That's what they actually are, you just get an interactive type through for selecting your number. You can just type it all at once if you already know it.

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.

It's also a statement, whether you want callers to pass the same object to different parameters. If that doesn't make sense or you don't want that, write restrict.

For availability and stability concerns, the C approach is actually better, but for security and reproducibility, it is not.