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

From: J. Bruce Fields <bfields@fieldses.org>
Date: May 9, 2007, 17:18 UTC
Message-ID: <20070509171845.GC23778@fieldses.org>
In-Reply-To: <56b7f5510705090933t261e414es9e3cc63b28b60546@mail.gmail.com>

On Wed, May 09, 2007 at 09:33:40AM -0700, Dana How wrote:

Show 8 quoted lines

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