Re: [DRAFT] Branching and merging with git

From: Theodore Tso <tytso@mit.edu>
Date: Jan 8, 2007, 14:03 UTC
Message-ID: <20070108140305.GE32756@thunk.org>
In-Reply-To: <20070108023511.GI18009@fieldses.org>

On Sun, Jan 07, 2007 at 09:35:11PM -0500, J. Bruce Fields wrote:

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 11 quoted lines

> 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