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 <nanako3@lavabit.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Nanako Shiraishi committed
Jul 1, 2008 at 23:02 UTC
aa0c1f2001e6d4fbc48401147541fcf7c84d7a0e
1 file changed
+37
-1
Documentation/gitcli.txt
+37
-1
@@ -133,9 +133,45 @@ $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT
133
----------------------------
134
135
136
+NOTES ON FREQUENTLY CONFUSED OPTIONS
137
+------------------------------------
138
+
139
+Many commands that can work on files in the working tree
140
+and/or in the index can take `--cached` and/or `--index`
141
+options. Sometimes people incorrectly think that, because
142
+the index was originally called cache, these two are
143
+synonyms. They are *not* -- these two options mean very
144
+different things.
145
+
146
+ * The `--cached` option is used to ask a command that
147
+ usually works on files in the working tree to *only* work
148
+ with the index. For example, `git grep`, when used
149
+ without a commit to specify from which commit to look for
150
+ strings in, usually works on files in the working tree,
151
+ but with the `--cached` option, it looks for strings in
152
+ the index.
153
+
154
+ * The `--index` option is used to ask a command that
155
+ usually works on files in the working tree to *also*
156
+ affect the index. For example, `git stash apply` usually
157
+ merges changes recorded in a stash to the working tree,
158
+ but with the `--index` option, it also merges changes to
159
+ the index as well.
160
+
161
+`git apply` command can be used with `--cached` and
162
+`--index` (but not at the same time). Usually the command
163
+only affects the files in the working tree, but with
164
+`--index`, it patches both the files and their index
165
+entries, and with `--cached`, it modifies only the index
166
+entries.
167
+
168
+See also http://marc.info/?l=git&m=116563135620359 and
169
+http://marc.info/?l=git&m=119150393620273 for further
170
+information.
171
+
172
Documentation
173
-------------
138
-Documentation by Pierre Habouzit.
174
+Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>.
175
176
GIT
177
---