Re: [PATCH] branch,checkout: fix --track documentation

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

René Scharfe <l.s.r@web.de> writes:

> Document that the accepted variants of the --track option are --track,
> --track=direct, and --track=inherit.  The equal sign in the latter two
> cannot be replaced with whitespace; in general optional arguments need
> to be attached firmly to their option.
>
> Put "direct" consistently before "inherit", if only for the reasons
> that the former is the default, explained first in the documentation,
> and comes before the latter alphabetically.

;-)  I see too many good reasons to modestly say "if only for" ;-)

> -'git branch' [--track [direct|inherit] | --no-track] [-f] <branchname> [<start-point>]
> +'git branch' [--track[=(direct|inherit)] | --no-track] [-f] <branchname> [<start-point>]

Good.

>  -t::
> ---track [inherit|direct]::
> +--track[=(direct|inherit)]::

Good.

> @@ -216,11 +216,11 @@ This option is only applicable in non-verbose mode.
>  	upstream when the new branch is checked out.
>  +
>  The exact upstream branch is chosen depending on the optional argument:
> -`--track` or `--track direct` means to use the start-point branch itself as the
> -upstream; `--track inherit` means to copy the upstream configuration of the
> -start-point branch.
> +`-t`, `--track`, or `--track=direct` means to use the start-point branch
> +itself as the upstream; `--track=inherit` means to copy the upstream
> +configuration of the start-point branch.

When "-x" and "--long-x" both do the same thing, we list both in the
heading but omit "-x" from the text, but in this case I fully agree
with the updated text as "-t" and "--track[=...]" work a bit
differently and there is no way to say "we want inherit" with "-t".

> -`--track direct` is the default when the start point is a remote-tracking branch.
> +`--track=direct` is the default when the start point is a remote-tracking branch.

Good.

> diff --git a/builtin/branch.c b/builtin/branch.c
> index 0c8d8a8827..4ce2a24754 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -638,7 +638,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
>  		OPT__VERBOSE(&filter.verbose,
>  			N_("show hash and subject, give twice for upstream branch")),
>  		OPT__QUIET(&quiet, N_("suppress informational messages")),
> -		OPT_CALLBACK_F('t', "track",  &track, N_("mode"),
> +		OPT_CALLBACK_F('t', "track",  &track, "(direct|inherit)",
>  			N_("set branch tracking configuration"),
>  			PARSE_OPT_OPTARG,
>  			parse_opt_tracking_mode),

Good.

> diff --git a/builtin/checkout.c b/builtin/checkout.c
> index 6a5dd2a2a2..0bc2e63510 100644
> --- a/builtin/checkout.c
> +++ b/builtin/checkout.c
> @@ -1549,7 +1549,7 @@ static struct option *add_common_switch_branch_options(
>  {
>  	struct option options[] = {
>  		OPT_BOOL('d', "detach", &opts->force_detach, N_("detach HEAD at named commit")),
> -		OPT_CALLBACK_F('t', "track",  &opts->track, N_("mode"),
> +		OPT_CALLBACK_F('t', "track",  &opts->track, "(direct|inherit)",
>  			N_("set branch tracking configuration"),
>  			PARSE_OPT_OPTARG,
>  			parse_opt_tracking_mode),

Good.

Thanks.