Why does git-pull manpage say “You never do your own development on branches that appear on the right hand side of a colon on Pull: lines”?

Question

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

You never do your own development on branches that appear on the right hand side

Answer 1

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
    fetch = +refs/heads/*:refs/remotes/origin/*

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.

Answer 2

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).

Answer 3

The git Visual Reference is a good start:

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

---

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.