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@xxxxxx> > --- > 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.
