Re: [PATCH 5/5] doc: git-add: explain inconsistent terminology

[Junio C Hamano <gitster@pobox.com>]

Chris Torek <chris.torek@gmail.com> writes:

> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> +TERMINOLOGY NOTE
>> +----------------
>> +
>> +Git uses the terms "staging area", "index" and "cache" interchangeably
>> +for historical reasons. Many commands have flags like `--staged`,
>> +`--index`, or `--cached`, and they all refer to the index.
>> +
>
> I think this is also a good idea. Unfortunately, `git apply` has two
> different meanings for `--index` vs `--cached` (I believe it's the
> *only* exception to the "means the same thing" rule...).

Yes, I think the first sentence is an excellent addition, even
though I do not know if "git add" is the best place to teach it.

However, it will be disservice to users to say "they all refer to
the index" here.  Yes, it is technically correct that they all refer
to the index, but that much any intelligent readers can infer after
reading the first sentance that historically these three words were
used to refer to the same "index".  And what I think is bad in that
second sentence is that it implies they may mean the same thing
without saying that.  It is perfectly fine to say that these three
words express some operation around the index (sometimes called the
staging area).  It also is fine to say that "--staged" is sometimes
used as synonym for `--cached`.

But at least `--cached` and `--index` mean quite different things.

As "git help cli" explains, an operation that can affect only the
index would use "--cached" and both the index and the working tree
would use "--index".

It may be that "apply" is currently the only exception (I did not
check), but it certainly is not guaranteed to stay to be the only
exception.  If a command wants to work on both the contents in the
index and in the working tree, such a command is very much welcomed
to use the option "--index" to trigger such a mode of operation.

Conclusion?  I would rather see "Many commands have ..." sentence
struck out.  After all, that does not need to be taught to those who
came here to learn about "git add".

Thanks.