incorrect 'git (checkout|branch) -h' output with new --track modes (was: [PATCH v8 2/3] branch: add flags and config to inherit tracking)

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Dec 20 2021, Josh Steadmon wrote:

> Since we've added an argument to "--track", also add "--track=direct" as
> another way to explicitly get the original "--track" behavior ("--track"
> without an argument still works as well).
> [...]
> -'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
> +'git branch' [--track [direct|inherit] | --no-track] [-f] <branchname> [<start-point>]

The usage info here is correct...

> ---track::
> +--track [inherit|direct]::

...as is this...

> -		OPT_SET_INT('t', "track",  &track, N_("set up tracking mode (see git-pull(1))"),
> -			BRANCH_TRACK_EXPLICIT),
> +		OPT_CALLBACK_F('t', "track",  &track, "direct|inherit",
> +			N_("set branch tracking configuration"),
> +			PARSE_OPT_OPTARG | PARSE_OPT_LITERAL_ARGHELP,
> +			parse_opt_tracking_mode),
....

>  	struct option options[] = {
>  		OPT_BOOL('d', "detach", &opts->force_detach, N_("detach HEAD at named commit")),
> -		OPT_SET_INT('t', "track",  &opts->track, N_("set upstream info for new branch"),
> -			BRANCH_TRACK_EXPLICIT),
> +		OPT_CALLBACK_F('t', "track",  &opts->track, "direct|inherit",

... but these are not. I.e. we'll emit:

    -t, --track[=direct|inherit]
                          set branch tracking configuration

I.e. implying that the valid uses are --track, --track=direct, and
--trackinherit.

It looks like the problem is (ab)use of PARSE_OPT_OPTARG, i.e. it was
never meant for an enumeration of possible values, but for something
like N_("mode"). It could be made to support that, but it would require
some light patching of the releant bits of parse-options.c.

The PARSE_OPT_LITERAL_ARGHELP should also be dropped if it's fixed to
use a string like "mode".

> +			N_("set up tracking mode (see git-pull(1))"),

Aside: In v5 the other reference was changed from using the
"git-pull(1)" manpage syntax. See
https://lore.kernel.org/git/cover.1638859949.git.steadmon@google.com/;
It looks like this one should be changed too, but was missed.

> +			PARSE_OPT_OPTARG | PARSE_OPT_LITERAL_ARGHELP,
> +			parse_opt_tracking_mode),