What is a Tracking Reference?

When I push a new branch up to a remote repository via Git Extensions, I get an alert saying

The branch {branch name} does not have a tracking reference. Do
you want to add a tracking reference for {branch name}?

What is a tracking reference? I've found only a few mentions of tracking references in Google and no real definition.

The basic idea is that there are purely local references (e.g., branches, tags), and then there are remote tracking references, which follow what happens in other repos. Because Git is decentralized, it is possible for you to choose a name for a branch that is the same as one used in a remote, without having known about the other one, such that they have completely different work on them. Git lets you do this, but it also provides a way to link local references to remote ones as well.

For example, consider the following:

% git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/maint
  remotes/origin/master
  remotes/origin/next
  remotes/origin/pu
  remotes/origin/todo

Here we have branches on origin called next and todo.

% git checkout -t remotes/origin/next
Branch next set up to track remote branch next from origin.
Switched to a new branch 'next'
% git branch todo    

Now we have a local branch next that tracks the remote branch of the same name and local branch todo that will not be updated with changes to remotes/origin/todo.

A local git branch can track a remote branch, which means that git push and git pull commands will know to push and pull commits to and from the tracked branch by default. Also git status will tell the status between your current local branch and the remote branch it's tracking. When you clone a git repository, git will add a tracking reference to the local master branch to track the remote master branch. When you checkout from a new remote branch, git will add a tracking reference to the created local branch to track the remote branch you checked out.

However, if you create a new branch locally, and then push it to the remote repository, you have to explicitly tell git if you want your local branch to start tracking the new remote branch. You do that with the -u or --set-upstream option when pushing the local branch to the remote repository: git push -u origin my-new-branch.

You can check which remote branches your local branches are tracking (if any) with the command git branch -vv Below is a small example of the output.

  b1     560eb64 Added file.txt
  b2     560eb64 [origin/b2] Added file.txt
  b3     b638c18 [origin/r1: ahead 1] Added file3.txt
* master 560eb64 [origin/master] Added file.txt

In this case we have local branches master, b1, b2 and b3. The master branch is tracking a remote branch called master, the b1 branch isn't tracking any remote branches, the b2branch is tracking a remote branch called b2and the b3branch is tracking a remote branch called r1. git branch -vv also shows the status of the branch related to the traced branch. Here branch b3 is 1 commit ahead of the tracked remote branch and the other branches are up to date with their respective remote tracked branches.

So if you create a local branch and push to the remote repository, would you want to add a tracking reference to the branch or not? Usually when you push a new local branch to the remote repository, you do it to collaborate with other developers on a feature. If you add a tracking reference to your local branch, you can conveniently pull the changes that other people have made to the branch, so I would say that in most cases you want to add the tracking reference.

Nick Quaranto's excellent blog git ready has a post explaining remote tracking branches:

Remote-tracking branches have a few different purposes:

• They’re used to link what you’re working on locally compared to what’s on the remote.

• They will automatically know what remote branch to get changes from when you use git pull or git fetch.

• Even better, git status will recognize him how many commits you are in front of the remote version of the branch.

yes you likely want to add it. do this in the console: git branch --set-upstream-to origin/master