Re: Officially start moving to the term 'staging area'

From: Drew Northup <n1xim.email@gmail.com>
Date: Sep 4, 2013, 04:45 UTC
Message-ID: <CAM9Z-nnjb1wUDH9e=E38QnWvPK44xZqvza77yNLrDpjpj47BKw@mail.gmail.com>
In-Reply-To: <CAMP44s3ABKMAhp_P+QZBWOfjp_wPkqB0A63v6n2mKZv_Ln+qKg@mail.gmail.com>

On Thu, Aug 29, 2013 at 6:10 PM, Felipe Contreras <felipe.contreras@gmail.com> wrote:

Show 13 quoted lines

> On Thu, Aug 29, 2013 at 4:55 PM, Drew Northup <n1xim.email@gmail.com> wrote:
>> On Thu, Aug 29, 2013 at 2:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> It has been discussed many times in the past that 'index' is not an
>>>> appropriate description for what the high-level user does with it, and
>>>> it has been agreed that 'staging area' is the best term.
>>>
>>> "add" is the verb, not "index" (which is a noun that refers
>>> to the thing that keeps track of what will be written as a tree to
>>> be committed next).
>>>
>>> And it will stay that way.

Show 5 quoted lines

>> I agree with Junio.
>
> All right, you are the only person (presumably other than Junio) that
> thinks "index" is the right name for what high-level users should be
> familiar with.

If that were true it would never have gotten that name. "Add" is the verb, as we are adding a snapshot. New users don't care how that works for the most part. Just telling them "it keeps track of it itself" is usually good enough. If the user is asking for more detail at that point it is probably because he isn't as much interested in how to use it as he is in how it works. At that point we're better off just giving him the actual explanation instead of getting caught up in the staging area vs index fight (which seems odd to me as the index contains the entries which act as a "staging area"--a superset / subset relation).

Show 14 quoted lines

>> We add content snapshots to the index of content (creating
>> "temporary"--they will be garbage collected eventually if they become
>> orphans--objects into the store at the same time). We build commits
>> from those snapshots (in whole or in part, typically only using the
>> most recent snapshots of new things added to the index) and save those
>> in the object store with the content and tree objects. Sometimes we
>> create tag objects to record something special about commits, trees,
>> and content blobs.
>>
>> That's the real model (with some rough edges). Explaining what that
>> has to do with distributed version control is the hard part.
>
> The user doesn't need to know the format of the index, or the packs,
> in fact, they don't even need to know the index or packs even exist.

I never implied that the end user does need to know these things. (Note the use of "We"--as in "we who are having this conversation.")

> All the user needs to know about this is that there's an area where
> contents of the next commit are being prepared, and "staging area" is
> the best name for that mental area. How that area is actually
> implemented (the index) is not relevant to the user.

Part of what I am arguing is that the mental area doesn't need to exist at all. The "staging area" is a part of the index. It is not the whole thing. There is no one-off complete replacement of one with the other. Most new users won't care about either, just that it happens somehow and that git keeps track of that state itself. We need not change any core items to achieve that.

> Everyone agrees on that, except you, and possibly Junio.

We don't have enough information to say that. Seriously, this is nowhere near as certain as climate change.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59