[PATCH] doc: clarify "config --bool" behaviour with empty values

[PATCH] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

`git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
`false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
t1300-repo-config.sh since 09bc098c2.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/config.txt | 3 ++-
 Documentation/git.txt    | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..d3261006b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -221,7 +221,8 @@ boolean::
 		is taken as true.
 
        false;; Boolean false can be spelled as `no`, `off`,
-		`false`, or `0`.
+		`false`, `0`, no value (but still with `=`) or the
+		empty string.
 +
 When converting value to the canonical form using `--bool` type
 specifier; 'git config' will ensure that the output is "true" or
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 7dd5e0328..6e3a6767e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -75,7 +75,8 @@ example the following invocations are equivalent:
 Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
 `foo.bar` to the boolean true value (just like `[foo]bar` would in a
 config file). Including the equals but with an empty value (like `git -c
-foo.bar= ...`) sets `foo.bar` to the empty string.
+foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
+--bool` will convert to `false`.
 
 --exec-path[=<path>]::
 	Path to wherever your core Git programs are installed.
-- 
2.13.3

Re: [PATCH] doc: clarify "config --bool" behaviour with empty values

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> `git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
> `false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
> t1300-repo-config.sh since 09bc098c2.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/config.txt | 3 ++-
>  Documentation/git.txt    | 3 ++-
>  2 files changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index d5c9c4cab..d3261006b 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -221,7 +221,8 @@ boolean::
>  		is taken as true.
>  
>         false;; Boolean false can be spelled as `no`, `off`,
> -		`false`, or `0`.
> +		`false`, `0`, no value (but still with `=`) or the
> +		empty string.

Thanks for noticing that it was a problem not spelling out that an
empty string means false.  We do need to spell it out.

However, I think this "no value (but still with '=')" is making it
more confusing than necessary for two reasons.

(1) The notation

	[section] var =

    is a perfectly valid way to spell an empty string, and is *not*
    a way to say "section.var has no value".

(2) In fact there is no way to say "section.var has no value", which
    is an often lamented inconvenience, because sometimes people may
    have their own setting in ~/.gitconfig and want to override it
    in the repository specific .git/config but do the overriding not
    with a specific value but by saying "pretend as if there were no
    setting in lower precedence configuration files like
    ~/.gitconfig".  If we ever fix this and introduce some syntax to
    mean "the variable has no value", it will become necessary to
    update the above description, but I am sure nobody will remember
    it.

I notice that in this Values section (where the boolean:: is the
first entry) there is no mention on how to spell a string value.

Perhaps something like this?

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab6..7580088bec 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -210,6 +210,14 @@ Values of many variables are treated as a simple string, but there
 are variables that take values of specific types and there are rules
 as to how to spell them.
 
+string::
+
+	A variable can take a string value, which can be quoted with
+	double quotes and backslashes as outlined in the Syntax
+	section above.  Note that it is sufficient to say 'name ='
+	without anything after the equal sign to spell an empty
+	string.
+
 boolean::
 
        When a variable is said to take a boolean value, many
@@ -221,7 +229,7 @@ boolean::
 		is taken as true.
 
        false;; Boolean false can be spelled as `no`, `off`,
-		`false`, or `0`.
+		`false`, or `0`.  An empty string can also be used.
 +
 When converting value to the canonical form using `--bool` type
 specifier; 'git config' will ensure that the output is "true" or

Re: [PATCH] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

Am 14.08.2017 um 19:53 schrieb Junio C Hamano:
> Andreas Heiduk <asheiduk@gmail.com> writes:
> 
>> `git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
>> `false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
>> t1300-repo-config.sh since 09bc098c2.
>>
>> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
>> ---
>>  Documentation/config.txt | 3 ++-
>>  Documentation/git.txt    | 3 ++-
>>  2 files changed, 4 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index d5c9c4cab..d3261006b 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -221,7 +221,8 @@ boolean::
>>  		is taken as true.
>>  
>>         false;; Boolean false can be spelled as `no`, `off`,
>> -		`false`, or `0`.
>> +		`false`, `0`, no value (but still with `=`) or the
>> +		empty string.
> 
[...]
 
> However, I think this "no value (but still with '=')" is making it
> more confusing than necessary for two reasons.
[...]
 
> I notice that in this Values section (where the boolean:: is the
> first entry) there is no mention on how to spell a string value.

I assumed this is due to the pretext of the definition list:

	Values of many variables are treated as a simple string, but there
	are variables that take values of specific types and there are rules
	as to how to spell them.

After that I would NOT expect string values to be "specific". Also: If string 
values are explained here in the "Values" section, the line-breaking and escape 
sequences syntax should be here too.

So my (minimal) suggestion is:

       false;; Boolean false literals are `no`, `off`,
                `false`, `0` and the empty string.

I'll adapt `true` in the same style and resend a patch.

[PATCH v2] doc: clarify "config --bool" behaviour with empty values

[Andreas Heiduk]

`git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
`false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
t1300-repo-config.sh since 09bc098c2.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/config.txt | 10 +++++-----
 Documentation/git.txt    |  3 ++-
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..478b9431e 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -216,15 +216,15 @@ boolean::
        synonyms are accepted for 'true' and 'false'; these are all
        case-insensitive.
 
-       true;; Boolean true can be spelled as `yes`, `on`, `true`,
-		or `1`.  Also, a variable defined without `= <value>`
+	true;; Boolean true literals are `yes`, `on`, `true`,
+		and `1`.  Also, a variable defined without `= <value>`
 		is taken as true.
 
-       false;; Boolean false can be spelled as `no`, `off`,
-		`false`, or `0`.
+	false;; Boolean false literals are `no`, `off`, `false`,
+		`0` and the empty string.
 +
 When converting value to the canonical form using `--bool` type
-specifier; 'git config' will ensure that the output is "true" or
+specifier, 'git config' will ensure that the output is "true" or
 "false" (spelled in lowercase).
 
 integer::
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 7dd5e0328..6e3a6767e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -75,7 +75,8 @@ example the following invocations are equivalent:
 Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
 `foo.bar` to the boolean true value (just like `[foo]bar` would in a
 config file). Including the equals but with an empty value (like `git -c
-foo.bar= ...`) sets `foo.bar` to the empty string.
+foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
+--bool` will convert to `false`.
 
 --exec-path[=<path>]::
 	Path to wherever your core Git programs are installed.
-- 
2.14.1

Re: [PATCH v2] doc: clarify "config --bool" behaviour with empty values

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> `git config --bool xxx.yyy` returns `true` for `[xxx]yyy` but
> `false` for `[xxx]yyy=` or `[xxx]yyy=""`.  This is tested in
> t1300-repo-config.sh since 09bc098c2.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/config.txt | 10 +++++-----
>  Documentation/git.txt    |  3 ++-
>  2 files changed, 7 insertions(+), 6 deletions(-)

This looks good to me.  Will queue.



> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index d5c9c4cab..478b9431e 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -216,15 +216,15 @@ boolean::
>         synonyms are accepted for 'true' and 'false'; these are all
>         case-insensitive.
>  
> -       true;; Boolean true can be spelled as `yes`, `on`, `true`,
> -		or `1`.  Also, a variable defined without `= <value>`
> +	true;; Boolean true literals are `yes`, `on`, `true`,
> +		and `1`.  Also, a variable defined without `= <value>`
>  		is taken as true.
>  
> -       false;; Boolean false can be spelled as `no`, `off`,
> -		`false`, or `0`.
> +	false;; Boolean false literals are `no`, `off`, `false`,
> +		`0` and the empty string.
>  +
>  When converting value to the canonical form using `--bool` type
> -specifier; 'git config' will ensure that the output is "true" or
> +specifier, 'git config' will ensure that the output is "true" or
>  "false" (spelled in lowercase).
>  
>  integer::
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 7dd5e0328..6e3a6767e 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -75,7 +75,8 @@ example the following invocations are equivalent:
>  Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
>  `foo.bar` to the boolean true value (just like `[foo]bar` would in a
>  config file). Including the equals but with an empty value (like `git -c
> -foo.bar= ...`) sets `foo.bar` to the empty string.
> +foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
> +--bool` will convert to `false`.
>  
>  --exec-path[=<path>]::
>  	Path to wherever your core Git programs are installed.

Re: [PATCH] doc: clarify "config --bool" behaviour with empty values

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

>> However, I think this "no value (but still with '=')" is making it
>> more confusing than necessary for two reasons.
> [...]
>  
>> I notice that in this Values section (where the boolean:: is the
>> first entry) there is no mention on how to spell a string value.
>
> I assumed this is due to the pretext of the definition list:
>
> 	Values of many variables are treated as a simple string, but there
> 	are variables that take values of specific types and there are rules
> 	as to how to spell them.

I assumed so too.  

But if you knew that "[section] var =" is a valid way to spell an
empty string, I'd thought that you wouldn't have written "no value
but still with '=')" there.

The description for "true" (i.e. "[section] var" and nothing else)
is also spelled out perfectly well in the Syntax section, but it is
duplicated in Values section.  I think that it is a good thing to
have the complete picture in a single Values section, without
assuming readers to know what is in the other Syntax section.

So if it bothers you to have a non-specific "string" description in
the Values section, I think it would be more helpful to update the
pretext so that including the description of a simple string there
does not look unnatural, IMHO.