Comment by 1718627440

Cache is like the old name, index is the new name, because the implementation didn't really make sense to use as a term for the users. Staging area was invented by third-parties as a term for training. Now Git uses --cached to mean only work on the context cached in the index and --index to mean also look at the --index. --stages exists as an alias for --cached for the people who want it, but it has no additional meaning and is not advertised in the documentation.

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.

> Here are a handful of examples.

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