Re: [1.8.0] use 'stage' term consistently

From: Junio C Hamano <gitster@pobox.com>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: "Mark Lodato" <lodatom@gmail.com>,
	"Junio C Hamano" <gitster@pobox.com>,
	"Ævar Arnfjörð" <avarab@gmail.com>,
	"Felipe Contreras" <felipe.contreras@gmail.com>,
	"Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>,
	git@vger.kernel.org, "Jeff King" <peff@peff.net>,
	"Scott Chacon" <schacon@gmail.com>,
	"Paolo Ciarrocchi" <paolo.ciarrocchi@gmail.com>,
	"Jakub Narębski" <jnareb@gmail.com>,
	"Johannes Schindelin" <johannes.schindelin@gmx.de>,
	"Piotr Krukowiecki" <piotr.krukowiecki.news@gmail.com>
Subject: Re: [1.8.0] use 'stage' term consistently
Date: Sun, 20 May 2012 14:11:48 -0700	[thread overview]
Message-ID: <7vzk92a76z.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <20120519060031.GB23799@burratino> (Jonathan Nieder's message of "Sat, 19 May 2012 01:00:32 -0500")

Jonathan Nieder <jrnieder@gmail.com> writes:

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

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