Merge branch 'js/branch-track-inherit'

[thirdparty/git.git] / Documentation / git-branch.txt

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 8af42eff895c391994ef9e8ea1e4e7004f5d493e..2d52ae396b0c3029dc371c80853725a3a492e596 100644 (file)
--- 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 | --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,24 +206,34 @@ This option is only applicable in non-verbose mode.
        Display the full sha1s in the output listing rather than abbreviating them.
 
 -t::
---track::
+--track [inherit|direct]::
        When creating a new branch, set up `branch.<name>.remote` and
-       `branch.<name>.merge` configuration entries to mark the
-       start-point branch as "upstream" from the new branch. This
+       `branch.<name>.merge` configuration entries to set "upstream" tracking
+       configuration for the new branch. This
        configuration will tell git to show the relationship between the
        two branches in `git status` and `git branch -v`. Furthermore,
        it directs `git pull` without arguments to pull from the
        upstream when the new branch is checked out.
 +
-This behavior is the default when the start point is a remote-tracking branch.
+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.
++
+`--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
-start-point is either a local or remote-tracking branch.
+start-point is either a local or remote-tracking branch. Set it to
+`inherit` if you want to copy the tracking configuration from the
+branch point.
++
+See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
+how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
 
 --no-track::
        Do not set up "upstream" configuration, even if the
-       branch.autoSetupMerge configuration variable is true.
+       branch.autoSetupMerge configuration variable is set.
 
 --set-upstream::
        As this option had confusing syntax, it is no longer supported.