From d3115660b4cc4b1a32e77ddfd289afde5e4b94d8 Mon Sep 17 00:00:00 2001 From: Josh Steadmon Date: Mon, 20 Dec 2021 19:30:23 -0800 Subject: branch: add flags and config to inherit tracking It can be helpful when creating a new branch to use the existing tracking configuration from the branch point. However, there is currently not a method to automatically do so. Teach git-{branch,checkout,switch} an "inherit" argument to the "--track" option. When this is set, creating a new branch will cause the tracking configuration to default to the configuration of the branch point, if set. For example, if branch "main" tracks "origin/main", and we run `git checkout --track=inherit -b feature main`, then branch "feature" will track "origin/main". Thus, `git status` will show us how far ahead/behind we are from origin, and `git pull` will pull from origin. This is particularly useful when creating branches across many submodules, such as with `git submodule foreach ...` (or if running with a patch such as [1], which we use at $job), as it avoids having to manually set tracking info for each submodule. 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). Finally, teach branch.autoSetupMerge a new "inherit" option. When this is set, "--track=inherit" becomes the default behavior. [1]: https://lore.kernel.org/git/20180927221603.148025-1-sbeller@google.com/ Signed-off-by: Josh Steadmon Signed-off-by: Junio C Hamano --- Documentation/git-branch.txt | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) (limited to 'Documentation/git-branch.txt') diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 5449767121..75beea7bac 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -16,7 +16,7 @@ SYNOPSIS [--points-at ] [--format=] [(-r | --remotes) | (-a | --all)] [--list] [...] -'git branch' [--track | --no-track] [-f] [] +'git branch' [--track [direct|inherit] | --no-track] [-f] [] 'git branch' (--set-upstream-to= | -u ) [] 'git branch' --unset-upstream [] 'git branch' (-m | -M) [] @@ -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..remote` and - `branch..merge` configuration entries to mark the - start-point branch as "upstream" from the new branch. This + `branch..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..remote` and `branch..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. -- cgit v1.3