Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras <felipe.contreras@gmail.com>]

On Sun, May 20, 2012 at 11:11 PM, Junio C Hamano <gitster@pobox.com> wrote:

> I personally think it is a wrong way of thinking to focus too much on the
> "name", though.

Names are important. Name it 'jaberwocky' and people would have a
harder time trying to understand what you are talking about. Maybe
just by hearing the name they would give up, thinking it's too
advanced, or too obscure, or what not.

There have been countless people that say "me too! when I realized it
was X", which suggests the current name does not help.

> The goal should be increased clarity and ease of learning.

And using a common/well understood name is a step in the right direction.

But also, once we accept that "that thing" is not an index, then it
becomes much more easy to distinguish between the abstract concept,
and the actual index, and then we can begin to remove the index from
the high-level documentation and squash it to a corner where the user
does not _have_ to go unless she really does want to know the
implementation details.

Right now it's almost impossible to split the "index", and then index.

If the name is not important, why do you think people avoid the official name?

> For example, the first sentence in your example reads equally well if it
> said "the content _prepared_ for the next commit" without losing clarity
> and tells the most important thing it must tell the user: that "add" is
> about updating "that thing" that is different from the working tree and
> the latest commit, even if "stage" (verb) does not translate well to other
> language.

Indeed, but you are missing the important part; everything else in
that sentence.

I will put my end-user hat and read while thinking aloud the current text:

"This command updates the index"

OK, you lost me there. I don't know what is that "index", do I need to
learn what is that in order to understand the command? Maybe I
shouldn't be reading this documentation at all.

But, OK, let's give it a try... Right, an index, well, an index of
what to what? No idea. Maybe if I keep reading.

"using the current content found in the working tree, to prepare the
content staged for the next commit.

OK, maybe I'm beginning to understand... But I'm still not sure if I
should be touching this index thing, I don't understand what is being
indexed.

> About the "git stage --add/rm" commands in your follow-up message, I have
> mixed feelings.  Once users get that making progress and growing history
> with Git is all about interacting with "that thing", writing out a new
> tree out of it and recording it in a new commit with appropriate parents,
> saying "stage" becomes redundant.  You "add", "remove", "patch", etc. to
> affect that is recorded in "that thing" (e.g. you do not "add" to commit).

While I would not like to touch the 'git stage' at this point--nor do
I think it's needed--, I don't agree with what you said. In certain
commands it might be redundant, but I specially disagree on these:

The 'add' command has a long tradition in SCM; it adds a file for
content tracking--nothing more.

Using 'add' to *update* the staging area seems completely and totally
counter-intuitive to me. Adding something means that something was not
there; if it was there, you couldn't add it.

Of course, that's if you think about files, but it makes sense if you
think about changes instead, but 'git add file' and 'git add file' do
very different things conceptually depending on weather 'file' was
tracked or not; one would "add a file" (to git), and the other would
"add the changes of the file" (to the staging area). Splitting the
command in two would make this difference in concepts clearer.

And then we have all sorts of confusion. --patch; I thought we were
adding patches to the staging area, this is redundant, --selectively
might make more sense. --update; I thought we were updating! --updated
might make more sense. And what happens when you do 'git add --patch
untracked-file' (or --update)? That's very strange.

If we have a 'stage' command things become much simpler:

git add untracked-file # maybe as the current 'git add --intent-to-add'
git add tracked-file # no-op (error?)
git add --patch file # doesn't make sense; option not present
git add --update file # doesn't make sense; option not present

git stage untracked-file # add, and stage it, why not?
git stage tracked-file
git stage --hunks file
git stage --updates file

At this point 'git add' would not be doing much, and might even go
away, but I guess it's nice for people coming from other SCMs.

'rm' is similar, could be solved by 'unstage'.

Either way, I have proposed to use stage/unstage before I think,
without much success, so I think the only realist option to move
forward is to add --stage(d) and --stage-only.

Cheers.

-- 
Felipe Contreras