Re: Git documentation reorganization and cleanup

[Simos Xenitellis <simos lists googlemail com>]

On Sat, Apr 18, 2009 at 5:14 PM, Santi Béjar <santi agolina net> wrote:
> 2009/4/18 Owen Taylor <otaylor redhat com>:
>> ===
>> In Git, branches and tags are simply references to a commit. You can
>> check out a branch using the following command, once you have cloned the
>> project:
>>
>> git checkout [branch name]
>>
>> For a list of the available branches for a given project:
>>
>> git branch -r
>>
>> The following example will check out gnome-utils master and then check
>> out the 'gnome-2-0' branch:
>>
>> git clone git://git.gnome.org/gnome-utils
>> cd gnome-utils
>> git checkout gnome-2-0
>> ===
>>
>> That obviously doesn't work - it needs to show:
>>
>>  git checkout -b [branch name] origin/[branch name]
>>
>> For initially creating the local branch, and have some explanation of
>> what is going on.
>>
>> (It's a little confusing here to use git checkout -b to create the
>> branch... multiple things going on at once; but 'git checkout -b' has
>> the important side-effect of setting up the new branch to pull from the
>> origin, which you would have to do manually if you used 'git branch' to
>> create the branch.)
>
> git branch [branch name] origin/[branch name]
>
> also does the setup the same way as ´git checkout -b´.

In Git 1.6.1 or newer, one can do

git checkout --track origin/[branch name]

and this creates the [branch name] branch. The usability benefit is not having
to write the branch name twice.

It appears a common error with 'git checkout -b [branch name]
origin/[branch name]'
is that when you write by accident as 'git checkout -b origin/[branch name]'
the command succeeds, but it creates a local branch which is a copy of 'master',
and has the name 'origin/[branch name]'.
'git checkout' does not warn if you create a branch name with a '/' in the name.

In older versions of Git, the "git checkout --track origin/[branch
name]" syntax
does not work due to a bug, http://lkml.org/lkml/2008/12/25/8

«* "git checkout --track origin/hack" used to be a syntax error.  It now
 DWIMs to create a corresponding local branch "hack", i.e. acts as if you
 said "git checkout --track -b hack origin/hack".»

Simos