Understanding Remote Tracking Branches

Remote tracking branches are local references that represent the state of branches on a remote repository. They look like origin/main, origin/feature, etc. You cannot commit to them directly — they update automatically when you fetch or pull.

What Are They?

Every time you interact with a remote (fetch, pull, push, clone), Git updates these special references to reflect the remote's branch positions. They serve as bookmarks showing "where was this branch the last time I checked?"

main           → your local branch (you work here)
origin/main    → last known state of main on origin
origin/feature → last known state of feature on origin

Viewing Remote Tracking Branches

List all remote tracking branches:

git branch -r

List all branches (local and remote tracking):

git branch -a

See where each branch points:

git branch -vv

The -vv output shows which local branch tracks which remote branch:

  main    abc1234 [origin/main] Latest commit message
* feature def5678 [origin/feature: ahead 2] My new work

How They Update

Remote tracking branches update in specific situations:

git fetch — Downloads and updates all remote tracking branches
git pull — Fetches (updating tracking branches) then merges
git push — After a successful push, the tracking branch moves forward
git clone — Sets up all tracking branches from the cloned remote

They do not update automatically. If a teammate pushes new commits, your origin/main still points to where it was until you fetch.

Upstream Tracking

A local branch can be configured to "track" a remote branch, making it the upstream. This enables shorthand commands:

git push -u origin main

After setting upstream, these shorter commands work:

git push        # instead of git push origin main
git pull        # instead of git pull origin main
git status      # shows "ahead/behind" info

Ahead and Behind

When your local branch tracks a remote branch, Git can tell you how they diverge:

git status
# On branch main
# Your branch is ahead of 'origin/main' by 2 commits.

Ahead by N — You have N local commits not yet pushed
Behind by N — The remote has N commits you haven't merged
Diverged — Both sides have new commits (you'll need to merge or rebase)

Ahead by 2:
  origin/main:  A --- B
  local main:   A --- B --- C --- D

Behind by 3:
  origin/main:  A --- B --- C --- D --- E
  local main:   A --- B

Diverged (ahead 1, behind 2):
  origin/main:  A --- B --- D --- E
  local main:   A --- B --- C

Key Takeaways

Remote tracking branches are read-only snapshots of the remote's state
They live in your local repository but you don't commit to them
They update when you fetch, pull, push, or clone
Setting an upstream lets you use shorthand commands and see ahead/behind status
Always fetch to get the latest picture of what's happening on the remote