Tracking Branches
A tracking branch (formally an 'upstream-tracking' local branch) is a local branch that has been explicitly associated with a specific remote-tracking branch, such as origin/feature-x. That association is what lets you run bare git push and git pull without naming the remote and branch every time, and it's also what powers git status's 'your branch is ahead by 2 commits' messaging and git branch -vv's ahead/behind counts. Without a tracking relationship, Git has no default answer to 'push this branch where?' and will either prompt you to specify or, depending on configuration, refuse to push at all.
Cricket analogy: A tracking branch is like a batsman's designated non-striker end being pre-assigned before the over starts, so the umpire doesn't ask 'which end are you running to?' every single ball; without it, git push has no default crease to run for.
Setting Up Tracking
Tracking is set up automatically in the most common cases: cloning a repository sets your default branch (e.g. main) to track origin/main, and checking out a remote branch by name with git checkout feature-x (when only one remote has a matching branch) automatically creates a local branch tracking origin/feature-x. For a brand-new local branch with no remote counterpart yet, the first push needs an explicit flag to establish tracking: git push -u origin feature-x (or --set-upstream) both pushes the branch and records the tracking relationship in one step, so every subsequent plain push/pull on that branch knows where to go.
Cricket analogy: Cloning a repo automatically pairs main with origin/main like a franchise draft automatically slotting a marquee player into the opening batting position, but a brand-new local branch needs an explicit team announcement — git push -u origin feature-x — to formally register it before it can play.
Inspecting and Changing Tracking Relationships
git branch -vv lists local branches with their tracked remote branch and how many commits ahead/behind they are, which is the fastest way to spot branches that need pushing, pulling, or cleanup. If a branch's tracking got set to the wrong remote branch (or none at all), git branch --set-upstream-to=origin/main (or -u for short) fixes it without touching any commits. git branch --unset-upstream removes the tracking relationship entirely, which is occasionally useful for a purely local, throwaway branch you never intend to push.
Cricket analogy: git branch -vv is like a scoreboard showing every batsman's partnership and run-rate versus the required rate at a glance; --set-upstream-to is like correcting a scorer's mistaken end-of-innings entry without replaying any deliveries, and --unset-upstream retires a throwaway net-practice session from official records.
# See tracking relationships and ahead/behind counts
git branch -vv
# * main a1b2c3d [origin/main] Add checkout summary
# feature/search 9f8e7d6 [origin/feature/search: ahead 2] WIP search filters
# First push of a new local branch, establishing tracking
git checkout -b feature/search
git push -u origin feature/search
# Fix tracking to point at a different remote branch
git branch --set-upstream-to=origin/develop feature/search
# Check out an existing remote branch, auto-creating a tracking local branch
git checkout feature/reporting # creates local branch tracking origin/feature/reporting
# Remove the tracking relationship for a purely local branch
git branch --unset-upstream scratch/experimentThe square-bracket notation in git status and git branch -vv output — e.g. [origin/main: ahead 2, behind 1] — is Git comparing your local branch tip against the remote-tracking branch's tip as of your last fetch. 'Behind' means the remote has commits you don't; 'ahead' means you have local commits not yet pushed. Both counts can be stale until you fetch again.
Ahead/behind counts are only as fresh as your last fetch. If a teammate pushed five minutes ago and you haven't fetched since, git branch -vv will still show you as 'up to date' even though you're not — always fetch before trusting these numbers for anything important, like deciding whether a force push is safe.
- A tracking branch is a local branch linked to a specific remote-tracking branch, enabling plain
push/pullwithout arguments. - Cloning sets up tracking for the default branch automatically; checking out a matching remote branch name does too.
git push -u origin <branch>both pushes and establishes tracking for a brand-new local branch.git branch -vvshows each local branch's tracked remote branch and how many commits ahead/behind it is.git branch --set-upstream-to=<remote>/<branch>fixes or changes an existing tracking relationship without altering commits.- Ahead/behind counts reflect your last fetch, not the remote's live state — fetch first before relying on them.
Practice what you learned
1. What does a tracking branch relationship enable you to do?
2. Which command both pushes a brand-new local branch AND sets up its tracking relationship in one step?
3. What does `git branch -vv` display for each local branch?
4. How do you change which remote branch an existing local branch tracks, without altering any commits?
5. Why can the 'ahead/behind' counts shown by `git branch -vv` be misleading?
Was this page helpful?
You May Also Like
Remotes Explained
A remote is a named reference to another copy of a repository, usually hosted elsewhere, that Git uses to synchronize commits, branches, and tags between machines.
Push, Pull, and Fetch
Push, pull, and fetch are the three commands that move commits between your local repository and a remote — understanding exactly what each does (and doesn't do) prevents most everyday Git confusion.
Creating and Switching Branches
Master the day-to-day commands for creating, switching, listing, and deleting branches, including the modern git switch/git restore split from git checkout.
Forking and Cloning
Cloning creates a full local copy of a repository's history, while forking creates a server-side copy under your own account — together they underpin how most open-source contribution happens.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 75 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics