diff options
Diffstat (limited to 'Documentation/urls-remotes.adoc')
| -rw-r--r-- | Documentation/urls-remotes.adoc | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc index 9b10151198..57b1646d3e 100644 --- a/Documentation/urls-remotes.adoc +++ b/Documentation/urls-remotes.adoc @@ -92,5 +92,47 @@ git push uses: ------------ +[[UPSTREAM-BRANCHES]] +UPSTREAM BRANCHES +----------------- + +Branches in Git can optionally have an upstream remote branch. +Git defaults to using the upstream branch for remote operations, for example: + +* It's the default for `git pull` or `git fetch` with no arguments. +* It's the default for `git push` with no arguments, with some exceptions. + For example, you can use the `branch.<name>.pushRemote` option to push + to a different remote than you pull from, and by default with + `push.default=simple` the upstream branch you configure must have + the same name. +* Various commands, including `git checkout` and `git status`, will + show you how many commits have been added to your current branch and + the upstream since you forked from it, for example "Your branch and + 'origin/main' have diverged, and have 2 and 3 different commits each + respectively". + +The upstream is stored in `.git/config`, in the "remote" and "merge" +fields. For example, if `main`'s upstream is `origin/main`: +------------ +[branch "main"] + remote = origin + merge = refs/heads/main +------------ +You can set an upstream branch explicitly with +`git push --set-upstream <remote> <branch>` +but Git will often automatically set the upstream for you, for example: + +* When you clone a repository, Git will automatically set the upstream + for the default branch. +* If you have the `push.autoSetupRemote` configuration option set, + `git push` will automatically set the upstream the first time you push + a branch. +* Checking out a remote-tracking branch with `git checkout <branch>` + will automatically create a local branch with that name and set + the upstream to the remote branch. + +[NOTE] +Upstream branches are sometimes referred to as "tracking information", +as in "set the branch's tracking information". |