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

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

On Thu, Jan 20 2022, René Scharfe wrote:

> 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.
>
> Mention both modes in the short help so that readers don't have to look
> them up in the full documentation.  They are literal strings and thus
> untranslatable.  PARSE_OPT_LITERAL_ARGHELP is inferred due to the pipe
> and parenthesis characters, so we don't have to provide that flag
> explicitly.
>
> Mention that -t has the same effect as --track and --track=direct.
> There is no way to specify inherit mode using the short option, because
> short options generally don't accept optional arguments.
>
> Signed-off-by: René Scharfe <l.s.r@web.de>
> ---
>  Documentation/git-branch.txt   | 12 ++++++------
>  Documentation/git-checkout.txt |  2 +-
>  builtin/branch.c               |  2 +-
>  builtin/checkout.c             |  2 +-
>  4 files changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 2d52ae396b..731e340cbc 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -16,7 +16,7 @@ SYNOPSIS
>  	[--points-at <object>] [--format=<format>]
>  	[(-r | --remotes) | (-a | --all)]
>  	[--list] [<pattern>...]
> -'git branch' [--track [direct|inherit] | --no-track] [-f] <branchname> [<start-point>]
> +'git branch' [--track[=(direct|inherit)] | --no-track] [-f] <branchname> [<start-point>]
>  'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
>  'git branch' --unset-upstream [<branchname>]
>  'git branch' (-m | -M) [<oldbranch>] <newbranch>
> @@ -206,7 +206,7 @@ This option is only applicable in non-verbose mode.
>  	Display the full sha1s in the output listing rather than abbreviating them.
>
>  -t::
> ---track [inherit|direct]::
> +--track[=(direct|inherit)]::
>  	When creating a new branch, set up `branch.<name>.remote` and
>  	`branch.<name>.merge` configuration entries to set "upstream" tracking
>  	configuration for the new branch. This
> @@ -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.
>  +
> -`--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.
>  Set the branch.autoSetupMerge configuration variable to `false` if you
>  want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track`
>  were given. Set it to `always` if you want this behavior when the
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index 2a90ea6cd0..9f37e22e13 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -156,7 +156,7 @@ of it").
>  	linkgit:git-branch[1] for details.
>
>  -t::
> ---track [direct|inherit]::
> +--track[=(direct|inherit)]::

These changes (and the below) all look good to me. Thanks for fixing
this.

>  	When creating a new branch, set up "upstream" configuration. See
>  	"--track" in linkgit:git-branch[1] for details.

As a side-note this "--track" reference is incorrect, and has been since
d3115660b4c (branch: add flags and config to inherit tracking,
2021-12-20), i.e. it should now mention "--track[=(direct|inherit)]".

But as we're not explicitly cross-linking anything here with the
relevant syntax I think leaving it as-is is fine, the user would also
find it with a substring search.