Skip to content

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/main

When 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 -av

Output:

* 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 API

The * 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/main

Together 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/logout

Once set, git push and git pull work without arguments. Git reads the upstream from config.

Checking upstream status ​

bash
git status

Output 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}...HEAD

Output:

2       0

The 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't

If you like the new commits, merge or rebase:

bash
git rebase origin/main

Or 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/main

Now 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 upstream

Now 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't

What happens when you delete a remote-tracking branch ​

Remote-tracking branches are local metadata. Deleting one is safe:

bash
git branch -dr origin/stale-branch

The -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 origin

This removes any remote-tracking branches that no longer exist on the remote. Run it periodically to clean up stale refs.

Quick reference ​

CommandWhat it does
git branch -aList all branches (local + remote-tracking)
git branch -rList remote-tracking branches only
git branch -vvList 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 fetchUpdate all remote-tracking branches
git fetch --pruneRemove stale remote-tracking refs
git statusShow ahead/behind relative to upstream
git log @{u}..HEADCommits you have that upstream doesn't
git log HEAD..@{u}Commits upstream has that you don't

Pitfalls ​

PitfallWhy it bites
Assuming origin/main is always the real remote stateIt is a local snapshot. Run git fetch to refresh it.
Pushing without upstream setGit refuses: "The current branch has no upstream branch." Use -u on first push.
Deleting a remote-tracking branch manuallySafe, but git fetch recreates it unless you prune.
Thinking git pull always mergesIt does, but pull.rebase true makes it rebase. Know your config.
Ignoring "diverged" in git statusYour 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 fetch before every work session.
  • Use @{u} in scripts and aliases. It makes everything branch-agnostic.
  • Prune stale refs. Add git fetch --prune to 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.

Git Master — Git Reference for Every Skill Level