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

From: J. Bruce Fields <bfields@fieldses.org>
Date: May 9, 2007, 03:45 UTC
Message-ID: <20070509034556.GC27980@fieldses.org>
In-Reply-To: <20070508145311.GA31152@diana.vm.bytemark.co.uk>

On Tue, May 08, 2007 at 04:53:11PM +0200, Karl Hasselström wrote:

Show 15 quoted lines

> I would introduce it with a paragraph or two right where committing is
> covered the first time. Explain that the empty file list box to the
> left contains the changes that will be committed when you press the
> commit button, and that the file list box on the right contains the
> changes that won't be committed. By clicking on a file name you get to
> see the diff to the file, and by clicking on the icon you move it to
> the other file list box -- that is, you stage/unstage it.
> 
> And now comes the clever part: Introduce the index, by explaining that
> it essentially _is_ the left file list box. Explain that git-add is
> the command-line equivalent of moving changes to the left box, and
> that git-commit without arguments simply commits what's in the index
> -- exactly like git-gui's Commit button.
> 
> I think it could work. :-)

Definitely, sounds fun.

For the in-tree documentation, maybe I'm just my crusty text-centric commandline point of view, but I'd rather have the primary explanation continue to depend only on text and commandline examples, and then add a note telling people that playing with git-gui may help develop their intuition for the way the index works.

But I think it'd be interesting to try out the above approach with screenshots, etc., on a web page someplace. It might also make a good visual aid for a talk.

--b.