Recent documentation patches, and an RFC on terminology

I just sent two documentation patches to the list in quick succession. In case they arrive out of order: the first, smaller one - modifying only the git-status documentation - should be applied before the second one (distinguishing between "staging area" and "index" throughout the documentation).

We may have an opportunity to improve on the term "staging area". As I reflect on it, I think replacing that with the term "depot" might not be a bad idea. In English this word has the general sense of "warehouse", and the more specialized connotation of a place where freight is temporarily held for transshipment, or where military supplies and recruits are mustered before field deployment. That is, a depot is a particular kind of staging area.

Since these terms are so similar, why change?

One reason is that --depot would be a shorter and more graceful choice than --staging-area as a long-form option. It has the same letter count as "index", so changing command and option names to use it wouldn't add more typing.

Another reason is that "depot" is slightly more distant from normal English vocabulary than "staging area" is. When you need a word to co-opt as a technical term of art, thast's an advantage; it reduces the chances of collisions between term-of-art and normal usages.

If this proposal is accepted, I can very easly generate a patch to implement it. Teasing apart "index" from "staging area" was actual work, but now that the distinction has been made replacing the latter would be trivial.

On 2010.04.23 17:54:48 -0400, Eric Raymond wrote:

IIRC Perforce already uses the term "depot" for something that's not quite git's index (your other mail didn't make it to me yet, so I couldn't quickly look up how you differentiate between the "staging area" and the index). There have been people in #git that used the term "depot", and till now I simply guessed that they meant "repository", and that seemed to fit. Introducing git's own definition of "depot" will probably cause confusion when talking to (former) perforce users, so I'd rather avoid that term.

Björn

Björn Steinbrink <B.Steinbrink@gmx.de>:

*Groan*...is the Great Galactic Ghoul randomly eating my patch submissions again? I'll check the archives...

Basically, I changed the docs to use "staging area" when talking about workflow and "index" only when describing implementation.

On Fri, 23 Apr 2010, Eric Raymond wrote:

If so that should be a good thing.

Nicolas

Nicolas Pitre <nico@fluxnic.net> writes:

Do you mean that Ghoul did a good thing to eat such a change?

On Sat, 24 Apr 2010, Junio C Hamano wrote:

:-)

I meant that the proposed change to the doc as described above should be a good change.

Nicolas

On 4/23/10, Eric Raymond <esr@snark.thyrsus.com> wrote:

I didn't get the patch which distinguishes index vs. staging area, but I did get 'Typo fixes and minor cleanups for the big "index"/"staging area patch', so I can see some of what it did.

Based on my limited view, I think it makes things more confusing. I'd rather see references to the index be replaced with "the staging area (a.k.a. the index)" than long winded explanations like "the index is the structure used to store the content of the staging area" or "the staging area used to be called the index".

To me, "depot" has connotations of transportation. A depot is a place to catch a train or a bus.

Staging area describes exactly how we use the index. An area where things are staged (prepared) to be committed.

Why not keep index as a synonym for staging area and use --index?

I haven't seen such collisions causing problems.

Adam

Hello Eric,

For what it's worth: I am a non-expert git user and I find the name "staging area" to be perfectly adapted. With this terminology, it makes it easier for me to explain some git principles to new git users.

The name "depot" is confusing because there is no expectation of a following action. I already see this question coming: "can I leave my files in the depot now?"

  -- aghiles