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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 12, 2025, 21:36 UTC
Message-ID: <xmqqpld0ql2e.fsf@gitster.g>
In-Reply-To: <CAPx1GveEX_r8thqpux0jcbEsEyLpNOvRWEvogUp4m_cNC5=dbw@mail.gmail.com>

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

Show 13 quoted lines

> 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.