Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder <jrnieder@gmail.com>]

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.

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

Hope that helps,
Jonathan