Josh Steadmon <steadmon@xxxxxxxxxx> 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.
