2

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 of a colon on Pull: lines; they are to be updated by git fetch. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i.e. Pull: B:remote-B), and have a separate branch my-B to do your development on top of it. The latter is created by git branch my-B remote-B (or its equivalent git checkout -b my-B remote-B). Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull . remote-B, while you are on my-B branch.

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?

Sarge
  • 2,367
  • 2
  • 23
  • 36
  • 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](http://stackoverflow.com/a/8274988/6309) – VonC Aug 02 '14 at 16:54

3 Answers3

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

CB Bailey
  • 755,051
  • 104
  • 632
  • 656
1

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.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
0

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.

Jacob Groundwater
  • 6,581
  • 1
  • 28
  • 42