Re: [DRAFT 2] Branching and merging with git

From: J. Bruce Fields <bfields@fieldses.org>
Date: Dec 4, 2006, 07:23 UTC
Message-ID: <20061204072350.GC28043@fieldses.org>
In-Reply-To: <20061204011958.GB28043@fieldses.org>

On Sun, Dec 03, 2006 at 08:19:58PM -0500, J. Bruce Fields wrote:

Show 6 quoted lines

> That doesn't mean *you* need to do everything from scratch, but it would
> be helpful to figure out where this would fit in with the other
> documentation in a logical progression.  As a start, the first paragraph
> could say "before reading this, we assume you've read X, Y, and Z", and
> then the rest of the document could be audited to make sure that it
> didn't assume anything that isn't in X, Y, and Z.

By the way, I have some draft rough work on getting that introductory documentation organized at

	git://linux-nfs.org/~bfields/git.git

See Documentation/user-manual.txt and Documentation/quick-start.txt. I think I've stolen a small amount of text from you--hope that's OK!

I have two ideas in mind:

	- The tutorial is supposed to a very quick "look what git can
	  do" document, but people also want it to really explain git,
	  prepare people to read the man pages, etc., which will make it
	  much longer over time.  So I'm trying to split out an
	  extremely concise "quick-start" guide (modelled partly on
	  Mercurial's) that doesn't even pretend to explain anything, and
	  a "user manual" that's much more verbose and tries to cover
	  the basics comprehensively.

	- A lot of people don't actually need to do commits or merges at
	  all--they just need to know how to clone a repository, check
	  out a few versions, etc.  (Witness the number of web pages
	  with "how to check out our latest code from CVS" out
	  there....) I'm also assuming most people are joining an
	  ongoing project instead of creating a new one.  So instead of
	  starting right away with init-db/add/commit, I'm putting off
	  actual "development" stuff till pretty late:

	  	1. clone
		2. checking out old versions, basic branch management
		3. keeping up-to-date with fetch
		4. bisect
		5. archaeology (commits DAG, git-log, ...)
		6. creating commits, index file
		7. resolving merges, pull
		8. publishing a public repository, push

	  etc.  I'm hoping you'd be interested in working together on
	  the last parts (7 and 8 especially).

Comments welcomed...