The concept of the staging area is one which many newcomers struggle with when starting to learn git, and the fact that this concept is barely mentioned in the official documentation (i.e. man pages) doesn’t help at all. Instead the official name is “the index” which has absolutely nothing to do with the way users interact with it. That’s the reason most people who teach git prefer to use the term “staging area” instead, and in fact that’s the term used in the best available documentation: the Pro Git book (which is not official), and also pretty much in all online documentation, including tutorials and blog posts (e.g. Atlassian saving changes, code refinery).
Attempts to move away from the incorrect term “the index” towards one that most native and non-native English speakers can grasp without the need for further explanation have been attempted for more than a decade, and even though there’s universal consensus that “staging area” is by far the best alternative, attempts to use it officially in the documentation and user interface have been blocked because one person cannot be convinced.
This is a summary of 13 years of discussions regarding the term “staging area”, similar to my previous post about 13 years of discussions regarding
git stage and
The first thread happened in 2008, when David Symonds suggested the addition of a new command:
git staged. This command was basically an alias for
git diff --cached, and it was a result of a discussion in GitTogether ’08. While this command was not considered seriously (and in fact it wasn’t proposed seriously), it did result in the
git diff --staged alias. This is the first time I suggested a
git stage command.
Soon after Scott Chacon–a famous git trainer and author of the Pro Git book–suggested a
git stage command that is basically an alias for
git add. This time the proposal was serious and Scott offered a good rationale:
This continues the movement to start referring to the index as a staging area (eg: the –staged alias to ‘git diff’). Also added a doc file for ‘git stage’ that basically points to the docs for ‘git add’.
Neither Jeff King nor Junio C Hamano (the maintainer) objected, so it was immediately merged.
In 2009 David Abrahams suggested the “index” should be called “staging area” as that’s a more friendly name, and he expressed that
git stage would have helped his learning curve. Shawn O. Pearce–who unfortunately passed away–gave a pretty good summary of the history of the “index”, which basically resumes to: it’s historical baggage.
Only late last October at the GitTogether did we start to talk about creating a command called “git stage”, because people have started to realize we seem to call it a “staging area” as we train newcomers…Shawn O. Pearce
Junio objected to Shawn’s history lesson claiming it was “a bit misleading, if not completely incorrect”, and also objected to the way “the outside” referred to the index:
Yeah, you may have to consider the possibility that that particular training lingo is inconsistent with the rest of the system, exactly because it came from outside.Junio C Hamano
Jakub Narebski–a prolific developer and community member–also said it was a pity
git stage wasn’t there from the start, but Junio quickly disagreed.
I simply agreed that “staging area” is a more friendly name.
git stage, I proposed a more comprehensive command with subcommands, so instead of doing
git diff --caced, the user could do
git stage diff.
Junio did not like the idea at all:
I do not think these are good ideas at all, as it just spreads more confusion, not less.Junio C Hamano
I argued that there’s a lot of confusion already: stage, cache, index, etc. And it’s not just me the only one who sees that confusion.
Perhaps not spreading “stage” even wider? That is the newest confusing term that caused the most harm.Junio C Hamano
Junio proceeded to blame the “git training industry” (e.g. Scott Chacon) for using the term “staging area” instead of “index”:
Later, some outside people started “git training industry” without talking with the git development community and started using a new term “to stage” as a verb to describe “add to the index”. Addition of “git diff –staged” was supposed to lesson the confusion resulted from this mess, but as we can see from your patch it had a reverse effect.Junio C Hamano
In his opinion to avoid confusion
--cached should not have been existed at all, and the command should have been
git diff --index-only. He also opined that he should have rejected “stage” as an option name (and a command) (in favor of –index-only).
I thanked Junio for his clarification, but I also explained that there’s no porcelain command (intended for common users) that uses “index” in any way. Moreover, I explored what “cache”,”index”, and “stage” mean in English, and the high-level notion of most people do not match what “cache” and “index” actually mean.
In git it is barely used, mostly on the “documentation industry” probably because it’s easier to understand for most people (even non-native-English speakers).Felipe Contreras
Markus Heidelberg argued that my proposal didn’t match his mental model:
Not for me. If I want to GET a diff, I want to use a command “diff”, so “git diff” is more obvious.Markus Heidelberg
I argued that this was a matter of preference, but his preference would not be hindered in any way: we could have both
git stage diff and
git diff --staged. Additionally I argued that
git diff is used in two fundamentally different ways, moreover we already have command/subcommand instances (e.g.
git remote add).
Well, it’s a matter of preference, and you would not loose the option to do it the way you like. But actually, “git diff –cached” is a different action; you can’t do “git diff –cached HEAD^..” for example.Felipe Contreras
Curiously enough when Markus argued back that you could not do
git stage diff HEAD^.. either, it was Sverre Rabbelier–another prominent developer back then–who did the mic drop for me:
I rest my case ;). That’s the whole point Felipe is trying to make here.
$ git diff --cached
$ git diff HEAD^..
That’s two different modes of operation with the only difference being a switch (‘–cached’), which changes what is, and what is not valid after that.Sverre Rabbelier
David Aguilar mentioned an old thread in which an alternative style for git diff was proposed by using STAGE and WORTREE as pseudo commits. Unfortunately a lot of the following discussion was about this proposal, and not mine.
Junio disagreed with this proposal as well, and stated he didn’t think there’s any usability issue:
I do not think there is any usability issue. Why do you think saying STAGE in all capital makes it easier to use instead of saying –cached (or –index-only)? In either way, you need to understand the underlying concept, such as:Junio C Hamano
There is most definitely a usability issue here. I use git every day and I cannot for the life of me remember all the inconsistent stage-related oddball commands. I have a number of aliases for them (similar to what Felipe is proposing) which are the only way I can remember them. Whenever I find myself using a git repo without those aliases, I have to fire up the man pages. Trying to explain all of this to coworkers that use git—honestly, I don’t even try to go there.Stefan Karpinski
Nothing materialized out of this discussion.
In a side-thread when I tried to improve the user-manual, and argued that color should be enabled by default (
color.ui=auto), Jonathan Nieder–the most prominent developer–asked me what were some of my UI patches that might have been overlooked:
Could you list some UI patches that were overlooked or not properly addressed? Maybe people just forgot about them or were waiting for an updated version, or maybe the problems some solve weren’t articulated clearly yet. I would be glad to help out in any way I can.Jonathan Nieder
I mentioned my patch for
git stage and attempts to standardize
--stage as examples where there’s clearly a UI problem. But the real problem is that even though it’s clear by virtually everyone that there’s a problem, a path forward doesn’t seem to be there.
Michael J Gruber argued back that basically the reason he decided to disengage with this particular patch series is that “I didn’t seem to be willing to accept advice” (which obviously was not the case, since I had already included all his advice):
Regarding this specific patch series: I took part in the initial discussion, and got frustrated by the original poster’s seemingly unwillingness to accept advice, so I left. I’m not drawing any general conclusions, and please don’t take this as an ad hominem argument. Sometimes it’s simply a matter of mismatching participants.Michael J Gruber
Additionally he argued that
--cache are fine, because two options are needed on some commands, which although true that still doesn’t address the issue of the names, as I argued:
“good” is a very subjective term; I don’t think “they are different” is a good reason. By that logic –only-index and –index-and-working-dir serve the same purpose, just like –gogo and –dance.Felipe Contreras
Nanako Shiraishi piled on the ad hominem angle:
I don’t think Felipe seriously wants to change them to –gogo vs –dance, but if he made a more constructive proposal, instead of making such a comment whose intended effect is only to annoy people, we may see an improved UI at the end. Proposing “–index-only” vs “–index-too” or even “–stage-only” vs “–stage-too” would have helped him appear to be more serious and constructive and I think your expression “mismatching participants” was a great way to say this.Nanako Shiraishi
I don’t know how anyone can think that assuming bad faith is a more constructive way to achieve anything, clearly my intention was not to annoy people, but to demonstrate a point. It is a common rhetorical device called reductio ad absurdum, it’s not uncommon on the git mailing list to use it, and even Junio uses it regularly.
My point was that any two names would solve Michael’s concern, the whole issue is that names would those be, and before exploring any names, developers–and in particular Junio–need to accept there is a problem with the existing names. When I explained that to Nanako she didn’t back down:
You have a funny way of saying “I’m sorry, I wasn’t constructive, and my attitude repelled many participants from the discussion”.Nanako Shiraishi
Which of course is not what I was trying to say at all. Moreover, she said that because “stage” is not very user friendly to her, the word we use is irrelevant, and everyone would agree with her:
I think a proposal to replace the word “index” with “stage” will sound nothing but bike-shedding to anybody, especially after getting familiar with “index” and seeing it taught on many web pages and books.Nanako Shiraishi
Instead of my usual “blunt” style of communication I tried to appeal to Nanako’s sensitivity and empathy, in order explore the possibility that even though she doesn’t particularly see a useful difference between the words “stage” and “index”, that doesn’t mean other people don’t either:
I’m going to change my usual blunt style and try to be sensitive here: I’m not trying to blame you, or disregard your background. I’m not a native English speaker either (although my tongue language is a romance one, so perhaps I have some advantage), but to me, English is a language of short words, and therefore, the exact word you pick makes a world of difference, and this is something I feel many non-english speakers don’t appreciate. Since we all are communicating in English, I think we should not disregard “subtle” differences in words such as “cached” and “stage” that might not mean much to you, but I think it would to the thousands (or millions) of git users who do understand immediately the meaning of “stage” regardless of their git (or any other SCM) background.Felipe Contreras
I then explored at great length all the different meanings of the word “stage”, and also to some extent the word “index”. As a reward for my efforts my reply was censored and removed from the mailing list archive. I’ve uploaded the email in its entirety so you can see for yourself if there’s anything objectionable there.
Regardless of on which side you are on, Nanako did not object to the word “stage”, all she did is state that to her the word is irrelevant, and in her opinion I was bikeshedding. As we will later see Nanajo was wrong: most people did not consider it bikeshedding.
Nothing particularly productive came from the rest of the discussion.
Git User’s Survey
Since I pretty much gave up on convincing Junio using arguments, I thought it was a good idea to ask users directly if they thought the term “staging area” was better. So I proposed to Jakub Narebski who spearheaded the Git User’s Surveys, and he thought it was idea. Of course we couldn’t ask the question directly, that would bias the responses, so I proposed simply asking if users used the “index/cache/stage”.
In 2011 Piotr Krukowiecki asked if there was a plan to use a consistent term, instead of three.
Junio once again explained why he did not like “stage”:
In short, “stage” is an unessential synonym that came much later, and that is why we avoid advertising it even in the document of “git diff” too heavily. Unlike the hypothetical –index-only synonym for –cached I mentioned earlier that adds real value by being more descriptive, “staged” does not add much value over what it tried to replace.Junio C Hamano
Pete Harlan explained why “staging area” is better:
FWIW, when teaching Git I have found that users immediately understand “staging area”, while “index” and “cache” confuse them.Pete Harlan
Aghiles also agreed with Pete.
Once again I brought up my proposed
git stage command with subcommands. This time Michael J Gruber expressed that he liked the idea a lot, but stated that the design deviates from the common form. Of course this isn’t true since we have many commands with subcommands:
git submodule, etc.
Piotr explained that the main point of his email was to have a single name, and although the name was not that important, he advocated for stage:
I’m new to git and a non-native English speaker. “Staging” seems most clear of all of the terms. You may find it differently, but please take into consideration that you are accustomed to it.Piotr Krukowiecki
Pete Harlan explained that the problem to him was that developers working with Git internals were biased towards the term “index”, while everyone else see absolutely no reason to use the low-level details:
Part of the issue could be that one intimately familiar with Git’s internals may find a process oriented interface irritating (“Why must it say ‘staging area’ when it’s just updating the index?”), while one unfamiliar with the internals has the opposite reaction (“Why must it make me use the internal name of the staging area?”).Pete Harlan
Pete even suggested a git command developed from scratch with an interface that hides all the nuts and bolts from the user.
Once again Drew Northup explored what the definitions of “cache” and “index” mean in English and compared them what git actually does internally, but I argued that what happens internally is irrelevant for the end user:
Branches and tags are “rthetorical” devices as well. But behind scenes they are just refs. Shall we disregard ‘branch’ and ‘tag’?
No. What Git does behind scenes is irrelevant to the user. What matters is what the device does, not how it is implemented; the implementation might change. “Stage” is the perfect word; both verb and a noun that express a temporary space where things are prepared for their final form.Felipe Contreras
Additionally Miles Bader argued that magit already uses the label “staging area”, and the shortcut to add changes there is “s”.
Jonathan Nieder pushed back on new terms because they were “established”, however I mentioned that the whole point of git 1.8.0 (which later became 2.0) was to rethink git from scratch, so why not rethink these terms? Junio argued that while rethinking is fine, consensus so far has not been achieved, and thus it could not be considered for 1.8.0.
Jeff King argued that as a native English speaker “staging area” makes perfect sense to him:
So the term “staging area” makes perfect sense to me; it is where we collect changes to make a commit. I am willing to accept that does not to others (native English speakers or no), and that we may need to come up with a better term. But I think just calling it “the stage” is even worse; it loses the concept that it is a place for collecting and organizing.Jeff King
Drew Northup argued that although the term “staging area” has value, it has limited use for somebody trying to learn how git works.
Phil Hord also agreed “staging area” makes perfect sense:
When we pack up our kayak club for a trip, we stage equipment we’re bringing. Eventually we make a decision about which equipment is going and which is staying. The decision is codified by the equipment we leave in the staging area versus the equipment we remove to local storage. Everyone seems to understand the term when we use it in this context.Phil Hord
Additionally Jeff King agreed that the internals were not relevant for the mental model of the end user:
But note that it is a mental model. The fact that it is implemented inside the index, along with the stat cache, doesn’t need to be relevant to the user. And the fact that the actual content is in the object store, with sha1-identifiers in the index, is not relevant either. At least I don’t think so, and I am usually of the opinion that we should expose the data structures to the user, so that their mental model can match what is actually happening. But in this case, I think they can still have a pretty useful but simpler mental model.Jeff King
There were other proposals, such as “the bucket”, or “precommit area”. Matthieu Moy said that as a non-native speaker anything “foo area” helps, not necessarily “staging area”, but Alexey Feldgendler disagreed, at least in Russian “staging area” is better.
Alexei Sholik argued that as a new git user, he thinks term “index” only confuses unprepared readers.
Jonathan Nieder decided to write a summary of the situation:
To summarize: everyone knows what the staging area is, no one seems to know what the index is, and the –cached options are confusing.Jonathan Nieder
When I tried to explore other proposals like “commit preparation area” I eventually arrived back to the conclusion that there’s no better alternative than “staging area”, Miles Bader agreed:
I don’t why so many people seem to be trying so hard to come with alternatives to “staged” and “staging area”, when the latter are actually quite good; so far all the suggestions have been much more awkward and less intuitive.Miles Bader
Jonathan Nieder agreed and proposed that we stop discussing, in order to start coding. Curiously enough Junio’s argument for not considering this for 1.8.0 is that there was no consensus, but consensus was reached only a couple of messages later.
However, nothing was coded.
It seems that you are trying to advocate “staging area” as some sort of official term. I think “it is like a staging area” is a good phrase to use when answering “what is the index?”, but I think repeating it million times without telling the casual readers what its official name is is counterproductive. Don’t do that. It will confuse these same people when they start reading manuals.Junio C Hamano
Scott disagreed with Junio. The term “staging area” is already quite popular, the only place where it’s not used is in the official documentation (i.e. man pages):
I’m not really trying to advocate it as much as using terminology that is already quite popular. It’s true that it’s not what is used in the man pages, but neither is ‘index’ used consistently – there is ‘cache’ too, in addition to ‘index’ having two meanings – packfile and cache. I’m open to making things clearer, but I just don’t think that changing the terminology to something more technical and vague would be overall less confusing to people.Scott Chacon
While Junio and Scott mostly discussed where the location of
git diff should be, it’s worth noting that merely because Scott disagreed, Junio told him that he should “know better”:
As you are supposed to be one of the top-level Git Teachers, I wish you knew better. Here is a free Git lesson.Junio C Hamano
Which Scott understandably found it condescending and unnecessary:
There is absolutely no reason to be this condescending.Scott Chacon
Since nothing materialized from previous discussions, I decided to write a serious proposal for 1.8.0 (which later became 2.0). The proposal was simple: avoid “index” and “cache” in favor of “stage”.
Philip Oakley stated that he didn’t like the current terms, Matthieu Moy agreed something needs to be done, Zbigniew Jędrzejewski-Szmek that it was a very good idea, Mark Lodato agreed with me, and Sebastien Douche that it was an extremely good idea:
+1000. An anecdote: many attendees said to me “I didn’t understand until you explained it that way”. Now I use always the term “stage” in my training (and banned the term index). Far better.Sebastien Douche
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. Just search on Google for “home staging” and you will get plenty of hits. This usage clearly originates from theater but can be found in other contexts as well.Mark Lodato
Yeah, I think that this is a very good idea. Having three different terms for this great but relatively obscure idea adds an unnecessary cognitive burden for newcomers to git. ‘stage’ is certainly the best of the three options.Zbigniew Jędrzejewski-Szmek
Junio decided to find another objection to the word “stage”: that it might not be directly translated:
I didn’t necessarily wanted to use “stage”, it is “sad” because a new word-hunt may be needed for a replacement to “index” (as “stage” may not be a good word for i18n audience), and then we would need to keep “index”, “stage” and that third word as interchangeable terms.Junio C Hamano
Ævar Arnfjörð Bjarmason–a very prominent developer–did not think that made sense at all:
I don’t think that line of reasoning makes sense at all. We shouldn’t be picking terms in the original English translation of Git that we think would be more amenable to translation.
We should be picking terms that make the most sense in English, and then translators will translate those into whatever makes the most sense in their language.Ævar Arnfjörð Bjarmason
This is of course a great point, and Junio simply had to agreed and said “OK“.
Since Junio explained what “index” means in Japanese, and did so in a way that only made sense internally, but not how end users actually use it, I decided to point that out:
That’s what git has, internally, but that’s not how high-level users interact with it.Felipe Contreras
Matthieu Moy agreed with me.
Thiago Farina argued that neither “cache” or “index” helped him understand what the actual concept was, but “precommit” did.
When Jonathan Nieder proposed some concrete changes Junio objected stating that the name shouldn’t be important:
I personally think it is a wrong way of thinking to focus too much on the “name”, though.Junio C Hamano
Names are important. Name it ‘jaberwocky’ and people would have a harder time trying to understand what you are talking about. Maybe just by hearing the name they would give up, thinking it’s too advanced, or too obscure, or what not.Felipe Contreras
Junio kept referring to the concept “that thing”, although not only is “jabberwocky” not very useful, but “index” is in fact worse than “jabberwocky” because it has an understood meaning that does not match how the user interacts with “that thing”. Moreover, at this point is had become extremely clear that everyone agrees that “staging area” is the term in English that most closely resembles what it would be used for, and translators have already explained why that term is fine.
Junio did not respond back.
Since nothing happened in 2011, and nothing happened in 2012, in 2013 I took it upon myself to actually write the patches to actually start moving to the term “staging area”. While doing so it occurred to me that the difference between
git apply could be determined with a separate option, so
--staged --work, and
--staged --no-work. Since
--work would be enabled by default,
git apply --index simply becomes
git apply --staged. Moreover, I realized the same could be done for
git reset, so the unintuitive differences between
--hard become much clearer.
Matthieu Moy thanked me for working on this, found interesting my addition of
git stage edit which is currently not possible to do with any git command or option, and agreed that
--hard are terrible.
Junio objected, stating:
IIRC, when this was discussed, many non-native speakers had trouble with the verb “to stage”, not just from i18n/l10n point of view.Junio C Hamano
I explained to Junio that was not the case. Ævar was the only non-native speaker that had a problem with the term “stage”, but not “staging area”, and in fact he had already translated “index” to “the commit area”, not that it really mattered because as Ævar argued: what should be picked is what makes the most sense in English, and how that is best translated is up to the translators. Even Junio eventually agreed.
Again, everyone has agreed that index needs to be renamed, and “staging area” is the best option.Felipe Contreras
I asked Junio if he could re-read the threads (I provided the links) so I did not have to list the opinion of every person who participated. Junio did not respond to me, so I started writing the list, but asked him once again if he was planing to do that himself so I did not have to waste my time. He did not reply to that either.
So I had to finish the list. Only one person–Drew Northup–did not see the point in changing the name (but did not find any problem with the proposed name either), the rest, nineteen people were in favor of changing things.
If that was not enough, more people joined on this round:
I realize Git is not a democracy, but if the vote of a humble user counts for anything, I agree that “index” is a terrible name.
I was very excited when Felipe first started this thread, since I thought Git might finally fix one of it’s biggest long-standing usability problems. Calling this thing the “index” is like calling an important variable “someValue.” While the name may be technically correct, it’s way too generic to be useful. A name like “staging area” may not capture the whole idea, but at least it provides a good clue about what it does and how you might use it.
If we change this, I’m pretty sure most of the Internet will rejoice. Only a few old-timers will be grumpy, but that’s just because they don’t like change in general. I have never met anybody (outside this thread) who thought the current name was a good idea.William Swanson
+1 for staging areaPing Yin
As yet another “just a user”, I’d like to add my enthusiastic support for “to stage” and “staging area”.Hilco Wijbenga
All three: William, Ping, and Hilco expressed that they were very excited when I started the thread, because of the possibility of finally fixing this long-standing usability problem.
Junio did not reply again.
That’s the point where I stopped trying, but the discussions continued for years:
Is “staging area” still considered as the correct term or has time proven that index is better?Lars Vogel
Why is “index” better? It is a confusing name, one that has many other unrelated meanings. In particular, many projects managed by git also have an index, but few have a staging area.David A. Wheeler
That’s an absurd argument. A database product that wants to be used in library systems are forbidden to have “index” because that may be confused with library index cards?Junio C Hamano
- Junio C Hamano: “staging area” is a near-sighted and narrow minded term
- Nanako Shiraishi: the name doesn’t matter
- Drew Northup: the name doesn’t matter
- Felipe Contreras: “staging area” is the correct description
- Scott Chacon: we should move from “index” to “staging area”
- Jay Soffian: staging area is better
- Pete Harlan: “staging area” is good for teaching
- Aghiles: “staging area” is good for teaching
- Piotr Krukowiecki: “staging area” makes sense
- Jonathan Nieder: “staging area” is better than “index”
- Jeff King: “staging area” makes perfect sense
- Miles Bader: “staging area” is good
- Phil Hord: “staging area” is better than index/cache
- Victor Engmark: maybe “git bucket”
- David (bouncingcats): maybe “precommit”
- Alexey Feldgendler: “staging area” translates better into Russian (than precommit)
- Alexei Sholik: “staging area” is better
- Zbigniew Jędrzejewski-Szmek: “staging area” is better
- Ævar Arnfjörð Bjarmason: In Icelandic “index/stage” is translated to “the commit area”
- Sebastien Douche: “stage” is better than “cache”/”index”
- Thiago Farina: “precommit” is better
- Mark Lodato: “staging” is the most appropriate
- Philip Oakley: “staging area” is OK
- Matthieu Moy: something needs to be done
- William Swanson: “index” is a terrible name
- Ping Yin: +1 for staging area
- Hilco Wijbenga: I enthusiastically support “staging area”
- Lars Vogel: “staging area” is better
- David A. Wheeler: “staging area” is less confusing
Even though I started to contribute again in 2019 and I managed to land 81 patches, Junio once again has decided to ignore all my patches.
git stage --add
git stage --remove
git stage --diff
git stage --edit
Additionally a description of the staging area is added to
git help stage. What is missing from the 2013 patches are all the
--stage options that are basically aliases to
--cached. It is mostly legwork but I will eventually add those too.
Even though the Git project is not a democracy, you can cast your vote on this poll: Should git officially use the term “staging area” instead of “the index”? But if you want this to be done there’s only one way: send an email to the Git mailing list and try to convince Junio C Hamano.