Junio C Hamano wrote:
Felipe Contreras [off-list ref] writes:
quoted
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.
That's because Git is the only command tool that has such a concept.
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 ;-).
If you agree that explaining to users "the index is like a staging area", then
why just not call it the staging area?
Moreover, a staging area is not just a temporary dump, it is used in
preparation for something specific, and you might need to remove certain
weapons in place of better ones suited for the mission, that's why the word
"staging" is used.
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."
A buffer and a cache are two very different things used for two very different
purposes, and the term cache doesn't apply to "the index".
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").
All right, so that's progress; you do accept "the index" is not a good term.
Now, if you don't think "staging area" is a good term, do you have any that is
better?
This has been discussed for several years, and nobody has come up with a better
term, in fact, the vast majority of people prefer the term "staging area", and
it is already used in online documentation, including the ProGit book. It seems
inside and outside the Git project, the term has already been chosen.
Do you honestly think somebody is just suddenly going to come up with a better
term? How long do we have to wait before we decide X is the best term we could
come up with? One year? Two years? Ten years? Or do you just want to wait until
we have the "perfect" term, which might be never.
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.
Lets assume that "staging area" is not the best option, even though after
years of discussion nobody has come up with a better one. How would a different
term solve the problem you state above? If we use the term "commit draft", we
still could have people saying "draft # 2". So is there any term that would
avoid this problem, and is it really important to worry about such a marginal
problem?
Regardless of the term used, we can make sure it's not used in that context, so
I don't understand how that argument goes against "staging area". We can make
sure "staging area" is not used to denote the different "index" files.
Is this the *only* argument you have against the term "staging area"?
(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).
Or we can do what I already did to solve the problem:
git apply --stage --working-tree
* "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 grep --staged --working-tree
* "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.
git diff --staged --working-tree
--
Felipe Contreras