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

[Junio C Hamano <gitster@pobox.com>]

Josh Steadmon <steadmon@google.com> writes:

> As Ævar pointed out in [1], the use of PARSE_OPT_LITERAL_ARGHELP with a
> list of allowed parameters is not recommended. Both git-branch and
> git-checkout were changed in d311566 (branch: add flags and config to
> inherit tracking, 2021-12-20) to use this discouraged combination for
> their --track flags.

(tl;dr) I'll take this as-is and hopefully I can fast-track it in
time before tagging -rc2 tomorrow.

Having said that, here is what parse-options.h describes this flag
bit:

 *   PARSE_OPT_LITERAL_ARGHELP: says that argh shouldn't be enclosed in brackets
 *				(i.e. '<argh>') in the help message.
 *				Useful for options with multiple parameters.

Notice that this bit actually is meant "for options with multiple
parameters"?  The recommendation given to you might not be showing
the right way.

Looking at "git grep -C2 OPT_LITERAL_ARGHELP \*.c" output, I suspect
that a better solution may be to enclose "direct|inherit" in a pair
of parentheses, i.e. "(direct|inherit)".  That mimics the way how
"git am --show-current-patch[=(diff|raw)]" does it.

Then we would show

	--track[=(direct|inherit)]

instead of

	--track[=<mode>]

which means that ...

> Fix this by removing PARSE_OPT_LITERAL_ARGHELP, and changing the arghelp
> to simply be "mode". Users may discover allowed values in the manual
> pages.

... users won't have to visit the manual page only to find out what
modes we support.

In any case, the lesson should not be lost in the list archive.  To
help future developers from the same trouble, we should leave a note
to revisit the above description of the flag bit in parse-options.h
later, possibly after the 2.35 final, to see if we can improve it
(both the description and/or the behaviour of the code when it sees
the flag bit).

Thanks.