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

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.

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

Learn More

• Check out the chapter Inspecting Remote Data in our free online book
• More frequently asked questions about Git & version control