84

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.

Eric Walker
  • 7,063
  • 3
  • 35
  • 38
Simon Elms
  • 17,832
  • 21
  • 87
  • 103
  • 2
    See push -u for the scoop. – bmargulies Mar 13 '13 at 01:04
  • If I understand the git man pages for push, pull and config correctly, a tracking reference is a setting or settings added to the config file, used by argument-less git-pull to tell it what to pull down. I find the documentation a bit confusing but my take on it is the tracking reference is a combination of the following settings in the config file: remote..fetch and branch..merge. Is that correct? – Simon Elms Mar 13 '13 at 01:32
  • 1
    Tracking reference is the **link between** a local blanch (e.g. `master`) and a remote branch (e.g. `origin/master`). – dedek Mar 04 '19 at 13:39

4 Answers4

40

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.

Eric Walker
  • 7,063
  • 3
  • 35
  • 38
  • Thanks. So a "reference" is just an object, like a branch or a tag, and a "tracking reference" is just an object that is linked to a corresponding object in a remote repository? – Simon Elms Mar 13 '13 at 04:23
  • 2
    Yes -- that's the main idea. "object" has a special meaning in Git; it means anything with a SHA1 that is stored beneath .git/objects, so it is more general than "reference", but this is the idea. – Eric Walker Mar 13 '13 at 04:29
  • 23
    Sooo, uhhhh, anybody want to recommend whether we should say YES or NO? "Do you want to add a tracking reference to master"? It's all confusing still in practical terms. What's commonly selected? Are there any benefits and drawbacks to either option? Can one say 'YES' and just forget about it without that causing any problems? – Nicholas Petersen Jul 15 '13 at 19:32
  • 5
    @NicholasPetersen, in most cases you want to avoid using the same name for a reference on a remote for different work. This means you usually want to use a tracking reference or choose a different name. – Eric Walker Aug 07 '13 at 18:19
  • 1
    I'm being told "The branch master does not have a tracking reference. Do you want to add a tracking reference to master?" **Scenario**: I cloned a repo in GitHub, made a change to local copy, committed. Then I wanted to send a pull request so I forked the same repo on GitHub. Next I removed the original 'origin' and replaced it with the 'origin' of my new fork. Finally I am trying to push to the new 'origin' in Git Extensions. This is the second warning after "The branch you are about to push seems to be a new branch for the remote" of two. I am worried! So the question remains... YES or NO? – Qwertie May 16 '14 at 23:54
  • @Qwertie best not to push if you get a warning, unless you have a pretty good sense of the implications. At this point I'd get someone who's pretty good with Git to look over your shoulder. – Eric Walker May 17 '14 at 00:09
  • @EricWalker Good news, I clicked YES and everything worked like I wanted it to. I just wish I understood what the warnings meant. – Qwertie May 17 '14 at 00:39
  • Does it matter if the remote is a bare repo that you mostly are pushing to as a back-up in case your pc crashes? – Mike Casas Dec 31 '15 at 15:59
  • @MikeCasas, in that case there's no other developer to accidentally create a branch with the same name, so you're pretty safe. – Eric Walker Jan 02 '16 at 20:31
19

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.

Hemaolle
  • 1,950
  • 18
  • 21
8

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.

Simon Elms
  • 17,832
  • 21
  • 87
  • 103
6

Yes, you likely do want to add it. Do this in the console:

git branch --set-upstream-to origin/master
Adrian Mole
  • 49,934
  • 160
  • 51
  • 83
whatsupanna
  • 77
  • 1
  • 1
  • I feel like this is not answering the question about "what is a tracking reference", although it answers "do I need one", without saying why. – Daemon Painter May 06 '22 at 20:47