Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to
From: しらいしななこ <hidden>
Date: 2016-06-15 22:44:51
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to · Avery Pennarun <hidden>
- 2016-06-15 · Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to · Theodore Tso <tytso@mit.edu>
- 2016-06-15 · Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to · Junio C Hamano <hidden>
- 2016-06-15 · Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to · Petr Baudis <hidden>
- 2016-06-15 · Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to · Johannes Schindelin <hidden>
Quoting myself:
quoted
quoted
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 <redacted> --- 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/