[PATCH] doc: note that interactive.singleKey is disabled by default

[PATCH] doc: note that interactive.singleKey is disabled by default

[Dragan Simic]

Make it clear that the interactive.singleKey configuration option is disabled
by default.  This should eliminate any associated doubts.

Signed-off-by: Dragan Simic <dsimic@manjaro.org>
---
 Documentation/config/interactive.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt
index 5cc26555f19a..067496d77cea 100644
--- a/Documentation/config/interactive.txt
+++ b/Documentation/config/interactive.txt
@@ -5,6 +5,7 @@ interactive.singleKey::
 	linkgit:git-add[1], linkgit:git-checkout[1],
 	linkgit:git-restore[1], linkgit:git-commit[1],
 	linkgit:git-reset[1], and linkgit:git-stash[1].
+	This is disabled by default.
 
 interactive.diffFilter::
 	When an interactive command (such as `git add --patch`) shows

Re: [PATCH] doc: note that interactive.singleKey is disabled by default

[Rubén Justo]

On Wed, May 22, 2024 at 09:34:16AM +0200, Dragan Simic wrote:
> Make it clear that the interactive.singleKey configuration option is disabled
> by default.  This should eliminate any associated doubts.
> 
> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
> ---
>  Documentation/config/interactive.txt | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt
> index 5cc26555f19a..067496d77cea 100644
> --- a/Documentation/config/interactive.txt
> +++ b/Documentation/config/interactive.txt
> @@ -5,6 +5,7 @@ interactive.singleKey::
>  	linkgit:git-add[1], linkgit:git-checkout[1],
>  	linkgit:git-restore[1], linkgit:git-commit[1],
>  	linkgit:git-reset[1], and linkgit:git-stash[1].
> +	This is disabled by default.

I'm on the fence if it needs to be said explicitly.  But, I'll add
that it has been so since it was introduced in ca6ac7f135 (add -p:
prompt for single characters, 2009-02-05).

Thank you for your attention to detail.

>  
>  interactive.diffFilter::
>  	When an interactive command (such as `git add --patch`) shows

Re: [PATCH] doc: note that interactive.singleKey is disabled by default

[Junio C Hamano]

Dragan Simic <dsimic@manjaro.org> writes:

> diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt
> index 5cc26555f19a..067496d77cea 100644
> --- a/Documentation/config/interactive.txt
> +++ b/Documentation/config/interactive.txt
> @@ -5,6 +5,7 @@ interactive.singleKey::
>  	linkgit:git-add[1], linkgit:git-checkout[1],
>  	linkgit:git-restore[1], linkgit:git-commit[1],
>  	linkgit:git-reset[1], and linkgit:git-stash[1].
> +	This is disabled by default.

Hmph, an optional configuration is optional because the lack of it
means the feature behind it does not trigger.

While it makes tons of sense to mention what the default is when
there are more than true or false choices (e.g. "defaults to never,
among possible choices never/local/remote/always"), or if it
defaults to true and the knob is to opt out of it, it feels like it
adds unnecesary noise to say "defaults to off" for a configuration
that is clearly a Boolean.

So I dunno.

Re: [PATCH] doc: note that interactive.singleKey is disabled by default

[Dragan Simic]

On 2024-05-22 20:28, Junio C Hamano wrote:
> Dragan Simic <dsimic@manjaro.org> writes:
> 
>> diff --git a/Documentation/config/interactive.txt 
>> b/Documentation/config/interactive.txt
>> index 5cc26555f19a..067496d77cea 100644
>> --- a/Documentation/config/interactive.txt
>> +++ b/Documentation/config/interactive.txt
>> @@ -5,6 +5,7 @@ interactive.singleKey::
>>  	linkgit:git-add[1], linkgit:git-checkout[1],
>>  	linkgit:git-restore[1], linkgit:git-commit[1],
>>  	linkgit:git-reset[1], and linkgit:git-stash[1].
>> +	This is disabled by default.
> 
> Hmph, an optional configuration is optional because the lack of it
> means the feature behind it does not trigger.
> 
> While it makes tons of sense to mention what the default is when
> there are more than true or false choices (e.g. "defaults to never,
> among possible choices never/local/remote/always"), or if it
> defaults to true and the knob is to opt out of it, it feels like it
> adds unnecesary noise to say "defaults to off" for a configuration
> that is clearly a Boolean.
> 
> So I dunno.

Let's have a look at a rather suitable (and to me, a bit inspiring)
excerpt from the git-config(1) man page:

   interactive.singleKey
      In interactive commands, allow the user to provide one-letter
      input with a single key (i.e., without hitting enter).
      Currently this is used by the --patch mode of git-add(1),
      git-checkout(1), git-restore(1), git-commit(1), git-reset(1),
      and git-stash(1). Note that this setting is silently ignored
      if portable keystroke input is not available; requires the
      Perl module Term::ReadKey.

   [...]

   log.abbrevCommit
      If true, makes git-log(1), git-show(1), and git-whatchanged(1)
      assume --abbrev-commit. You may override this option with
      --no-abbrev-commit.

With this in mind, I think that rewording the opening sentence for
the description of interactive.singleKey like this would make sense:

   interactive.singleKey
      If true, allow the user to provide one-letter input with a
      single key (i.e., without hitting Enter key) in interactive
      commands.
      [...]

Thoughts?  It would be more consistent and a bit more clear, without
putting too much stress on the actual default value.

Re: [PATCH] doc: note that interactive.singleKey is disabled by default

[Junio C Hamano]

Dragan Simic <dsimic@manjaro.org> writes:

>   interactive.singleKey
>      If true, allow the user to provide one-letter input with a
>      single key (i.e., without hitting Enter key) in interactive
>      commands.
>      [...]
>
> Thoughts?  It would be more consistent and a bit more clear, without
> putting too much stress on the actual default value.

"When set to true" or "when configured to true" is much better than
"defaults to true".

I am ambivalent about "If true", though.  It still leaves it open
for some mysterious "default" mechanism giving the value true
without user doing anything explicitly.

Re: [PATCH] doc: note that interactive.singleKey is disabled by default

[Dragan Simic]

On 2024-05-22 22:45, Junio C Hamano wrote:
> Dragan Simic <dsimic@manjaro.org> writes:
> 
>>   interactive.singleKey
>>      If true, allow the user to provide one-letter input with a
>>      single key (i.e., without hitting Enter key) in interactive
>>      commands.
>>      [...]
>> 
>> Thoughts?  It would be more consistent and a bit more clear, without
>> putting too much stress on the actual default value.
> 
> "When set to true" or "when configured to true" is much better than
> "defaults to true".
> 
> I am ambivalent about "If true", though.  It still leaves it open
> for some mysterious "default" mechanism giving the value true
> without user doing anything explicitly.

Makes sense.  I'll send the v2 of this patch with "when set to true"
in use, possibly with another patch that addresses already existing
instances of "if true", for consistency.