Re: [PATCH v2 00/14] Officially start moving to the term 'staging area'

Felipe Contreras <felipe.contreras@gmail.com> writes:

"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.