Remote tracking branches¶
Tracking or not tracking¶
When you clone a remote repository all the remote branches are tracked and set as upstream branch for the new checked out master, then git-pull(1) will appropriately merge from the starting point branch.
But it is not special to cloning, when a local branch is started off
a remote-tracking branch, the remote branch is tracked, with the
default value of the global branch.autosetupmerge
configuration flag.
If you want to override this global setting, you can use the option
--track
or --no-track
.
Listing upstream branches¶
To see what are the upstream branches of your branches you can do:
$ git branch -vv
* master 376438d [origin/master] this commit is an example
or for a specific branch mybranch:
$ git branch -vv --list mybranch
* mybranch 226f541 [gitlab/master] an other example
The upstream branch is shown between brackets.
You can also explore the configuration and show the remote and the default fetched reference and the default pushed one if it differs from the fetched one with:
$ git config --get-regexp branch.mybranch
branch.mybranch.remote gitlab
branch.master.merge refs/heads/master
If you want to know all the upstream branches you can do
$ git config --get-regexp branch\\..*\\.remote
To know what branches are tracked by a specific remote origin, and know the status of the local branches (up to date or out of date):
$ git remote show bitbucket
* remote bitbucket
Fetch URL: git@bitbucket.org:bigjohn/repo.git
Push URL: git@bitbucket.org:bigjohn/repo.git
HEAD branch: master
Remote branch:
master tracked
Local branch configured for 'git pull':
master merges with remote master
Local ref configured for 'git push':
master pushes to master (up to date)
This command will query the remote repository, if you want to know only the local
configuration, you may add the -n
option, but you will not know the status of the
local branches.
Create a branch and track the origin¶
Example with matching name¶
To start a local branch from origin/mywork and track the origin, you issue:
$ git branch mywork origin/mywork
The new branch is created, but the HEAD is unchanged, to move HEAD to mywork you have to issue:
$ git checkout mywork
both command can be summarized in only one:
$ git checkout mywork
because when the branch is not existing, git will look for a matching name for a remote tracking branch.
Example with non matching names¶
You can also use non matching names:
$ git branch --track devel origin/mywork
$ git checkout devel
is also done with:
$ git checkout -b devel --track origin/mywork
Since branches from a remote are implicitely tracked, you can omit the --track
option from the previous two commands and do:
$ git branch --track devel origin/mywork
$ git checkout devel
or:
$ git checkout -b devel origin/mywork
Tracking defaults¶
The default when creating a branch from a remote is to track the remote, but when you create a branch from an other local branch is to not tracked by default.
When you do
$ git branch newdev devel
devel is not tracked, if you want to have it tracked you should use:
$ git branch --track newdev devel
These defaults depend of the global configuration option branch.autoSetupMerge
whose
default value is true
.
Asking to not track¶
To start a local branch from origin/mywork but not track the origin, you issue:
$ git branch --no-track mywork origin/mywork
Note that for two local branches the default, is no tracking, so with:
$ git branch develop master
or:
$ git checkout -b develop master
develop will not track master, unless you have used:
$ git branch --track develop master
or:
$ git checkout -b --track develop master
You can also add to any branch a tracking of an upstream branch
$ git branch --set-upstream-to=origin/mywork mywork
This is specially usefull whan you first created mywork and then pushed it to origin as:
$ git push origin mywork
will not set origin/mywork as remote tracking branch for mywork, except if you explicitly issue:
$ git push --set-upstream origin mywork
--set-upstream
is abridged in -u
.
Configuration of upstream branches¶
A branch is registered as upstream for another one by setting the
two configuration variables branch.<name>.remote
and
branch.<name>.merge
.
These two configuration options are described in git-config(1).
The previous tracking branch will set the following config options:
branch.mywork.remote=origin
branch.mywork.merge=refs/heads/mywork
The first line tell what is the default remote to fetch and push to. If you want to
fetch/pull from one remote and push to another one use remote
for fetching and
pushremote
for pushing.
If you want to set a default remote for all branches, you can also set the configuration
variable remote.Pushdefault
which overide branch.<name>.remote
for all branches.
The second line tell which ref on the remote should be used for fetching, pulling and rebasing.
Together these options will cause a git pull without remote nor refspec given, to merge origin/mywork in mywork.
In the .git/config
it appears as:
[branch "mywork"]
remote = origin
merge = refs/heads/mywork
[remote "origin"]
url = <url>
fetch = +refs/heads/*:refs/remotes/origin/*
If you track an other local branch, the pseudo remote is designed by a dot:
branch.feature.remote=.
branch.feature.merge=refs/heads/master
Changing the upstream branch¶
We have seen how to create a branch and track the origin but you may also want change the tracking option of an existing branch, either declare an upstream branch for a branch which does not have one, or change the upstream branch.
You can do it at the level of upstream configuration either by using
git-config(1), or even by editing the .git/config
file,
but since v 1.8 git offer a new option of git-branch(1)
$ git branch --set-upstream-to github/master
will set the upstream branch for the currently checked out branch to github/master
,
this can also be done for an other branch by:
$ git branch mywork --set-upstream-to github/master
You can also do it while pushing your branch to the new remote by
$ git push --set-upstream github/master
or
$ git push mywork --set-upstream github/master
This is specially usefull whan you first created a local branch mywork and then pushed it to origin as:
$ git push origin mywork
will not set origin/mywork as remote tracking branch for mywork, except if you either explicitly issue:
$ git push --set-upstream origin mywork
or you later add tracking with:
$ git branch --set-upstream-to=origin/mywork mywork
--set-upstream
(for git push
) or --set-upstream-to
(for git branch
) are
both abridged in -u
.
If you no longer want any tracking for a branch, you can remove it with:
$ git branch --unset-upstream <branch>
as usual if the branch name is omitted, it applies to the current checked out branch