Felipe Contreras <felipe.contreras@xxxxxxxxx> 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html