Subject: Re: [FAQ?] Rationale for git's way to manage the index

From: "J. Bruce Fields" <[email-masked]>
Date: Wed, 9 May 2007 13:18:45 -0400

On Wed, May 09, 2007 at 09:33:40AM -0700, Dana How wrote:
> Geez,  this is similar [in nature, not scale] to what I've been doing.
> After reading about people "right-clicking on hunks in git-gui",
> I was convinced I needed to force myself to do more manipulations
> inside git itself.  Hmm...
> 
> Maybe, in addition to [or in] the User Manual, git should have some
> workflow examples, which have been cribbed from various emails
> on this list?

That's something several people have asked for, and I think it's a great
idea--I just haven't personally had much time to get to it.  But I'd
happily take even very rough patches and help get them into shape.

The way I'd thought of doing it was having an "examples" section at the
end of each chapter, with subsections for each individual example; see
the one at the end of the "exploring git history" chapter:

	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#history-examples

They shouldn't use the material introduced in the associated chapter,
but it's also OK to introduce new commands (with references to the man
pages) when their use in the example is pretty self-explanatory.  (In
fact, this is a great way to introduce more commands and options--git
has so many that it would be tedious to try to be comprehensive, but
they'd fit well in examples.)

The patch-editing stuff discussed above might fit best at the end of
"rewriting history and maintaining patch series".

--b.