Subject: Re: [DRAFT] Branching and merging with git

From: "J. Bruce Fields" <[email-masked]>
Date: Mon, 8 Jan 2007 21:41:26 -0500

On Mon, Jan 08, 2007 at 09:03:05AM -0500, Theodore Tso wrote:
> 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.