Quoting myself: >>> Don't you also want to talk about distinction between --cached and >>> --index that new people are often confused about? These options are >>> defined consistently across commands but people who do not know it bring >>> up discussions to rename --cached to some commands to --index to make it >>> inconsistent and waste your time every once in a while. > > Do you have any comment on the --index/--cached issue? Junio, I haven't heard back from you yet and I take it you mean you are not interested in a vague suggestion but in a concrete patch, so here it is. -- cut here -- 8< -- cut here -- Subject: [PATCH] gitcli: Document meaning of --cached and --index We saw this explanation repeated on the git mailing list a few times. Even though the description of individual options to particular commands are explained in their manual pages, the reason behind choosing which is which has been clearly explained in none of the documentation. Signed-off-by: Nanako Shiraishi <nanako3@xxxxxxxxxxx> --- Documentation/gitcli.txt | 38 +++++++++++++++++++++++++++++++++++++- 1 files changed, 37 insertions(+), 1 deletions(-) diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 2316049..281a987 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -133,9 +133,45 @@ $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT ---------------------------- +NOTES ON FREQUENTLY CONFUSED OPTIONS +------------------------------------ + +Many commands that can work on files in the working tree +and/or in the index can take `--cached` and/or `--index` +options. Sometimes people incorrectly think that, because +the index was originally called cache, these two are +synonyms. They are _not_ --- these two options mean very +different things. + + * The `--cached` option is used to ask a command that + usually works on files in the working tree to _only_ work + with the index. For example, `git grep`, when used + without a commit to specify from which commit to look for + strings in, usually works on files in the working tree, + but with the `--cached` option, it looks for strings in + the index. + + * The `--index` option is used to ask a command that + usually works on files in the working tree to _also_ + affect the index. For example, `git stash apply` usually + merges changes recorded in a stash to the working tree, + but with the `--index` option, it also merges changes to + the index as well. + +`git apply` command can be used with `--cached` and +`--index` (but not at the same time). Usually the command +only affects the files in the working tree, but with +`--index`, it patches both the files and their index +entries, and with `--cached`, it modifies only the index +entries. + +See also http://marc.info/?l=git&m=116563135620359 and +http://marc.info/?l=git&m=119150393620273 for further +information. + Documentation ------------- -Documentation by Pierre Habouzit. +Documentation by Pierre Habouzit and others. GIT --- -- 1.5.6 -- Nanako Shiraishi http://ivory.ap.teacup.com/nanako3/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
