Re: [PATCH] doc: Modify git-add doc to say "staging area"

From: Stefan Beller <sbeller@google.com>
Date: Dec 14, 2017, 21:28 UTC
Message-ID: <CAGZ79kbgbLEOTY9ziWz7gkUFKfpNVsZp5-r-jzd15PQ7iJZsGQ@mail.gmail.com>
In-Reply-To: <E1ePark-0008P4-Qx@rmmprod07.runbox>

On Thu, Dec 14, 2017 at 1:16 PM, David A. Wheeler <dwheeler@dwheeler.com> wrote:

Show 29 quoted lines

> "David A. Wheeler" <dwheeler@dwheeler.com> writes:
>> > Why is "index" better? It is a confusing name, one that has many
>> > other unrelated meanings.  In particular, many projects managed by
>> > git also have an index, but few have a staging area.
>
> On Thu, 14 Dec 2017 11:40:51 -0800, Junio C Hamano <gitster@pobox.com> wrote:
>> That's an absurd argument.  A database product that wants to be used
>> in library systems are forbidden to have "index" because that may be
>> confused with library index cards?
>
> No, because most database systems aren't designed to be primarily used
> in library systems.  Even if they are, I haven't seen a "library index card"
> in decades (many people will not know what they are), so
> that is much less likely to be confusing.
>
> In contrast, git is widely used to manage source code (where "index" often
> means "array index", "hash index", and so on) and/or HTML
> (where "index.html" is pretty common).  Using the *same* term for something
> git often manages *is* confusing.
>
> Even if you don't buy that argument, I think most newer users find the term
> "staging area" simpler... and we are *all* new to something at one time.
>
> A Google of git "staging area" returns 67,000 results, and "staging area"
> is *much* newer terminology than "index" and has those hits in *spite* of
> "index" and "cache" being the historical terms.
>
> Is there a term you'd prefer over "index" or "cache"?
>

I would personally prefer to drop 'cache', as the mechanism involved is not a cache from the users point of view. (A cache is not affecting behavior except for performance. In Git this "index" does affect more than just performance, it also allows a very specific workflow.)

Personally I am indifferent to whether we call it index or staging area as long as it is consistent. Junio mentioned the 'X acts like Y' is different from 'X is Y'", so maybe we can use both words, as in "Use git-add to add files into the index, which is used as a staging area for the next commit".

Note that this discussion seems to be quite old (way older than my contribution record):

    $ git log --grep "staging area"
...
commit 11920d28da1ac1b65eb4041c1b7355924e5d1366
Author: Scott Chacon <schacon@gmail.com>
Date:   2008-12-01 22:14

    Add a built-in alias for 'stage' to the 'add' command

    This comes from conversation at the GitTogether where we thought it would
    be helpful to be able to teach people to 'stage' files because it tends
    to cause confusion when told that they have to keep 'add'ing them.

    This continues the movement to start referring to the index as a
    staging area (eg: the --staged alias to 'git diff'). Also adds a
    doc file for 'git stage' that basically points to the docs for
    'git add'.

    Signed-off-by: Scott Chacon <schacon@gmail.com>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>