Take the 2-minute tour ×

The manpage for git pull, below "Options related to fetching" says


We've been trialling a workflow which is:

git fetch origin
git checkout -b un-3437 origin/un-3437

I believe that un-3437 in the example is B in the manpage comment. Therefore we should then branch from un-3437. However, this seems to be a lot of extra work.

Secondly, ignoring the second branch idea in the paragraph above, we are finding that git status will say that the local branch is ahead of the remote by x commits. We don't understand how that would be if we've just done git pull.

Our mental model appears to be wrong. Is there a good resource to explain all these pointers?

share|improve this question
Note: since Git 2.1 (August 2014), that part of the documentation is no longer relevant and has been removed. See my answer edited below –  VonC Aug 2 at 16:54

3 Answers 3

The git Visual Reference is a good start:

See git pull, where you combine git fetch and git merge:

enter image description here

Update August 2014 (2+ years later)

Commit 3630654 (May 2014, Git 2.1 by Junio C Hamano (gitster)) removes that warning from the doc:

In old days before Git 1.5, it was customary for "git fetch" to use the same local branch namespace to keep track of the remote-tracking branches, and it was necessary to tell users not to check them out and commit on them.

Since everybody uses the separate remote layout these days, there is no need to warn against the practice to check out the right-hand side of <refspec> and build on it---the RHS (right hand side) is typically not even a local branch.

share|improve this answer

Your workflow is correct.

Have a look inside your .git directory at the root of your project, examine the config file and you should see something like

[remote "origin"]
    url = git@bitbucket.org:something/projectname.git

these lines are consulted when you type git fetch origin.

You can see that actually the right-hand-side of the pull/fetch is actually something that contains remotes/origin. What they are saying is do not edit the remote tracking branch.

By typing

git checkout -b un-3437 origin/un-3437

you are creating a local branch that tracks the "locally stored remote tracking branch". When git status says you are ahead or behind by X commits, it is comparing un-3437 to remotes/origin/un-3437.

share|improve this answer

The man page says you never do development on a branch than appears on the right hand side of the colon in a "Pull:" config. It doesn't say that you shouldn't do development in a branch named the same as something on the left hand side of the colon.

It doesn't matter what's on the left hand side of the colon because those references live on the remote server. The name that appears on the right hand side does matter as this references a branch on your local repository that will be automatically updated (not merged!) by a pull or fetch and you don't want that reference branch to be modified locally otherwise chances will either be lost (if you force the update) or you won't be able to get a local copy of the remote changes (if you don't force the update).

share|improve this answer

Your Answer


