diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc index 9b10151198..dba5adeb58 100644 --- a/Documentation/urls-remotes.adoc +++ b/Documentation/urls-remotes.adoc @@ -92,5 +92,44 @@ 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..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 ` or `git branch --track`, +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 ` + 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".