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

From: Julia Evans <julia@jvns.ca>
Date: Aug 12, 2025, 21:43 UTC
Message-ID: <93133935-648a-4333-9272-c8528085499a@app.fastmail.com>
In-Reply-To: <xmqqpld0ql2e.fsf@gitster.g>

That sounds good to me, I'll remove the second sentence.

On Tue, Aug 12, 2025, at 5:36 PM, Junio C Hamano wrote:

Show 47 quoted lines

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