Skip to main content

How can I tell a local branch to track a remote branch?

Short answer

A tracking (upstream) connection links a local branch to a counterpart branch on a remote, allowing Git to report how many commits ahead or behind you are and enabling argument-free git pull and git push. To set the upstream for the current branch after it already exists, run git branch --set-upstream-to=origin/<remote-branch>. When creating and pushing a new branch for the first time, use git push -u origin <branch-name>, which simultaneously pushes the branch and sets the upstream in one step. Once the tracking relationship is configured, git status will display messages like 'Your branch is 2 commits ahead of origin/main', helping you stay aware of divergence. Run git branch -vv at any time to see all local branches alongside their configured upstream and the current ahead/behind counts.

Understanding and making use of tracking relationships makes version control a whole lot easier. Let's talk about both the concept and the practice of "tracking" branches.

The Git Cheat Sheet

No need to remember all those commands and parameters: get our popular "Git Cheat Sheet" - for free!

Free. We email you a ZIP with our cheat sheets.

What are tracking connections in Git?

By default, branches in Git have nothing to do with each other. However, when you tell a local branch to "track" a remote branch, you create a connection between these two branches. Your local branch now has a "counterpart" on the remote server.

Why should you set up tracking connections?

Let's say your current local HEAD branch is named "dev". And let's also say that you have set it up to track the "dev" branch on the remote named "origin". This relationship is invaluable for two reasons:

  1. Pushing and pulling becomes a lot easier. You can simply use the shorthand commands "git pull" and "git push" - instead of having to think about the exact parameters like in "git push origin dev". Even more importantly than being "easier", this also prevents you from making mistakes!

  2. Git can now inform you about "unpushed" and "unpulled" commits. Let's make an example:

(a) if you have 2 commits only locally that you haven't pushed to the remote yet, your local branch is "2 commits ahead" of its remote counterpart branch.
(b) if, on the other hand, there are 4 commits on the remote branch that you haven't downloaded yet, then your local branch is "4 commits behind" its remote counterpart branch.

This information helps tremendously in staying up-to-date. Git tells you about this right in the output for "git status":

  git status
  # On branch dev
  # Your branch and 'origin/dev' have diverged,
  # and have 1 and 2 different commits each, respectively.
  #
  nothing to commit (working directory clean)

How do you track a remote branch?

There are three main scenarios for creating a tracking connection.

When you're starting to work on an existing remote branch

Let's say one of your colleagues has already started and published a branch on your remote server. You now want to chime in and start working on that topic, too. In that scenario, simply use the --track flag with the "git checkout" command:

git checkout --track origin/dev
Branch dev set up to track remote branch dev from origin.
Switched to a new branch 'dev'

This creates a new local branch with the same name as the remote one - and directly establishes a tracking connection between the two.

When you're publishing a local branch

Let's now look at the opposite scenario: you started a new local branch and now want to publish it on the remote for the first time:

git push -u origin dev

You can tell Git to track the newly created remote branch simply by using the -u flag with "git push".

When you decide at a later point in time

In cases when you simply forgot, you can set (or change) a tracking relationship for your current HEAD branch at any time:

git branch -u origin/dev


No Command Line Needed

Tracking Branches in Tower

In case you are using the Tower Git client, you'll note that it uses tracking connections in many places to display helpful information:


Learn More

Free download

Download the Cheat Sheet

Get 18 of our most popular Cheat Sheets in one handy ZIP!