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

["J. Bruce Fields" <bfields@fieldses.org>]

On Tue, May 08, 2007 at 04:53:11PM +0200, Karl Hasselström wrote:
> 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.