Skip to content
Tutorials Center
My learning

Topics

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".

Terminal
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

Bash Upstream, ahead and behind

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.

Bash Remote-tracking branches move only on fetch

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

Terminal
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:

TEXT
[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, so git log @{u}..HEAD lists what you have not pushed and git 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) or git switch -c name origin/name sets up tracking automatically; branch.autoSetupMerge controls when.
  • First push. With push.autoSetupRemote set to true, git push sets the upstream the first time, so -u is no longer needed.
  • Upstream is not always the same name. A local fix can track origin/hotfix-12; with push.default set to simple (the default), git push then refuses to push to a differently named branch.
  • Counts can be stale. Ahead/behind numbers compare against the last fetch. Run git fetch first.
  • Deleted remote branch. After it disappears on the server, the local branch shows [gone] in git branch -vv; git fetch --prune removes the stale remote-tracking branch.
  • You can track a local branch with git branch -u main feature (remote is .).