Felipe Contreras <felipe.contre...@gmail.com> writes: > Junio, can you make an exception and reply to this thread? The change > to move away from the term "the index" has been suggested many times > since many years ago, it is an extremely important change to users, > and all the Git developers agree it must be done.
"It must be done" is different from "any change is good, as long as it introduces more instances of word 'stage'". As we established, we do not seem to be able to do a sensible design discussion with you without wasting time for nothing, I won't directly comment on that patch series, at least for now. However, since you asked, I would share a couple of comments regarding the index, cache and staging area. (1) "Staging area". The phrase "staging area" is not an everyday phrase or common CS lingo, and that unfortunately makes it a suboptimal choice of words especially to those of us, to whom a large portion of their exposure to the English language is through the command words we use when we talk to our computers. I personally do not mind explaining the index is "like a staging area, where an army piles up ammunition to a temporary dump before starting a major campaign." to native speakers, though ;-). The index can also be thought of "like the buffer cache, where new contents of files are kept before they are committed to disk platter." At least, non-native speaker with CS background would understand that, much better than "the index" (no, I am not saying that we should call it "the cache"; I am just saying "the index" is not a good word, but we may need to find a better word than "the staging area"). The noun phrase "staging area" and the verb "to stage" are good (especially when we do not worry too much about us foreigners), but we need to make sure "stage" is not mistaken as a noun when used in a context that talks about the index as a whole, to avoid confusion with the use of the word "stage" long established since http://thread.gmane.org/gmane.comp.version-control.git/231/focus=286 to call "ours" stage#2, etc. (2) "cached" vs "index". I think this is the more major issue between the two issues (the other one being "why do we force people to say 'index'?"). Some commands take "--cached", some others take "--index", some take both. What these two mean are documented in gitcli manual page, but that is far from sufficient. The users can get confused by this UI mistake in different ways. * We do need to have "git apply" that mimics "patch" (i.e. works only to a working tree files, or even outside Git repository) without any option, "git apply --mode1" that only applies the change to the index, and "git apply --mode2" that applies the change to both the index and the working tree. No renaming of "the index" does not change this need to have three different mode of operation. It was a major UI mistake to call one of the modes "--cached" and another "--index", because there is no way, other than rote learning, for people to choose the one between the two depending that is right for the situation they face. If "--cached" were called "--index-only", it might have been a lot more learnable (and then "--index" could be renamed to "--index-and-working-tree" at the same time to reduce the confusion further). Alternatively, with the synonym "--staged" for "--cached" already in place for "git diff", we could introduce "--staged-and-working-tree" as a synonym for "--index" to achieve the same effect (of course we need to find a way to shorten "-and-working-tree" part in a sensible way). * "git grep" barfs when given "--index", even though it does accept "--cached" and searches the patterns in contents that are in the index. This is technically correct, as the command does not search both in the index and in the working tree, but again, there is no way other than rote learning for users to tell that "--cached" is the correct one to use, even after they know that they want to search in the index (I already called it a major UI mistake, didn't I?). A new synonym "--staged" for "--cached" may be able to alleviate the confusion somewhat, given especially that "git diff" already knows "--staged" as a synonym for "--cached". I think a better end result will come if we taught "git grep --index" to actually search the patterns both in the index and in the working tree at the same time. There is no logical reason from the end user's point of view that "git grep --index" (aka "git grep --staged-and-working-tree") needs to fail; if we make the "--mode2" to mean to work on both the index and the working tree for any Git command when it makes sense, things will be more consistent, and it certainly makes sense to ask "git grep" to work on both the index and the working tree. We do allow "git grep -e pattern tree-ish-1 tree-ish-2" to search in multiple data sources already, so it can be seen as a logical extension. * "git diff --index [TREE-ISH]" has exactly the same issue as "git grep", and the same conclusion, i.e. it may be worthwhile to teach "git diff --index [TREE-ISH]" to give combined diff between the given tree-ish (defaulting to HEAD as usual), the index and the working tree. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html