Part V: Chapter 5.6

Tracking Branches

The relationship between main and origin/main.

A tracking branch is a local branch that has a registered upstream counterpart. Git uses this relationship to compute ahead/behind counts, power git pull and git push with no arguments, and tell you exactly how your work relates to the remote.

The Four Possible States

Toggle between states to see how the graph, git status, and git branch -vv output change — and what the tracking config in .git/config looks like.

git status output

$ git status

On branch main

Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

git branch -vv output

$ git branch -vv

* main a1b2c3f [origin/main] Add homepage

.git/config (tracking setup)

[branch "main"]

remote = origin

merge = refs/heads/main

origin/main is just a local bookmark — a file in .git/refs/remotes/origin/ recording where the remote's branch was the last time you fetched.

What “tracking” actually means

origin/main is not a live view of the remote — it is a local ref that records where origin's main was the last time you fetched. It lives in .git/refs/remotes/origin/main and is updated only by fetch, pull, or push.

The tracking relationship is stored in .git/config under [branch "main"]. Two keys matter: remote (which remote to talk to) and merge (which remote ref to integrate).

With tracking set up, git pull and git push know what to do with no arguments. Without it, you must be explicit: git push origin main.

Setting up tracking

Tracking is set automatically when you clone (for the default branch) or when you push with -u. You can also set it explicitly at any time.

# Push and set upstream in one step:

git push -u origin feature/login

# Set upstream on an existing branch:

git branch --set-upstream-to=origin/main main

# Remove the tracking relationship:

git branch --unset-upstream main

# Check all branches and their upstreams:

git branch -vv

Reading ahead/behind counts

Terminal

$git fetch origin

$git branch -vv

* main a1b2c3f [origin/main: ahead 2, behind 1] Add dark mode

feature/nav d4e5f6a [origin/feature/nav] Add nav bar

hotfix g7h8i9b Urgent patch

$# 'ahead 2' means you have 2 commits to push

$# 'behind 1' means there is 1 remote commit to pull

$# 'hotfix' has no upstream — push -u to set one

$git log main..origin/main --oneline

x9y0z1a Colleague's fix

$git log origin/main..main --oneline

a1b2c3f Add dark mode

e4f5g6h Refactor nav