On Thu, Nov 30, 2006 at 07:58:09AM -0800, Linus Torvalds wrote:

So I wanted to make it clear that I never have that situation, because I 
never leave the index "dirty". I agree that there is nothing odd about it, 
but I think that people who don't actively use the index (or don't use git 
at all, and just worry about it) see it as a kind of separate entity with 
a life all its own.

Well, sure, because the documentation *talks* about it as a separate
entity all its own.  Just look at the man page for git-diff as a great
example of this, or the ascii art diagram of the index.  It is all
technically _correct_, but it is scary as all heck.

I can see that if you think the index is likely to be out of kilter with 
HEAD, you'd always worry about "ok, so maybe the diff I get from 'git 
diff' isn't the _true_ diff, so now I have to do _both_ 'git diff' and 
'git diff HEAD' to make sure I know what's up".

I just wanted to clarify that that is never the case for me, and I doubt 
anybody else really does it either. 

But then why is the default for "git commit" to commit the index, if
the index is almost == HEAD?  And why is git-update-index given such
prominence in the documentation?

In other words, the fact that the index _normally_ matches the HEAD may be 
obvious, but it's also important - it's important to allay fears from 
non-index users about it being somehow scary and confusing. It's not.

If everyone agrees with this, I think it would be easier to make
changes to the documentation and maybe some UI tweaks about what the
default might be.

One suggestion is that perhaps a mode where warns users when index !=
HEAD for certain critical commands might not be a bad thing.  That
might give users that are just graduating beyond novice git usage, and
just starting to become aware of the index, reassurance because if
they *don't* see the warning message, they can rest assured that they
don't have to do both "git diff" and "git diff HEAD", for example.