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

From: Junio C Hamano <[email-masked]>
Date: Thu, 20 Jan 2022 10:38:21 -0800

Ævar Arnfjörð Bjarmason <[email-masked]> 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.