Re: [DRAFT] Branching and merging with git

From: J. Bruce Fields <bfields@fieldses.org>
Date: Jan 9, 2007, 02:41 UTC
Message-ID: <20070109024125.GD1686@fieldses.org>
In-Reply-To: <20070108140305.GE32756@thunk.org>

On Mon, Jan 08, 2007 at 09:03:05AM -0500, Theodore Tso wrote:

Show 11 quoted lines

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

Yeah, I agree. I just haven't been able to decide quite what to choose for that purpose. Some choices:

	- We could just pare down the tutorial a bit and drag it in as
	  chapter one.

	- I tried writing something modeled loosely on the hg quick
	  start.  It's a little out of date now, but that could be
	  fixed:

		http://www.fieldses.org/~bfields/git-quick-start.html

	- Or maybe a revised everyday.txt would do the job?

Any opinions?

> At least some discussions of branches needs to happen here;

The basic nuts-and-bolts (how to create and delete branches, etc.) should all be covered, of course, but....

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

.... Maybe it'd be fun to have a section called just "examples" at the end of each chapter. The sort of thing you're describing could fit in well there. I'd need some help collecting interesting examples.

--b.