Re: [1.8.0] use 'stage' term consistently

From: "Philip Oakley" <philipoakley@iee.org>
To: "Jonathan Nieder" <jrnieder@gmail.com>,
	"Mark Lodato" <lodatom@gmail.com>
Cc: "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 List" <git@vger.kernel.org>, "Jeff King" <peff@peff.net>,
	"Scott Chacon" <schacon@gmail.com>,
	"Paolo Ciarrocchi" <paolo.ciarrocchi@gmail.com>,
	"Jakub Narebski" <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: Sat, 19 May 2012 11:14:09 +0100	[thread overview]
Message-ID: <C03B8CAB76CA449FB887C5430FDAA470@PhilipOakley> (raw)
In-Reply-To: 20120519060031.GB23799@burratino

From: "Jonathan Nieder" <jrnieder@gmail.com>
Sent: Saturday, May 19, 2012 7:00 AM
> Hi Mark,
>
> 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.  As you
> said, staging a home is like staging a play, creating an illusion and
> putting on a production.  It is not obvious how this concept would
> help me understand what it means to add content to the index.
>
> By contrast, if you run an image search for "staging area", you will
> see examples in all sorts of fields --- shipping, military logistics,
> data warehousing, disaster relief.  It is a familiar, non
> domain-specific term for native English speakers.  In all these
> fields, staging means to put everything needed in one place before
> deploying.  This matches the concept of a file that tracks the content
> of the commit being prepared very well.

Agreed. (both sentences)
It's about making it up as you go along. (1: it = the commit ;-)
In particular it's about the 'area' (noun) that we use for that 
preparation.
Unfortunately there are no common terms because every industry, and
language, came up with its own terminology. To assist translation, we
should avoid being too concise in the explanation, while being 
consistent
with our base terms.

>
> "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.
>
> For the sake of having a proposal: :)
>
> - the file representing the content of the next command would still
>   be called .git/index and not be renamed
>
> - adding and removing content to and from the index is "staging a
>   change".  Since it is not safe to assume the reader already
>   knows what that means, when working on the manual authors should
>   try to imagine themselves as a new user and make the text
>   unambiguous enough to help such a person.
>
>   For example, the first sentence of the "git add" manual:
>
> This command updates the index using the current content found in the
> working tree, to prepare the content staged for the next commit.
>
>   should not be changed to:
>
> This command updates the staging area using ...
>
>   because that just makes it less clear.  Before, it said "the index"
>   and I could look in the glossary or the .git directory to at least
>   find what file it was talking about.  Afterwards, it is using an
>   everyday term and the new user wonders "which staging area?".
>
>   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

This line, if it is a carry on from the previous, also suffers the same
confusion. The index file by itself does not have any of the content. We
need to say in some way that - The 'staging area' has the content, and
is indexed by the index file. The staging area content itself is held
securely in the object storage ready for the commit.

> 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?  If so, patches welcome. :)  If not, what sort of changes
> would you like to see instead?
>
> By the way, I don't mean that "the .git/index file will not be
> renamed" above to be non-negotiable.  I didn't get the impression
> anyone wanted it to be renamed, but if someone does want to rename it
> to .git/staging-area, then I suppose we could discuss that.

I'd agree. The file is an index.

>
> Hope that helps,
> Jonathan
> --

Philip