Miles Bader <miles@xxxxxxx> writes: > Jonathan Nieder <jrnieder@xxxxxxxxx> writes: >> Do you think it would be valuable to introduce --added as a synonym >> for --cached and slowly steer documentation to encourage the latter >> in place of the former? > > "--added" sounds very awkward though; "--staged" is much more natural. Actually I think _both_ are equally wrong. I have to thank you and Jonathan for making me realize the real reason why "staged" didn't sit well in my ears. The word used as adjective nauseated me forever but I couldn't clearly explain why even to myself, but now I have the explanation. The index has data registered for paths. "add" (and "stage") are verbs used to describe the act of taking data different from what is currently registered in the index and replacing it. The phrase "added contents" thus can be (mis)interpreted to refer to only the subset of the data that is different from what you used to have in the index, typically meaning the ones that are different from HEAD, i.e. you would see the change in the output of "git diff HEAD". This is especially true because many people think in terms of "recording difference from the previous version" when they think about SCMs, and "--added" or "--staged" rhyme well with that mindset. This potential misinterpretation does not cause problems in some contenxt, and one such context is the hidden synonym "git diff --staged", which _is_ all about the subset of the paths that are different from HEAD. But as Jonathan in his message and you in your response brilliantly illustrated, misinterpreted "added" and "staged" break down badly in other contexts. When running "git grep" and "git rm" against the data sitting in the index, you do _not_ want to limit your request to the subset of paths in the index that are different from HEAD. "git rm --added" is not a command that chooses paths that are added to the index, and remove these paths from both the index and the working tree, but "added" would invite such a misinterpretation from new people. The adjective "cached" refers to the _state_ of the data for various paths in the index as they exist, regardless of when or how these contents were placed there. For the majority of the paths the "cached" data may have come from the HEAD, and for other paths, "cached" data may be something you have "added", but because "cached" is a state as it exists in the index, there is no distinction between the two. Because "cache" nor "index" are never used as verbs that mean the _act_ of putting updated things in the index, we do not risk --cached nor --index to get misinterpreted as limiting to the subset of the paths that are different from HEAD. At least that is how these four words (added, staged, cached and index) sound to my ears, and that is why I said the first two are equally wrong in the beginning of this message. It is an entirely different issue that "cached" is _not_ the best way to spell "index-only", though. -- 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