From aa0c1f2001e6d4fbc48401147541fcf7c84d7a0e Mon Sep 17 00:00:00 2001 From: Nanako Shiraishi Date: Tue, 1 Jul 2008 23:02:40 +0900 Subject: [PATCH] gitcli: Document meaning of --cached and --index We saw this explanation repeated on the 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 not been clearly explained in any of the documentation. Signed-off-by: Nanako Shiraishi Signed-off-by: Junio C Hamano --- Documentation/gitcli.txt | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 231604986..29e5929db 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 the git-list . GIT --- -- 2.26.2