Re: friendlier names

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 27, 2009, 18:28 UTC
Message-ID: <7vwscgy56b.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20090127153837.GB1321@spearce.org>

"Shawn O. Pearce" <spearce@spearce.org> writes:

Show 14 quoted lines

> David Abrahams <dave@boostpro.com> wrote:
>> 
>> For example, why couldn't the "index" be called the "stage" instead?
>> That, along with knowing that "git add" was a synonym for "git stage"
>> would have flattened the learning curve considerably for me.
>
> Historical reasons...
>
> Waaay back the "index" was an index of the files git knows about in
> your working directory.  It made sense to call it an index, as like
> a book index it was a full listing of what's here, sorted by name.
>
> That's pre-1.0 days.  Like the very first version Linus ever
> released.  Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.

This part is a bit misleading, if not completely incorrect.

Since day 1, the entity we now call "the index aka staging area" has been just that. It was originally called "cache" and it implemented a cache of _contents_ that are meant to go in the tree the next commit records. It was renamed to the "index" because it is an index, which you can consult with a pathname as the key to get to the _contents_ as its value.

It never was "list of pathnames" without _contents_. So it was a staging area from day one.

The way to update the cache was called "update-cache" then "update-index". Because it usually is much rare to actually add a new entry to the index than updating an existing entry in the index, the command had a safeguard against "update-cache a-newfile" without explicit request from the user to say "oh by the way I know I am adding new entries". "git add" came much later to give you a shorthand for "update-index --add". Updating existing entries in the index was still done with "update-index".

Later Nico taught (after much discussion) "git add" to also serve as "update-index" for existing entries in the index.

We could have called it "git update-index" when we did that switch-over, because the operation is exactly that --- updating the index.

But the name somehow stuck.

> Only late last October at the GitTogether did we start to talk about
> creating a command called "git stage", because people have started to
> realize we seem to call it a "staging area" as we train newcomers...

Yeah, you may have to consider the possibility that that particular training lingo is inconsistent with the rest of the system, exactly because it came from outside.