Re: as promised, docs: git for the confused

[Junio C Hamano <junkio@cox.net>]

linux@horizon.com writes:

> Like other version control systems, git has a current version (referred
> to as HEAD) in its object database, you make changes in the working
> directory, and then commit them, which appends a new version and makes
> that the new HEAD.
>
> However, there's also this "index" thing interposed.  As "man git"
> explains, you can have one version of the file in the HEAD, a second
> in the index, and a third in the working directory.  That's weird
> and confusing - why does git allow that?  Why isn't the index just an
> implementation detail that caches the HEAD until you commit a new one?
>
> The answer is merging, which does all its work in the index.  Being a
> toolkit, git has to pass partial merges around between its various
> tools, which means keeping track of multiple files all competing for
> the same name.  Neither the object database nor the working directory
> let you have multiple files with the same name.

I do not necessarily agree with this claim that merging is the
whole story about index.  As the steps in the hello/example
tutorial demonstrate, index is used to build up what you will
commit incrementally, and you can use this facility to view your
changes incrementally.

Your workflow could be like this:

    $ git checkout
    $ hack away
    $ git diff ;# what have I done so far?
    $ git diff HEAD ;# this one shows the same as the above.

    $ git update-index frotz ;# now I am satisfied with my progress so far.
    $ hack away further
    $ git diff ;# what have I done since my last "satisfactory checkpoint"?
    $ git diff HEAD ;# changes since the last commit -- this is
    		     # different from the above, and gives a lot
		     # more output
    $ git update-index nitfol ;# I am happy with what I've done
                               # to this file as well.
    $ hack away further
    $ git diff	    ;# changes since the checkpoint
    $ git update-index frotz nitfol
    $ git diff HEAD ;# final pre-commit review
    $ git commit

You could view updating the index as "checking in" and making a
commit as "casting your cumulative check-ins in stone".  You can
make "check in" as many times as you want, and there is "git
reset --mixed" to uncheckin the index changes.  And by doing
intermediate "checkins" to index file, you can limit what "git
diff" shows only to changes since your last checkpoint, as
opposed to all the changes you have made since your last commit.

This is sometimes very useful, and I suspect your comment about
"commit -a will take care of everything, so you do not need to
know about update-index" is coming from your ignoring this
aspect of update-index.