Appearance
Remote-Tracking Branches: Upstream, Ahead/Behind, and Tracking Config
You clone a repo. You run git branch -a and see both main and origin/main. You wonder: what is origin/main? Why does git status sometimes say "Your branch is ahead of 'origin/main' by 2 commits"? And what happens when you run git push without arguments?
This guide answers those questions. Remote-tracking branches are the bridge between your local work and everyone else's, and understanding them is the difference between guessing at push/pull behavior and knowing exactly what Git will do.
What a remote-tracking branch is
A remote-tracking branch is a local ref that mirrors a branch on a remote. It lives in .git/refs/remotes/<remote>/<branch>. You never commit directly to it. Git updates it when you fetch or push.
Local branches: Remote-tracking branches:
main origin/main
feature/logout origin/feature/logout
upstream/mainWhen you run git fetch origin, Git contacts origin, downloads new commits, and updates origin/main, origin/feature/logout, and so on. Your local main does not move. Your working tree does not change.
Think of remote-tracking branches as your repo's memory of what the remote had last time you checked.
Viewing them
bash
# All branches, local and remote-tracking
git branch -a
# Only remote-tracking branches
git branch -r
# With last commit info
git branch -avOutput:
* main a1b2c3d [ahead 2] Add login retry
feature/logout d4e5f6g Add logout button
remotes/origin/main a1b2c3d Add login retry
remotes/origin/feature/logout c7d8e9f Implement logout APIThe * on main means you have it checked out. origin/main points to the same commit as your local main (they are in sync). origin/feature/logout is ahead of your local copy because a teammate pushed.
Upstream tracking: connecting local to remote
When a local branch has an upstream, Git knows what to compare it against. The upstream is a remote-tracking branch, stored in the branch config:
bash
git config --get branch.main.remote
# origin
git config --get branch.main.merge
# refs/heads/mainTogether they mean: local main tracks origin/main.
Setting upstream
bash
# During first push
git push -u origin feature/logout
# For an existing branch
git branch -u origin/feature/logout
# Or explicitly
git branch --set-upstream-to=origin/feature/logoutOnce set, git push and git pull work without arguments. Git reads the upstream from config.
Checking upstream status
bash
git statusOutput when ahead:
On branch main
Your branch is ahead of 'origin/main' by 2 commits.
(use "git push" to publish your local commits)Output when behind:
On branch main
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
(use "git pull" to update your local branch)Output when diverged:
On branch feature/logout
Your branch and 'origin/feature/logout' have diverged,
and have 1 and 2 different commits each, respectively.
(use "git pull" to merge the remote branch into yours)The @{upstream} shortcut
Use @{u} or @{upstream} anywhere you'd use a branch name:
bash
# See commits you have that upstream doesn't
git log --oneline @{u}..HEAD
# See commits upstream has that you don't
git log --oneline HEAD..@{u}
# Diff against upstream
git diff @{u}
# Rebase on upstream
git rebase @{u}This saves typing origin/main over and over.
Ahead/behind: what Git is actually counting
"Your branch is ahead by 2 commits" means: there are 2 commits reachable from your local branch that are not reachable from the upstream. Git uses git rev-list --count under the hood:
bash
# Ahead count
git rev-list --count --left-right @{u}...HEADOutput:
2 0The left number is commits only in upstream, the right number is commits only in your branch. When both are non-zero, your branch has diverged from upstream.
Fetching without merging
git fetch updates remote-tracking branches. It does not touch your local branches or working tree. This is the safe way to check what happened on the remote without changing your state:
bash
git fetch origin
git log --oneline main..origin/main # what's new on remote
git log --oneline origin/main..main # what you have that remote doesn'tIf you like the new commits, merge or rebase:
bash
git rebase origin/mainOr use git pull --rebase to do both steps at once.
Real scenario: teammate pushed while you worked
You are on feature/payments. You committed twice. Your teammate merged a PR to main. You need to integrate.
bash
# Step 1: fetch to update origin/main
git fetch origin
# Step 2: check the divergence
git status
# On branch feature/payments
# Your branch and 'origin/feature/payments' have diverged,
# and have 2 and 3 different commits each, respectively.
# Step 3: rebase on the latest main
git rebase origin/mainNow your feature commits sit on top of the latest main, and origin/main is up to date from the fetch.
Multiple remotes
Real projects have more than one remote:
bash
git remote add upstream https://github.com/original/project.git
git fetch upstreamNow you have upstream/main, upstream/develop, etc. The @{upstream} shortcut always resolves to the tracking branch of the current branch's configured remote. For upstream's branches, you reference them explicitly:
bash
git log --oneline upstream/main..origin/main # what the fork has that upstream doesn'tWhat happens when you delete a remote-tracking branch
Remote-tracking branches are local metadata. Deleting one is safe:
bash
git branch -dr origin/stale-branchThe -d flag with -r deletes the remote-tracking branch. The remote still has the branch. Next git fetch recreates the remote-tracking branch unless you prune:
bash
git fetch --prune originThis removes any remote-tracking branches that no longer exist on the remote. Run it periodically to clean up stale refs.
Quick reference
| Command | What it does |
|---|---|
git branch -a | List all branches (local + remote-tracking) |
git branch -r | List remote-tracking branches only |
git branch -vv | List branches with upstream and ahead/behind |
git push -u origin <branch> | Push and set upstream |
git branch -u origin/<branch> | Set upstream for current branch |
@{u} or @{upstream} | Reference to the upstream branch |
git fetch | Update all remote-tracking branches |
git fetch --prune | Remove stale remote-tracking refs |
git status | Show ahead/behind relative to upstream |
git log @{u}..HEAD | Commits you have that upstream doesn't |
git log HEAD..@{u} | Commits upstream has that you don't |
Pitfalls
| Pitfall | Why it bites |
|---|---|
Assuming origin/main is always the real remote state | It is a local snapshot. Run git fetch to refresh it. |
| Pushing without upstream set | Git refuses: "The current branch has no upstream branch." Use -u on first push. |
| Deleting a remote-tracking branch manually | Safe, but git fetch recreates it unless you prune. |
Thinking git pull always merges | It does, but pull.rebase true makes it rebase. Know your config. |
Ignoring "diverged" in git status | Your branch and upstream have both moved. Rebase or merge before push. |
When to use what
- Fetch often. It is read-only and keeps your remote-tracking branches current. Run
git fetchbefore every work session. - Use
@{u}in scripts and aliases. It makes everything branch-agnostic. - Prune stale refs. Add
git fetch --pruneto your weekly routine or CI setup. - Never commit to a remote-tracking branch. Git prevents this. If you need to work on something that exists only on remote, create a local branch from it:
git switch -c my-feature origin/my-feature.
Next steps
Now that you understand tracking, the interactive rebase guide shows how to clean up commits before pushing. The rebase onto guide covers advanced rebase scenarios when upstream has moved in complex ways.