I think we can all agree that information should be behind a -v CLA. It's probably just something no one has thought of doing. I've learned over the decades to just ignore it.
One might reasonably think that about a number of git's rough edges, and one might be surprised at the reality.
Some years ago, the annoyance of git's inconsistent terminology drove me to look into consolidating "cache", "index", and "staging area" in git's help text and documentation. What I found was that others had (of course) thought of it before, but when they tried to do it, it was rejected by git's gatekeepers.
Contributions from jvns:
https://github.com/search?q=repo%3Agit%2Fgit+jvns&type=commi...
Here she explains how she did it:
https://jvns.ca/blog/2026/01/08/a-data-model-for-git/
Contributions I've made:
https://github.com/search?q=repo%3Agit%2Fgit+jaysoffian+docu...
Generically:
https://github.com/search?q=repo%3Agit%2Fgit+documentation&t...
Do you have a link to your proposal on the git mailing list?
The actual documentation is actually sensible, the issue is just that most people just learn from third parties, who are lax with terms.
> At the end user level, "cache" is only used as an adjective these days; "cached", meaning "contents cached in the index, not the contents in the work tree". We could have called it "indexed", but "cached contents" was an already established phrase from very early days to mean that exact concept, and we did not need another word that meant the same thing.
> There are some commands that take --index and --cached options, and even some that can take both (but not at the same time). Many people find this confusing, but there is a pair of simple rules:
"--cached" always means "work only on contents cached in the index, ignoring the work tree";
"--index" makes a command that usually works on files in the work tree also pay attention to the index.
"git apply" usually patches the files in the work tree without touching the index.
"git apply --cached" only updates the contents in the index without modifying the file in the work tree.
"git apply --index" patches both the contents in the work tree and in the index.
"git diff HEAD" shows a patch to update the contents in the HEAD commit to contents in the work tree.
"git diff --cached HEAD" shows a patch to update the contents in the HEAD commit to contents that is cached in the index. "git diff --cached" is a short-hand for "git diff --cached HEAD" only because the HEAD commit is what you most often would want to compare the cached contents with.
There is no "git diff --index HEAD" (yet); it would imply showing a three-way diff between HEAD, the index and the work tree.
"git grep" finds matches in the work tree.
"git grep --cached" finds matches in the contents in the index.
"git rm" removes both the file in the work tree and the corresponding path in the index.
"git rm --cached" removes the path from the index, leaving the file in the work tree untracked.There are 1000 things that's true of about git. At a certain point that becomes a problem in and of itself.
At least they gave us the `--porcelain` flag, meant exactly for this use case, to make the output format of porcelain commands never change. Dumb flag name, though.
This is very much a "if you don't like X about your country, just move to a different one" kind of "solution". The costs are extreme to the point that pretending it's viable is insulting. Really it's just a way to silence legitimate complaints.