Re: [1.8.0] use 'stage' term consistently

From: Junio C Hamano <gitster@pobox.com>
Date: May 20, 2012, 21:11 UTC
Message-ID: <7vzk92a76z.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20120519060031.GB23799@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 14 quoted lines

> Mark Lodato wrote:
>
>> I agree with Felipe that "staging" is the most appropriate term for
>> "adding to the index" in git.  As a native English speaker, I have
>> never thought of "to stage" as relating to shipping in any way.  To
>> me, by far the most common usage is in real estate.  The seller of a
>> home "stages" it by setting up furniture and decorations to make the
>> home as appealing to prospective buyers as possible.
>
> I think staging a home does not fit very well here, actually....
> By contrast, if you run an image search for "staging area", you will
> see examples in all sorts of fields...
> "aire de rassemblement" doesn't get as many hits from a web search,
> alas, so I guess the idiom is not as popular in other languages.

All true.

Show 13 quoted lines

>    Instead, it would be better to change it to something like:
>
> 	This command modifies the content staged for the next commit
> 	using content found in the working tree.  It typically adds ...
>
> 	The "index" file (see gitindex(5)) typically holds a snapshot of
> 	the content of the working tree, and it is this snapshot that is
> 	taken as the content of the next commit.  Thus after making any
> 	changes to the working directory, and before running the commit
> 	command, you must use the add command to add any new or modified
> 	files.
>
> Sensible?

Comparing between the one before "Instead" and the above one, I would say it is.

I am hoping that we are not wasting people's time by the same experiment that already failed very early in Git's history to hide the "concept" of that which is used to shape the tree that would be recorded in the next commit that is different from either the current commit nor the contents in the working tree, and instead this round is about the name of that thing, which has been called "the index" and also colloquially known as "the staging area" in many third-party documents.

I personally think it is a wrong way of thinking to focus too much on the "name", though. The goal should be increased clarity and ease of learning. 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.

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

Another reason of my "mixed feelings" is that an interface organized around what is affected, instead of around what is achieved, may be counter-productive. "add" that adds the contents in the working tree (i.e. you already made the change you want yourself) to "that thing" makes sense from the work-flow point of view. It is how you edit, test or eyeball to convince yourself that you are happy with what is in your working tree, and then approach one step closer to your next commit.

An interface built around "that thing" may have a subcommand that adds contents to "that thing" regardless of what is in your working tree, but it is useful in only special occasions (e.g. in filter-branch script that does not want/need to use a temporary working tree). Such a functionality does have a place to live, namely at the plumbing level, but already is available as "update-index". But these commands that are organized around "what" they operate on are and should be of "specialized" kind, not "end user everyday activity" commands that are designed to give easier time to people in learning and using the system.