Re: Git documentation reorganization and cleanup

[Owen Taylor <otaylor redhat com>]

On Fri, 2009-04-17 at 16:13 -0700, Sandy Armstrong wrote:
> Hi all,
> 
> Just a quick note that I've been working a bit on cleaning up our git
> documentation.  It is now centralized here:
> 
> http://live.gnome.org/Git
> 
> And the main developer howto has been simplified.  It now recommends a
> single simple workflow of hacking, making a single commit, and
> generating a patch using `git format-patch HEAD^`:
> 
> http://live.gnome.org/Git/Developers
> 
> I really want to keep this page comprehensible for new contributors,
> as much as we can.  If you have ideas for how to improve it, any help
> is welcome.  Please keep in mind that I'm actually pretty new to git,
> and may not be aware of better workflows for new contributors.

Thanks a lot for working on this, Sandy. One area that someone could fix
up is the section in /Developers about branches whiich currenlt ysays:

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

- Owen