GIT: 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

GIT: Remote and local tracking branches

33.1. Remote tracking branches

Your local Git repository contains references to the state of the branches on the remote repositories to which it is connected. These local references are called remote-tracking branches.

You can see your remote-tracking branches with the following command.

# list all remote branches
git branch -r

To update remote-tracking branches without changing local branches you use the git fetch command. See Updating your remote-tracking branches with git fetch for more information.

It is safe to delete a remote branch in your local Git repository, this does not affect a remote repository. The next time you run the git fetch command, the remote branch is recreated. You can use the following command for that.

# delete remote branch from origin

git branch -d -r origin/[remote_branch]

33.2. Delete a remote branch

To delete the branch in a remote repository use the following command.

# delete branch in a remote repository

git push [remote] --delete [branch]

33.3. Tracking branches

Branches can track another branch. This is called to have an upstream branch and such branches can be referred to as tracking branches.

Tracking branches_ allow you to use the git pull and git push command directly without specifying the branch and repository.

If you clone a Git repository, your local master branch is created as a tracking branch for the master branch of the originrepository (short:_origin/master_) by Git.

You create new tracking branches by specifying the remote branch during the creation of a branch. The following example demonstrates that.

# setup a tracking branch called newbrach
# which tracks origin/newbranch
git checkout -b newbranch origin/newbranch

Instead of using the git checkout command you can also use the git branch command.

# origin/master used as example, but can be replaced

# create branch based on remote branch
git branch [new_branch] origin/master

# use --track,
# default when the start point is a remote-tracking branch
git branch --track [new_branch] origin/master

The --no-track allows you to specify that you do not want to track a branch. You can explicitly add a tracking branch with the git branch -u command later.

# instruct Git to create a branch which does
# not track another branch
git branch --no-track [new_branch_notrack] origin/master

# update this branch to track the origin/master branch
git branch -u origin/master [new_branch_notrack]

To see the tracking branches for a remote repository (short: remote) you can use the following command.

# show all remote and tracking branches for origin
git remote show origin

An example output of this might look as follows.

* remote origin
  Fetch URL: ssh://test@git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git
  Push  URL: ssh://test@git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git
  HEAD branch: master
  Remote branches:
    integration                tracked
    interm_rc2                 tracked
    master                     tracked
    smcela/HandlerAddonUpdates tracked
  Local branches configured for 'git pull':
    integration rebases onto remote integration
    master      rebases onto remote master
    testing     rebases onto remote master
  Local refs configured for 'git push':
    integration pushes to integration (up to date)
    master      pushes to master      (up to date)