From: "Jonathan Nieder" <jrnieder@xxxxxxxxx>
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html