Re: as promised, docs: git for the confused

From: Junio C Hamano <junkio@cox.net>
Date: Dec 10, 2005, 08:00 UTC
Message-ID: <7v7jadwfdj.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20051209054401.4016.qmail@science.horizon.com>

linux@horizon.com writes:

Show 16 quoted lines

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