First we need a few definitions.
A local branch (also just called "a branch", with no modifier) is one whose full name starts with refs/heads/
. When using git branch
, you will see your local branches by default. The git branch
command strips off the refs/heads/
part, leaving you with names like master
and v2
.
A remote-tracking branch is one whose full name starts with refs/remotes/
(and then has the name of a remote after that). When using git branch -r
, the command will show you your remote-tracking branches. The git branch -r
command strips off the refs/remotes/
part, leaving you with names like origin/master
and origin/v2
.
The prefix-stripping works both ways: git branch
takes it off, and you can leave it off too. This is meant for convenience, and works well as long as you do not accidentally give your (regular, local) branches names starting with origin/
. (If you do accidentally name a local branch origin/abc
, for instance, you may confuse yourself and git's helpful stripping of prefixes becomes harmful.)
(Note that all these entities are local to your own repository, despite the name "remote-tracking". Additional references may also exist and you can see all of them with git for-each-ref
, which will show you every reference using its full name. Most of the time you don't need this, and git branch
suffices.)
A (regular, local) branch can be set to track another branch. Making one branch track another does a few things for you, such as make git status
tell you when you are ahead and/or behind, and including the other branch in git branch -vv
output. (Setting tracking is not the same as a remote-tracking branch. Again, a local branch is one whose name starts with refs/heads/
, and its name does not change whether or not it is set to track another branch. However, the terminology is certainly confusing.)
To make one branch track another, first check out the first branch (the one you want to do the tracking). Then, run git branch --set-upstream-to otherbranch
. For instance, to make v2
track origin/v2
:
git checkout v2
git branch --set-upstream-to origin/v2
To make a local branch track another local branch, simply use a local branch name rather than a remote-tracking branch name. To make a local branch stop tracking anything, use git branch --unset-upstream
.
There's one more trick to all of this,1 which is that when you ask git checkout
to check out (but not create) a local branch that does not exist, git checkout
will search to see if there is a remote-tracking branch with a similar name. If so, it will create the local branch and set it up to track the remote-tracking branch. That is, if branch v2
does not exist—for instance, if you rename or delete the existing local v2
—and origin/v2
still does exist, then:
git checkout v2
creates local branch v2
and sets it to track origin/v2
, all at once.
A branch need not track another branch to push and fetch/merge/rebase/pull, but setting it up as tracking can make all of those operations more convenient.
1As usual with git, there are actually more methods to make local branches track something else. You can set up a local branch to track a remote-tracking branch on a successful git push
by adding -u
to the push. You can use the (deprecated) git branch --set-upstream
command. You can use flags to git checkout
or git branch
to create or re-create a branch with tracking set. And, you can use git config
(with two separate git config
commands) to make a local branch track some other branch.
git push
from that branch? – Midland