Git Reference ยท Concepts
Tracking branches
Understand Git upstream tracking: remote-tracking branches, branch.<name>.remote and merge settings, ahead/behind counts and setting an upstream.
Two similar ideas share the word "tracking", and mixing them up causes a lot of confusion.
A remote-tracking branch such as origin/main is a read-only bookmark in your repository that remembers where main was on the remote the last time you fetched. You never commit to it directly; git fetch moves it.
A tracking relationship (the upstream of a local branch) is a setting that links a local branch such as main to a remote-tracking branch such as origin/main. It is what lets plain git pull, git push and git status know which remote branch to talk to, and what produces messages like "Your branch is ahead of 'origin/main' by 2 commits".
git branch -u origin/main # set the upstream of the current branch git push -u origin feature # push and set the upstream git branch -vv # show upstream and ahead/behind git rev-parse --abbrev-ref @{upstream} # name of the upstream
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git branch --set-upstream-to=<remote>/<branch> [<local-branch>] # same as -u git branch --unset-upstream [<local-branch>] git switch -c <new> --track <remote>/<branch> git push -u <remote> <branch>
The relationship is stored in .git/config:
[branch "main"]
remote = origin
merge = refs/heads/main
| Setting | Meaning |
|---|---|
branch.<name>.remote |
which remote to fetch from and push to |
branch.<name>.merge |
which branch on the remote to merge or rebase with |
branch.<name>.rebase |
optional override of pull.rebase for this branch |
Usage notes
@{upstream}(short form@{u}) names the upstream in any revision, sogit log @{u}..HEADlists what you have not pushed andgit log HEAD..@{u}what you have not pulled.- Automatic tracking. Creating a branch from a remote-tracking branch with
git switch name(when only one remote has it) orgit switch -c name origin/namesets up tracking automatically;branch.autoSetupMergecontrols when. - First push. With
push.autoSetupRemoteset totrue,git pushsets the upstream the first time, so-uis no longer needed. - Upstream is not always the same name. A local
fixcan trackorigin/hotfix-12; withpush.defaultset tosimple(the default),git pushthen refuses to push to a differently named branch. - Counts can be stale. Ahead/behind numbers compare against the last fetch. Run
git fetchfirst. - Deleted remote branch. After it disappears on the server, the local branch shows
[gone]ingit branch -vv;git fetch --pruneremoves the stale remote-tracking branch. - You can track a local branch with
git branch -u main feature(remote is.).