That sounds good to me, I'll remove the second sentence. On Tue, Aug 12, 2025, at 5:36 PM, Junio C Hamano wrote: > Chris Torek <chris.torek@xxxxxxxxx> writes: > >> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget >> <gitgitgadget@xxxxxxxxx> 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.
