[PATCH] doc: centrally document various ways spell `true` and `false`

[PATCH] doc: centrally document various ways spell `true` and `false`

[Junio C Hamano]

We do not seem to centrally document exhaustively ways to spell
Boolean values.

The description in the Environment Variables of git(1) section
assumes that the reader is already familiar with how "Boolean valued
configuration variables" are specified, without referring to
anything, so there is no way for the readers to find out more.

The description of `bool` in the section on "--type
<type>" in "git config --help" might be the place to do so, but it
is not telling us all that much.

The description of Boolean valued placeholders in the pretty formats
section of "git log --help" enumerates the possible values with "etc."
implying there may be other synonyms; shrink the list of samples and
instead refer to the canonical and authoritative source of truth, which
now is git-config(1).

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * Noticed while writing <xmqqfrkk1l4i.fsf@gitster.g>, a review for
   <bc0de52b59f289e1388f1581fcfa49453365e21a.camel@intelfx.name>

 Cc'ed Taylor, as the author of fb0dc3ba (builtin/config.c: support
 `--type=<type>` as preferred alias for `--<type>`, 2018-04-18) this
 patch butchers.

 Documentation/git-config.txt     | 4 +++-
 Documentation/git.txt            | 5 +++--
 Documentation/pretty-formats.txt | 8 ++++----
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git c/Documentation/git-config.txt w/Documentation/git-config.txt
index 3e420177c1..76042581ec 100644
--- c/Documentation/git-config.txt
+++ w/Documentation/git-config.txt
@@ -213,7 +213,9 @@ See also <<FILES>>.
 +
 Valid `<type>`'s include:
 +
-- 'bool': canonicalize values as either "true" or "false".
+- 'bool': canonicalize values `true`, `yes`,`on`, and positive
+  numbers as "true", and values `false`, `no`, `off` and `0` as
+  "false".
 - 'int': canonicalize values as simple decimal numbers. An optional suffix of
   'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or
   1073741824 upon input.
diff --git c/Documentation/git.txt w/Documentation/git.txt
index e89a91dd0d..c029a297db 100644
--- c/Documentation/git.txt
+++ w/Documentation/git.txt
@@ -472,8 +472,9 @@ Environment Variables
 ---------------------
 Various Git commands pay attention to environment variables and change
 their behavior.  The environment variables marked as "Boolean" take
-their values the same way as Boolean valued configuration variables, e.g.
-"true", "yes", "on" and positive numbers are taken as "yes".
+their values the same way as Boolean valued configuration variables, i.e.,
+"true", "yes", "on" and positive numbers are taken as "yes", while "false",
+"no", "off", and "0" are taken as "no".
 
 Here are the variables:
 
diff --git c/Documentation/pretty-formats.txt w/Documentation/pretty-formats.txt
index 8ee940b6a4..07475de8c3 100644
--- c/Documentation/pretty-formats.txt
+++ w/Documentation/pretty-formats.txt
@@ -339,10 +339,10 @@ insert an empty string unless we are traversing reflog entries (e.g., by
 decoration format if `--decorate` was not already provided on the command
 line.
 
-The boolean options accept an optional value `[=<bool-value>]`. The values
-`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
-sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
-option is given with no value, it's enabled.
+The boolean options accept an optional value `[=<bool-value>]`. The
+values taken by `--type=bool` git-config[1], like `yes` and `off`,
+are all accepted.  Giving a boolean option without `=<value>` is
+equivalent to giving it with `=true`.
 
 If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
 is inserted immediately before the expansion if and only if the

Re: [PATCH] doc: centrally document various ways spell `true` and `false`

[Eric Sunshine]

On Tue, Feb 11, 2025 at 12:21 PM Junio C Hamano <gitster@pobox.com> wrote:
> doc: centrally document various ways spell `true` and `false`

s/spell/to spell/

Re: [PATCH] doc: centrally document various ways spell `true` and `false`

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Tue, Feb 11, 2025 at 12:21 PM Junio C Hamano <gitster@pobox.com> wrote:
>> doc: centrally document various ways spell `true` and `false`
>
> s/spell/to spell/

Yes, indeed.  Thanks for sharp eyes.

Re: [PATCH] doc: centrally document various ways spell `true` and `false`

[Taylor Blau]

On Tue, Feb 11, 2025 at 09:20:07AM -0800, Junio C Hamano wrote:
>  Cc'ed Taylor, as the author of fb0dc3ba (builtin/config.c: support
>  `--type=<type>` as preferred alias for `--<type>`, 2018-04-18) this
>  patch butchers.

Wow, this is a blast from the past. I think this was one of my first
contributions to Git, and indeed:

    $ git log --oneline --author=Taylor.Blau --until=2018-04-18 | wc -l
    9

>  Documentation/git-config.txt     | 4 +++-
>  Documentation/git.txt            | 5 +++--
>  Documentation/pretty-formats.txt | 8 ++++----
>  3 files changed, 10 insertions(+), 7 deletions(-)
>
> diff --git c/Documentation/git-config.txt w/Documentation/git-config.txt
> index 3e420177c1..76042581ec 100644
> --- c/Documentation/git-config.txt
> +++ w/Documentation/git-config.txt
> @@ -213,7 +213,9 @@ See also <<FILES>>.
>  +
>  Valid `<type>`'s include:
>  +
> -- 'bool': canonicalize values as either "true" or "false".
> +- 'bool': canonicalize values `true`, `yes`,`on`, and positive
> +  numbers as "true", and values `false`, `no`, `off` and `0` as
> +  "false".

I agree with the rest of the patch, but is this true (no pun intended
;-))? I thought that we might canonicalize "yes" to "yes" if the value
we are asking about is already something other than a literal "true" or
"false", but I don't think we do:

    $ git.compile -c foo.bar=yes config --type=bool foo.bar
    true

So I do think that it is worth saying "you can spell 'true' as 'yes',
'1', ..." in the documentation, but I don't think that it is correct
that we'll canonicalize "yes" to "true" in the case described here.

Sorry that this took me so long to respond to. I think I must have
missed it when you wrote it and I only noticed it today while cleaning
up old emails.

Thanks,
Taylor

Re: [PATCH] doc: centrally document various ways spell `true` and `false`

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

>> +- 'bool': canonicalize values `true`, `yes`,`on`, and positive
>> +  numbers as "true", and values `false`, `no`, `off` and `0` as
>> +  "false".
> ...
> I agree with the rest of the patch, but is this true (no pun intended
> ;-))? I thought that we might canonicalize "yes" to "yes" if the value
> we are asking about is already something other than a literal "true" or
> "false", but I don't think we do:
>
>     $ git.compile -c foo.bar=yes config --type=bool foo.bar
>     true

Sorry, but you lost me.  Isn't the above demonstration of 'yes' you
gave getting canonicalized to 'true'?

	$ for v in yes 1 2 on
	> do
	>    git -c foo.bar=$v config --type=bool foo.bar
	> done
	true
	true
	true
	true

Or are you saying that the above documents what happens, but you
think the code is wrong to do so?


> So I do think that it is worth saying "you can spell 'true' as 'yes',
> '1', ..." in the documentation, but I don't think that it is correct
> that we'll canonicalize "yes" to "true" in the case described here.