Tracking Branches

Tracking branches create a connection between your local branches and remote branches, making push and pull operations simpler and more intuitive.

What is a Tracking Branch?

A tracking branch is a local branch that has a direct relationship with a remote branch:

Local Branch         Remote-Tracking Branch       Remote Branch
main         ←────→  origin/main          ←────→  origin's main
feature      ←────→  origin/feature       ←────→  origin's feature

When a local branch tracks a remote branch:

• git push knows where to push
• git pull knows where to pull from
• git status shows how far ahead/behind you are

Setting Up Tracking

When Cloning

When you clone a repository, main is automatically set up to track origin/main:

git clone https://github.com/user/repo.git
cd repo

git status
# On branch main
# Your branch is up to date with 'origin/main'.

When Pushing a New Branch

Use -u (or --set-upstream) to set up tracking:

git push -u origin feature

Now feature tracks origin/feature.

For Existing Branches

# Set upstream for current branch
git branch --set-upstream-to=origin/feature

# Short form
git branch -u origin/feature

When Checking Out Remote Branches

# Automatic tracking if branch name matches
git checkout feature
# If origin/feature exists, local 'feature' will track it

# Or explicitly
git checkout -b feature origin/feature

Viewing Tracking Information

git branch with Verbose Flag

git branch -vv

Output:

* main      abc123 [origin/main] Latest commit message
  feature   def456 [origin/feature: ahead 2] Add new feature
  bugfix    789abc [origin/bugfix: behind 3] Fix bug
  local     111222 Work in progress  # No tracking (no brackets)

The brackets show:

• Which remote branch is tracked
• How many commits ahead/behind

git status

git status

Shows tracking info:

On branch feature
Your branch is ahead of 'origin/feature' by 2 commits.
  (use "git push" to publish your local commits)

Using git remote show

git remote show origin

Shows which local branches track which remote branches.

Ahead and Behind

When your local branch and remote branch have diverged:

git status
# Your branch and 'origin/main' have diverged,
# and have 2 and 3 different commits each, respectively.

Local main:   A ← B ← C ← D ← E        (ahead 2)
                      \
origin/main:           F ← G ← H       (behind 3)

Check specific counts:

# Commits ahead of origin
git rev-list --count origin/main..main

# Commits behind origin
git rev-list --count main..origin/main

# Both
git rev-list --left-right --count main...origin/main
# Output: 2    3  (2 ahead, 3 behind)

Changing or Removing Tracking

Change What a Branch Tracks

git branch -u origin/other-branch

Remove Tracking

git branch --unset-upstream

Change for a Specific Branch

git branch -u origin/main feature

Exercise: Set Up Tracking

Practice setting up and viewing tracking relationships:

Tracking and Push/Pull

Without Tracking

You must specify remote and branch:

git push origin feature
git pull origin feature

With Tracking

Just use the commands directly:

git push
git pull

Git knows where to push/pull from.

Tracking Remote Branches That Don't Exist Yet

When you create a new branch and want to push it:

# Create branch
git checkout -b new-feature

# Push and set up tracking in one command
git push -u origin new-feature

Fetching and Tracking

After fetching, new remote branches appear:

git fetch origin

git branch -r
# origin/main
# origin/feature
# origin/new-branch  (new!)

To work on the new branch:

# Automatic tracking if names match
git checkout new-branch

# Or explicitly
git checkout -b new-branch origin/new-branch

The Upstream Configuration

Tracking is stored in .git/config:

[branch "feature"]
    remote = origin
    merge = refs/heads/feature

You can view it with:

git config --get branch.feature.remote
# origin

git config --get branch.feature.merge
# refs/heads/feature

Push Default Configuration

Configure default push behavior:

# Push current branch to its tracking remote
git config --global push.default current

# Only push if upstream is set (default since Git 2.0)
git config --global push.default simple

# Push all matching branches
git config --global push.default matching

Summary

• Tracking branches connect local branches to remote branches
• Use git push -u to set up tracking when pushing
• Use git branch -vv to see tracking relationships
• Tracked branches show ahead/behind status
• With tracking, git push and git pull just work
• Use git branch -u to change or set tracking
• Use git branch --unset-upstream to remove tracking

In the next module, we'll learn about GitHub and how to use it effectively.