On Tue, 19 Oct 2010, Matthijs Kooijman wrote: Note that the excerpt cited (quoted) below is directly from gitcli(7) manpage. > > * 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. Mnemonic: operate on _cached_ contents. We could use `--staged` instead of `--cached` here, but for me it doesn't as strong as `--cached` this meaning. > > > > * 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. Mnemonic: include _index_ (the name for concrete implementation of the staging area) in operation. We could use `--stage` here, but it would be confusingly similar to `--staged`. We could use `--include-staged` or `--also-staged`, but it is long and unwieldy, and doesn't read as nice. > > Doesn't this just offer opportunity for two new options? E.g., --staged > and --also-staged or --include-staged or something? In the current form, > these two options provide a variation of the same concept, using > completely different option names (which could lead people to think > that they're really the same option, just inconsistently implemented). That's why documentation is for. That is why we have gitcli(7). Sidenote: there were some proposal of including pseudo-ref name for cache/index/staging area (and for workdir contents), i.e. to use for example INDEX or STAGE instead of `--cached`... but they fell flat because `--cached` / STAGE is not exactly like the ref, and it felt like it would contribute to confusion rather than reducing it. > > So, regardless of changing over to --staged, I guess these two options > could be made more consistent (though sticking to the "index" > terminology is tricky, since that would require --cached to be become > --index and --index to become --include-index, which throws away > backward compatibility...). Breaking backward compatibility that badly is a big NO. Unfortunately the need for backward compatibility prevents us from some of improvements... > > FWIW, I do rather like the "staging area" concept, since I feel it > accurately describes its use (or at least the most common use of the > staging area). I also like "staging area" concept (and "to stage" as a verb), but there are some difficulties in applying it thorough and through. -- Jakub Narebski Poland -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html