Re: [1.8.0] use 'stage' term consistently

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 21, 2012, 01:12 UTC
Message-ID: <CAMP44s1Bghc6zXRQ7fJxJORiHqAgs5dg-8_cp_FoChnBG7oD4w@mail.gmail.com>
In-Reply-To: <7vzk92a76z.fsf@alter.siamese.dyndns.org>

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?

Show 6 quoted lines

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

Show 6 quoted lines

> 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