Re: [DRAFT] Branching and merging with git

[Theodore Tso <tytso@mit.edu>]

On Sun, Jan 07, 2007 at 09:35:11PM -0500, J. Bruce Fields wrote:
> chapters 1 and 2: "Read-only" operations:
> 
> 	clone, fetch, the commit DAG, etc.; material that could be
> 	useful to a linux kernel tester, for example.  This also
> 	includes lots of stuff about branch manipulation and fetching,
> 	just because that's necessary to keep a repo up to date and
> 	check out random commits.  Once we have "git remote" and
> 	disconnected checkouts most of this could be postponed till
> 	later.

I would add a QuickStart Chapter before you start going into the
"read-only" oeperations.  It would show how to create a completely
empty repository, and add a few commits.  It would also demonstrate
how to clone an example repository (with a fixed set of contents,
stored at git://git.kernel.org/pub/scm/git/example and add a commit
using "git commit -a".

The basic idea is to show the user that git really isn't that hard,
*before* you start diving into a lot of details.  If you don't tell a
user how to make a commit until Chapter 3, he/she will assume it's
because it's Really Hard, and you may end up losing them before that.

> Chapter 3: "Read-write" operations:
> 
> 	Read-write stuff: creating commits (basic mention of index),
> 	handling merges, git-gc, ending with distributed stuff:
> 	importing and exporting patches, pull and push, etc.

At least some discussions of branches needs to happen here; it's
really important to talk about different workflows, and how you use
branches as part of your read-write operations.  Some folks might or
might not use topic branches, but the concept of using temporary
branches to try things out is critical.

> Chapter 4 (unwritten): interactions with other VCS's
> 
> 	cvs, subversion.  Also some of us use track projects with git
> 	even when all we've got is a sequence of release tarballs to
> 	track, and that might be worth documenting.
> 
> Chapter 6 (unwritten): git internals
> 
> 	I intend to just do a wholesale import of either tutorial-2.txt,
> 	core-tutorial.txt, or the README, or some combination thereof,
> 	but can't decide which.

You might want to consider putting these two chapters into appendices.

						- Ted