Earlier quoted context omitted.
> It's probably just something no one has thought of doing. 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 wh…
Are those three really all the same things? That seems crazy to have all three not consolidated.
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.