Subject: Re: [RFC] git-add update with all-0 object

From: Jakub Narebski <[email-masked]>
Date: Sat, 02 Dec 2006 09:35:52 +0100

Andy Parkins wrote:

> On Friday 2006 December 01 08:10, Daniel Barkalow wrote:
> 
>> My position on this subject is that "index" is a good name, but that
>> description is a terrible description, and "index" is a word that needs a
>> good description in context. If we just said up front:
> 
> If we need to explain what "index" means in the context of diff then it's not 
> a good name :-)

But "staging area" or more descriptive "staging area for commits" is
a bit long. But we no longer name the "index" "dircache".

> An index /everywhere else/ is a lookup table.  topic->page number; 
> author->book title.  record id->byte position.  There is never any content in 
> an index, indices just point at content.

Just like git index.

> I imagine that's how git's index got it's name.  (I'm only guessing as I've 
> not looked at what's actually inside git's "index").  Here's my guess:
> 
> git update-index file1 hashes file1, stores it somewhere under that hash and 
> writes the hash->filename connection to .git/index.  That is why git's index 
> is called an index.  It's a hash->filename index.

This "somewhere" is object repository. And it is reverse: it is 
filename->(stat + hash) index; from a file in the working area to the blob
(or tree) in the repository.

> Unfortunately, "index" in colloquial git actually means the combination 
> of .git/index plus the hashed file itself.  That's no longer an index, it's 
> a "book". :-)

Yes, it is true that "index" in colloquial git means "index version"
(version pointed by the "index").

> It's made worse, I think, by the fact that git doesn't want to do any 
> index-like things with the "index".  Being content-oriented rather than 
> name-oriented means that an entry like "file1->NOTHING" is impossible in git.  
> This leads to the sort of "git-add means track this filename" confusion that 
> turns up a lot with new users.

It is possible. By convention all-0 hash means 'no such object'. The very
first message in this thread tried to make use of it... but "git add" to
mark filename as interesting instead of "git add" to add _current_ contents
of the file goes a bit against git ideas.

> It's probably all too late to change the nomenclature, but I've always been of 
> the opinion that names are important, they confer meaning.  When we use a 
> common word, with common meaning and deviate from that common meaning we are 
> bound to create confusion.  New users don't have any "git-way-of-thinking" 
> knowledge when they begin, so when they hear "index" they can only fall back 
> on their standard understanding of that word.  We shouldn't be surprised then 
> when new users don't get "the index".

Well, "dircache" was changed to "index". "<ent>" was axed in preference
to "<tree-ish>". I think using "staging area" name in git man pages would
be a good idea (as would be making --index to be alias to --cached).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git