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

On Thu, Dec 14, 2017 at 1:16 PM, David A. Wheeler [off-list ref] wrote:

"David A. Wheeler" [off-list ref] writes:

quoted

quoted

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 [off-list ref] wrote:

quoted

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 [off-list ref]
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 [off-list ref]
    Signed-off-by: Junio C Hamano [off-list ref]