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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 20, 2022, 18:38 UTC
Message-ID: <xmqqbl06jlr6.fsf@gitster.g>
In-Reply-To: <220120.86zgnqli9v.gmgdl@evledraar.gmail.com>

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

Show 6 quoted lines

> 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.