X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgitcli.txt;h=29e5929db22257346a2bed16cbd5ca6531698676;hb=3f74c8e8d8721d093655d7bb00ead078d8324100;hp=23160498659a1e315ecd2976dfc348f28d26469c;hpb=24cd49f627ab0d313f8f7925e1f6f855563fea43;p=git.git 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 ---