threads / patch / 57478

patchfix: include the type flag in the cli docs

Subject: [PATCH] fix: include the type flag in the cli docs

## tl;dr

9 messages between Feb 26, 2022 and Mar 4, 2022. Diffs are folded; open one to read it.

replies: 8people: 4as markdown or json

Matheus Felipe via GitGitGadget· Feb 26, 2022, 05:34 UTC · lore
From: Matheus Felipe <matheusfelipeog@protonmail.com>

When the `git config --global --help` command is invoked, the cli documentation is shown in the terminal with a small error in one of the values of the Type group, which is the absence of the type flag in the `--type` argument. This commit fixes that.

Signed-off-by: Matheus Felipe <matheusfelipeog@protonmail.com>
---
    fix: include the type flag in the cli docs
    
    When the git config --global --help command is invoked, the cli
    documentation is shown in the terminal with a small error in one of the
    values of the Type group, which is the absence of the type flag in the
    --type argument:
    
    image
    [https://user-images.githubusercontent.com/50463866/155674905-01fcdf18-8f67-488a-b367-985040dfe57d.png]
    
    In the web documentation and man page:
    
    image
    [https://user-images.githubusercontent.com/50463866/155675353-4a39965a-875c-475c-829d-7849a982f5b9.png]
    image
    [https://user-images.githubusercontent.com/50463866/155675437-7283dbac-fff2-44b7-8733-7d5af375bce4.png]
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1220%2Fmatheusfelipeog%2Ffix%2Fgit-config-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1220/matheusfelipeog/fix/git-config-docs-v1
Pull-Request: https://github.com/git/git/pull/1220
 builtin/config.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to builtin/config.c +1 −1
diff --git a/builtin/config.c b/builtin/config.c
index 542d8d02b2b..2aea465466b 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -151,7 +151,7 @@ static struct option builtin_config_options[] = {
 	OPT_BIT(0, "get-color", &actions, N_("find the color configured: slot [default]"), ACTION_GET_COLOR),
 	OPT_BIT(0, "get-colorbool", &actions, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL),
 	OPT_GROUP(N_("Type")),
-	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
+	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
 	OPT_CALLBACK_VALUE(0, "bool", &type, N_("value is \"true\" or \"false\""), TYPE_BOOL),
 	OPT_CALLBACK_VALUE(0, "int", &type, N_("value is decimal number"), TYPE_INT),
 	OPT_CALLBACK_VALUE(0, "bool-or-int", &type, N_("value is --bool or --int"), TYPE_BOOL_OR_INT),

base-commit: dab1b7905d0b295f1acef9785bb2b9cbb0fdec84

-- 
gitgitgadget
Bagas Sanjaya· Feb 27, 2022, 04:29 UTC · re: Matheus Felipe via GitGitGadget · lore

Re: [PATCH] fix: include the type flag in the cli docs

On 26/02/22 12.34, Matheus Felipe via GitGitGadget wrote:
Show 8 quoted lines
> From: Matheus Felipe <matheusfelipeog@protonmail.com>
> 
> When the `git config --global --help` command is invoked,
> the cli documentation is shown in the terminal with a small
> error in one of the values of the Type group, which is the
> absence of the type flag in the `--type` argument.
> This commit fixes that.
> 
What about the commit message below?

``` The usage help for --type option of `git config` is missing `type` in the argument placeholder (`<>`). Add it. ```

> -	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
> +	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
The help should be `give the value the specified type`.
-- 
An old man doll... just what I always wanted! - Clara
Junio C Hamano· Feb 27, 2022, 19:48 UTC · re: Bagas Sanjaya · lore

Re: [PATCH] fix: include the type flag in the cli docs

Bagas Sanjaya <bagasdotme@gmail.com> writes:
Show 15 quoted lines
> On 26/02/22 12.34, Matheus Felipe via GitGitGadget wrote:
>> From: Matheus Felipe <matheusfelipeog@protonmail.com>
>> When the `git config --global --help` command is invoked,
>> the cli documentation is shown in the terminal with a small
>> error in one of the values of the Type group, which is the
>> absence of the type flag in the `--type` argument.
>> This commit fixes that.
>> 
>
> What about the commit message below?
>
> ```
> The usage help for --type option of `git config` is missing `type`
> in the argument placeholder (`<>`). Add it.
> ```

It is more concise, and at the same time points out the problem being addressed a lot more explicitly. Much better.

Show 5 quoted lines
>> -	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
>> +	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
>
>
> The help should be `give the value the specified type`.
I am not sure if this is much of an improvement.
    $ git config --type=bool junk.flag 0
    $ git config junk.flag
    false

uses the type information to turn "0" into "false" before it writes the value set to the variable to the file, while

    $ git config junk.flag 0
    $ git config junk.flag
    0
    $ git config --type=bool junk.flag
    false

shows that a stored value of "0" can be turned into "false" when showing. "Give the value the specified type" does not capture the essense in either direction.

    Before setting or showing, convert the value to its canonical
    representation according to the given type.
is what we want to convey, but it is quote a mouthful as-is.

Saying "Assume the value is of this type" would strongly imply "Convert ... to its canonical reporesentation", and the current "value is given this type" may be a close enough and shorter approximation of it. I dunno.

Ævar Arnfjörð Bjarmason· Feb 28, 2022, 22:42 UTC · re: Junio C Hamano · lore

Re: [PATCH] fix: include the type flag in the cli docs

On Sun, Feb 27 2022, Junio C Hamano wrote:
Show 55 quoted lines
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>
>> On 26/02/22 12.34, Matheus Felipe via GitGitGadget wrote:
>>> From: Matheus Felipe <matheusfelipeog@protonmail.com>
>>> When the `git config --global --help` command is invoked,
>>> the cli documentation is shown in the terminal with a small
>>> error in one of the values of the Type group, which is the
>>> absence of the type flag in the `--type` argument.
>>> This commit fixes that.
>>> 
>>
>> What about the commit message below?
>>
>> ```
>> The usage help for --type option of `git config` is missing `type`
>> in the argument placeholder (`<>`). Add it.
>> ```
>
> It is more concise, and at the same time points out the problem
> being addressed a lot more explicitly.  Much better.
>
>>> -	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
>>> +	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
>>
>>
>> The help should be `give the value the specified type`.
>
> I am not sure if this is much of an improvement.
>
>     $ git config --type=bool junk.flag 0
>     $ git config junk.flag
>     false
>
> uses the type information to turn "0" into "false" before it writes
> the value set to the variable to the file, while
>
>     $ git config junk.flag 0
>     $ git config junk.flag
>     0
>     $ git config --type=bool junk.flag
>     false
>
> shows that a stored value of "0" can be turned into "false" when
> showing.  "Give the value the specified type" does not capture the
> essense in either direction.
>
>     Before setting or showing, convert the value to its canonical
>     representation according to the given type.
>
> is what we want to convey, but it is quote a mouthful as-is.
>
> Saying "Assume the value is of this type" would strongly imply
> "Convert ... to its canonical reporesentation", and the current
> "value is given this type" may be a close enough and shorter
> approximation of it.  I dunno.
Perhaps:
	"coerce (on read and write) <value> to <type>"
or:
	"coerce (on read & write) <value> to <type>"
or:
	"coerce (on rw) <value> to <type>"
For the short help, depending on how verbose we'd like to be?

In any case a follow-up fix, just the "" to "type" being proposed here is orthagonal & looks good to me.

Matheus Felipe· Mar 4, 2022, 03:56 UTC · re: Ævar Arnfjörð Bjarmason · lore

Re: [PATCH] fix: include the type flag in the cli docs

Show 15 quoted lines
> On 26/02/22 12.34, Matheus Felipe via GitGitGadget wrote:
>
> > From: Matheus Felipe matheusfelipeog@protonmail.com
> > When the `git config --global --help` command is invoked,
> > the cli documentation is shown in the terminal with a small
> > error in one of the values of the Type group, which is the
> > absence of the type flag in the `--type` argument.
> > This commit fixes that.
>
> What about the commit message below?
>
> ```
> The usage help for --type option of `git config` is missing `type`
> in the argument placeholder (`<>`). Add it.
> ```
This commit message just got better, thanks. I will update with this message.
> > - OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
> > + OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
>
> The help should be `give the value the specified type`.
About the help message, I believe the current one is adequate, as Junio C Hamano well described.
It is also worth remembering that PR proposes a change from "" to "type" only, as recalled by Ævar Arnfjörð Bjarmason.
Matheus Felipe via GitGitGadget· Mar 4, 2022, 04:31 UTC · re: Matheus Felipe via GitGitGadget · lore

[PATCH v2] fix: include the type flag in the cli docs

From: Matheus Felipe <matheusfelipeog@protonmail.com>

The usage help for --type option of `git config` is missing `type` in the argument placeholder (`<>`). Add it.

Signed-off-by: Matheus Felipe <matheusfelipeog@protonmail.com>
---
    fix: include the type flag in the cli docs
    
    When the git config --global --help command is invoked, the cli
    documentation is shown in the terminal with a small error in one of the
    values of the Type group, which is the absence of the type flag in the
    --type argument:
    
    image
    [https://user-images.githubusercontent.com/50463866/155674905-01fcdf18-8f67-488a-b367-985040dfe57d.png]
    
    In the web documentation and man page:
    
    image
    [https://user-images.githubusercontent.com/50463866/155675353-4a39965a-875c-475c-829d-7849a982f5b9.png]
    image
    [https://user-images.githubusercontent.com/50463866/155675437-7283dbac-fff2-44b7-8733-7d5af375bce4.png]
    
    ------------------------------------------------------------------------
    
    Changes since v1:
    
     * Added a better commit message (as suggested by Bagas Sanjaya
       <bagasdotme@gmail.com>)
    
    ------------------------------------------------------------------------
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1220%2Fmatheusfelipeog%2Ffix%2Fgit-config-docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1220/matheusfelipeog/fix/git-config-docs-v2
Pull-Request: https://github.com/git/git/pull/1220
Range-diff vs v1:
 1:  7bc0abde8ff ! 1:  1550d29f5da fix: include the type flag in the cli docs
     @@ Metadata
       ## Commit message ##
          fix: include the type flag in the cli docs
      
     -    When the `git config --global --help` command is invoked,
     -    the cli documentation is shown in the terminal with a small
     -    error in one of the values of the Type group, which is the
     -    absence of the type flag in the `--type` argument.
     -    This commit fixes that.
     +    The usage help for --type option of `git config` is missing `type`
     +    in the argument placeholder (`<>`). Add it.
      
          Signed-off-by: Matheus Felipe <matheusfelipeog@protonmail.com>
      
 builtin/config.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to builtin/config.c +1 −1
diff --git a/builtin/config.c b/builtin/config.c
index 542d8d02b2b..2aea465466b 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -151,7 +151,7 @@ static struct option builtin_config_options[] = {
 	OPT_BIT(0, "get-color", &actions, N_("find the color configured: slot [default]"), ACTION_GET_COLOR),
 	OPT_BIT(0, "get-colorbool", &actions, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL),
 	OPT_GROUP(N_("Type")),
-	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
+	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
 	OPT_CALLBACK_VALUE(0, "bool", &type, N_("value is \"true\" or \"false\""), TYPE_BOOL),
 	OPT_CALLBACK_VALUE(0, "int", &type, N_("value is decimal number"), TYPE_INT),
 	OPT_CALLBACK_VALUE(0, "bool-or-int", &type, N_("value is --bool or --int"), TYPE_BOOL_OR_INT),

base-commit: dab1b7905d0b295f1acef9785bb2b9cbb0fdec84

-- 
gitgitgadget
Junio C Hamano· Mar 4, 2022, 07:45 UTC · re: Matheus Felipe via GitGitGadget · lore

Re: [PATCH v2] fix: include the type flag in the cli docs

"Matheus Felipe via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Subject: Re: [PATCH v2] fix: include the type flag in the cli docs

One more (hopefully final) nit. By reading the above alone (which is what people will see in "git shortlog --no-merges" output), you can not even guess which subcommand the "fix" is about, or if it is even a fix to the code, or just a documentation update.

I'd retitle it to
	config: correct "--type" option in "git config -h" output
> From: Matheus Felipe <matheusfelipeog@protonmail.com>
>
> The usage help for --type option of `git config` is missing `type`
> in the argument placeholder (`<>`). Add it.
Good.
Show 10 quoted lines
> diff --git a/builtin/config.c b/builtin/config.c
> index 542d8d02b2b..2aea465466b 100644
> --- a/builtin/config.c
> +++ b/builtin/config.c
> @@ -151,7 +151,7 @@ static struct option builtin_config_options[] = {
>  	OPT_BIT(0, "get-color", &actions, N_("find the color configured: slot [default]"), ACTION_GET_COLOR),
>  	OPT_BIT(0, "get-colorbool", &actions, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL),
>  	OPT_GROUP(N_("Type")),
> -	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
> +	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
Good again.
Thanks.  Will queue.
Matheus Felipe· Mar 4, 2022, 15:52 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] fix: include the type flag in the cli docs

Show 8 quoted lines
> One more (hopefully final) nit. By reading the above alone (which
> is what people will see in "git shortlog --no-merges" output), you
> can not even guess which subcommand the "fix" is about, or if it is
> even a fix to the code, or just a documentation update.
>
> I'd retitle it to
>
> config: correct "--type" option in "git config -h" output
You are right, this title is much better. I will update it.
Thank you very much, I learned a few things from this contribution.
Matheus Felipe via GitGitGadget· Mar 4, 2022, 16:15 UTC · re: Matheus Felipe via GitGitGadget · lore

[PATCH v3] config: correct "--type" option in "git config -h" output

From: Matheus Felipe <matheusfelipeog@protonmail.com>

The usage help for --type option of `git config` is missing `type` in the argument placeholder (`<>`). Add it.

Signed-off-by: Matheus Felipe <matheusfelipeog@protonmail.com>
---
    config: correct "--type" option in "git config -h" output
    
    When the git config --global --help command is invoked, the cli
    documentation is shown in the terminal with a small error in one of the
    values of the Type group, which is the absence of the type flag in the
    --type argument:
    
    image
    [https://user-images.githubusercontent.com/50463866/155674905-01fcdf18-8f67-488a-b367-985040dfe57d.png]
    
    In the web documentation and man page:
    
    image
    [https://user-images.githubusercontent.com/50463866/155675353-4a39965a-875c-475c-829d-7849a982f5b9.png]
    image
    [https://user-images.githubusercontent.com/50463866/155675437-7283dbac-fff2-44b7-8733-7d5af375bce4.png]
    
    ------------------------------------------------------------------------
    
    Changes since v1:
    
     * Added a better commit message (as suggested by Bagas Sanjaya
       <bagasdotme@gmail.com>)
     * Improve the title of the commit, to make it more explicit when viewed
       with git shortlog --no-merges (as suggested by Junio C Hamano
       <gitster@pobox.com>)
    
    ------------------------------------------------------------------------
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1220%2Fmatheusfelipeog%2Ffix%2Fgit-config-docs-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1220/matheusfelipeog/fix/git-config-docs-v3
Pull-Request: https://github.com/git/git/pull/1220
Range-diff vs v2:
 1:  1550d29f5da ! 1:  f0fff5f3597 fix: include the type flag in the cli docs
     @@ Metadata
      Author: Matheus Felipe <matheusfelipeog@protonmail.com>
      
       ## Commit message ##
     -    fix: include the type flag in the cli docs
     +    config: correct "--type" option in "git config -h" output
      
          The usage help for --type option of `git config` is missing `type`
          in the argument placeholder (`<>`). Add it.
 builtin/config.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to builtin/config.c +1 −1
diff --git a/builtin/config.c b/builtin/config.c
index 542d8d02b2b..2aea465466b 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -151,7 +151,7 @@ static struct option builtin_config_options[] = {
 	OPT_BIT(0, "get-color", &actions, N_("find the color configured: slot [default]"), ACTION_GET_COLOR),
 	OPT_BIT(0, "get-colorbool", &actions, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL),
 	OPT_GROUP(N_("Type")),
-	OPT_CALLBACK('t', "type", &type, "", N_("value is given this type"), option_parse_type),
+	OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
 	OPT_CALLBACK_VALUE(0, "bool", &type, N_("value is \"true\" or \"false\""), TYPE_BOOL),
 	OPT_CALLBACK_VALUE(0, "int", &type, N_("value is decimal number"), TYPE_INT),
 	OPT_CALLBACK_VALUE(0, "bool-or-int", &type, N_("value is --bool or --int"), TYPE_BOOL_OR_INT),

base-commit: dab1b7905d0b295f1acef9785bb2b9cbb0fdec84

-- 
gitgitgadget

← back to recent threads