Re: [PATCH] branch,checkout: fix --track usage strings

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jan 21, 2022, 11:27 UTC
Message-ID: <220121.86ee51l3jd.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqbl06jlr6.fsf@gitster.g>

On Thu, Jan 20 2022, Junio C Hamano wrote:

Show 37 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> With that we'll now emit:
>>     
>>     $ ./git add -h 2>&1|grep chmod
>>         --chmod[=](+|-)x      override the executable bit of the listed files
>> ...
>> But the usage output stated that the "=" was mandatory before.
>
> I am not sure if it is healthy to be _that_ strict when interpreting
> the boilerplate elements in the output.  Between "git add -h" that
> gives
>
>     (1) git add --chmod( |=)(+|-)x
>     (2) git add --chmod=(+|-)x
>
> I would prefer the latter 10x as much as the former.  The choice
> "You can give either plus or minus" is very much what the reader
> must understand and it is worth reminding in the help.  Compared to
> that, "You can use the stuck form that is recommended by gitcli
> documentation when giving the argument to the --chmod option, or you
> can give the argument to the option as a separate command line
> argument", while technically correct, is not a choice that is worth
> cluttering the output and making it harder to read.
>
> To put it differently, the choice (+|-) is something the user needs
> to pick correctly to make what they want to happen happen.  On the
> other hand, the choice ( |=) is not.  As this is a boilerplate
> choice that is shared by any and all options that take an argument,
> once you are aware that stuck form is recommended but that separate
> form is also accepted, you'd see "git add --chmod=blah" in the help
> and would not hesitate to type "git add --chmod blah".  And if you
> are not aware of the existence of the alternative, nothing is lost.
> You can type '=' and see what you want to see happen happen.
>
> Not cluttering the help text with an extra choice that the user does
> not have to make has a value.

I.e. if we're not going for pedantic accuracy you'd prefer the below diff instead?

I.e. when an option doesn't take an optional argument we're going out of our way to say that you can omit the "=", but we can instead just include it and have the the explanation in gitcli(7) about when "=" is optional suffice.

Also, with the sh completion if you do "git add --chm<TAB>" it expands
it to "git add --chmod=", i.e. the cursor is left after the "=" that's
not shown in the "git add -h". So always including it would be
consistent with that.
    
    diff --git a/parse-options.c b/parse-options.c
    index a8283037be9..75c345bb738 100644
    --- a/parse-options.c
    +++ b/parse-options.c
    @@ -916,7 +916,7 @@ static int usage_argh(const struct option *opts, FILE *outfile)
                    else
                            s = literal ? "[%s]" : "[<%s>]";
            else
    -               s = literal ? " %s" : " <%s>";
    +               s = literal ? "=%s" : "=<%s>";
            return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("..."));
     }
     
Just this patch will make getopts test fail, because we'll need
e.g. this test_cmp adjusted:
    
    + diff -u expect output
    --- expect      2022-01-21 11:31:17.395492260 +0000
    +++ output      2022-01-21 11:31:17.395492260 +0000
    @@ -5,7 +5,7 @@
     
         -h, --help            show the help
         --foo                 some nifty option --foo
    -    --bar ...             some cool option --bar with an argument
    +    --bar=...             some cool option --bar with an argument
         -b, --baz             a short and long option
     
     An option group Header
    @@ -13,20 +13,20 @@
         -d, --data[=...]      short and long option with an optional argument
     
     Argument hints
    -    -B <arg>              short option required argument
    -    --bar2 <arg>          long option required argument
    -    -e, --fuz <with-space>
    +    -B=<arg>              short option required argument
    +    --bar2=<arg>          long option required argument
    +    -e, --fuz=<with-space>
                               short and long option required argument
         -s[<some>]            short option optional argument
         --long[=<data>]       long option optional argument
         -g, --fluf[=<path>]   short and long option optional argument
    -    --longest <very-long-argument-hint>
    +    --longest=<very-long-argument-hint>
                               a very long argument hint
    -    --pair <key=value>    with an equals sign in the hint
    +    --pair=<key=value>    with an equals sign in the hint
         --aswitch             help te=t contains? fl*g characters!`
    -    --bswitch <hint>      hint has trailing tab character
    +    --bswitch=<hint>      hint has trailing tab character
         --cswitch             switch has trailing tab character
    -    --short-hint <a>      with a one symbol hint
    +    --short-hint=<a>      with a one symbol hint

It's arguably a bit odd to see the "=" for those that have !opts->long_name, but on the other hand I can't think of a reason other than it looking unusual to me for why we wouldn't include the "=" there for consistency.

It's odd that we don't have the short options in --git-completion-helper at all, so "git am -C<tab>" isn't completed", but looking at show_gitcomp() we'd need some further adjusting to make that work.