summaryrefslogtreecommitdiff
path: root/Documentation/gitcli.txt
diff options
context:
space:
mode:
authorNanako Shiraishi <nanako3@lavabit.com>2008-07-01 23:02:40 +0900
committerJunio C Hamano <gitster@pobox.com>2008-07-01 17:29:38 -0700
commitaa0c1f2001e6d4fbc48401147541fcf7c84d7a0e (patch)
tree714f63a6e7d616481aa929586dd289d9d18de4cd /Documentation/gitcli.txt
parent483bc4f045881b998512ae814d6cf44d0c0cb493 (diff)
downloadgit-aa0c1f2001e6d4fbc48401147541fcf7c84d7a0e.tar.gz
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>
Diffstat (limited to 'Documentation/gitcli.txt')
-rw-r--r--Documentation/gitcli.txt38
1 files changed, 37 insertions, 1 deletions
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 2316049865..29e5929db2 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@vger.kernel.org>.
GIT
---