[1.8.0] use 'stage' term consistently

Proposal:

Avoid the terms 'cache' and 'index' in favor of 'stage'.

Advantages:

The term 'stage' is more intuitive for newcomers which are more familiar with English than with git, and it seems to be a straightforward mental notion for people from different mother tongues.

It is so intuitive that it is used already in a lot online documentation, and the people that do teach git professionally use this term.

Risks:

People might be accustomed to the current options, and might take some time to get used to the new term. Scripts might be relying on the current options.

There's also the possibility that a lot of people prefer the terms 'cache' and 'index', but from the countless discussions on this subject, that seems to be rather unlikely.

Migration plan:

Follow a typical obsolete/deprecate process; for a period of time warn that the options are obsolete and shouldn't be used, in case there's a lot of people against this, this period would allow for them to shout; then remove them.

Rationale:

First of all, this discussion _always_ keeps coming back, so its clear something needs to be done, and in the last big discussion the consensus was that 'stage' was the best option. In summary:

cache: a 'cache' is a place for easier access; a squirrel caches nuts so it doesn't have to go looking for them in the future when it might be much more difficult. Git porcelain is not using the staging area for easier future access; it's not a cache.

index: an 'index' is a guide of pointers to something else; a book index has a list of entries so the reader can locate information easily without having to go through the whole book. Git porcelain is not using the staging area to find out entries quicker; it's not an index.

stage: a 'stage' is a special area designated for convenience in order for some activity to take place; an orator would prepare a stage in order for her speak to be successful, otherwise many people might not be able to hear, or see her. Git porcelain is using the staging area precisly as a special area to be separated from the working directory for convenience.

The term 'stage' is a good noun itself, but also 'staging area', it has a good verb; 'to stage', and a nice past-participle; 'staged'.

From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May 
05, 2012 2:04 PM

I've never found any of the terms to be great (as per this discussion ;-).

The term that helped me most, heard on one of the git videos, was "it's like a manifest", alluding to a 'shipping manifest', which then leads to both the "staging area" and "index" terms. Though "index" is probably too technical for most folk.

The allusion to shipping a consignment or rail marshalling (classification) yards, and similar frieght flows, may be another way for _explaining_ the term chosen for the preparation, consolidation and aggregation of the next shipment (commit). Most other VCS systems hide this stage (sic), hence the difficulty in explaining this to the lay person.

Philip 

On Sat, May 5, 2012 at 6:52 PM, Philip Oakley <philipoakley@iee.org> wrote:

Perhaps, but these terms are not already used everywhere, unlike 'stage', and haven't been brought in past discussions. Personally the word 'manifest' says nothing to me (manifesto?), neither does consignment, or marshalling. As discussed before, we need a term that has a nice noun (stage), verb (to stage), and past-participle (staged). There have been a lot of suggestions, but nothing as good as 'stage', which is presumably the reason why it's so prevalent in online documentation.

Maybe you are quite familiar with ships :)

Cheers.

From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May
05, 2012 6:30 PM

Useful to know.. The fact that there is such a variety of terms, usually based on specialist transport, is an indication of our on-going difficulties - people just don't talk about this aspect of 'work'. Usually it (packaging) is 'someone else's problem' ;-) E.g. what's it called when the post office batches up mail in the 'sorting' office? - I don't know, nor usually care, except when I just post 60 letters to Hawaii - should I put a band around them to 'help' the post office ... In the git case, unusually for a VCS, we do our own grouping, but need a verb.

Aside: wikipedia notes that even UK and US English railways can't agree 
their term
(http://en.wikipedia.org/wiki/Marshalling_yards) on what to call the
'staging' process we are discussing

I looked up a translation (I hope I haven't mis-chosen):
    shipping manifest (n) (bill or inventory enclosed with a consignment)
    manifiesto de carga (nm)
so (to me) it does look like "index" is the best word for our *list* of what 
we have
prepared, and the stage of preparation of those items for our next commit 
(shipment to the repo).

It probably doesn't help that the concepts and the implementation aren't always in alignment (a generic DVCS problem). e.g. when we `add` a file, a copy goes straight into our objects store, but isn't actually 'in' the repo. So the discussion suffers from knowing too much.

Ooops, my note about my wording suggestions being used for *explanation* got lost in the trimming. I wasn't suggesting a change to the candidate terms.

UK - home of the railways, and the SS Great Britain, and the Titanic ... Philip

On 05/05/2012 03:04 PM, Felipe Contreras wrote:

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.

I think you missed the most relevant meaning-of/phrase-with this word in this context, the one that is really the reason why it is used in git:

"A staging area (or staging point) is a location where organisms, people, vehicles, equipment or material are assembled before use." [http://en.wikipedia.org/wiki/Staging_area]

- Zbyszek

On Sat, 5 May 2012, Felipe Contreras wrote:

[...]

Actually Git porcelain does use 'the index' as a cache (computing), i.e. as a place to store redundant information (stat data, sha-1 for trees with DIRC dircache extension) for faster access.

But is not all it does...
 

Nb. 'the index' started as dircache at the very begining, and this historical legacy shows through in a few places (including documentation and plumbing error messages).

Actually 'the index' is index in that sense; it stores _references_ from filename to file contents, using SHA-1 identifier of a file/tree contents in place of page number in the book index. The SHA-1 identifier of object which is stored in database of repository, not the index itself.

But it is not all it does...

True, 'the index' serves a staging area to build a commit, or to resolve a merge conflict.

But from above comments you can see that it is not all it does...

Anyway another issue to resolve is '--cached' and '--index' command line options, as described in gitcli(7) manpage:

  Many commands that can work on files in the working tree
  and/or in the index can take `--cached` and/or `--index`
  options.  Sometimes people incorrectly think that, because
  the index was originally called cache, these two are
  synonyms.  They are *not* -- these two options mean very
  different things.

   * The `--cached` option is used to ask a command that
     usually works on files in the working tree to *only* work
     with the index.  For example, `git grep`, when used
     without a commit to specify from which commit to look for
     strings in, usually works on files in the working tree,
     but with the `--cached` option, it looks for strings in
     the index.

   * The `--index` option is used to ask a command that
     usually works on files in the working tree to *also*
     affect the index.  For example, `git stash apply` usually
     merges changes recorded in a stash to the working tree,
     but with the `--index` option, it also merges changes to
     the index as well.

You can use '--staged' in place of '--cached', but what about '--index'? How do you replace it?

BTW. here is the list of porcelain commands that use those command line options:

  Command         --cached        --index
  ----------------------------------------
  git-apply           X               X
  git-diff            X
  git-grep            X
  git-ls-files        X
  git-rm              X
  git-stash^*                         X
  git-submodule^#     X

  Footnotes
  .........
  [*] "git stash pop" and "git stash apply" subcommands
  [#] "git submodule status" and "git submodule summary" subcommands

Jakub Narebski <jnareb@gmail.com> writes:

This is an implementation optimization, that is not supposed to be visible for the user. Commands refering to the "cache" are not about stat data cache (e.g. "git diff --cached" is really about the content, not the stat cache).

The implementation is done like this, but the user doesn't really care about this. For example, git-add(1) says "The index holds a snapshot of the content of the working tree", not "The index holds a set of references to sha1sums".

There's no need to expose these two implementation details in the terminology used in the interface. Indeed, I've often seen people from other VCS confused by Git's index just because of the terminology. Because we sometimes call it "cache", they think it is basically a stat-cache, and wonder why it is shown to the user. I've even seen Git users think that others VCS didn't have a stat-cache because they had read that the "cache" was a unique Git feature.

On Sun, May 6, 2012 at 12:39 PM, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

Exactly; that's an implementation detail that doesn't affect how the user actually interacts with the staging area.

On Sun, May 6, 2012, Felipe Contreras wrote:

Well, it does (or hopefully just did) affect the user: _if it fails_, in the form of empty diff on no changes because of stat-dirtyness or racy-git :-P

Just a few factoid corrections.

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

Yes. It has been pointed out number of times that "--cached" option is misnamed and deserves a better name, perhaps "--index-only", with the current name kept as a backward compatibility synonym.

Correct. It is the table-of-contents for whatever tree the next "write-tree" would write out. But it also was named "cache" originally because that it is not a huge loss if you lose it; you can repopulate it from the working tree. Over time, the operation you can do to the "index" became richer and finer grained, mostly thanks to "add -p" family of features, so it no longer is "not a big deal" to lose the distinction between what has and has not yet been added to the index (iow, "git reset" without any options), and the reason to consider it "cache" has diminished.

Contrary to the popular belief by outsiders, i.e. what you wrote at the end of the message I left below, the "stat cache" part was not the primary origin of the name "dircache".

On Sun, May 6, 2012 at 12:21 PM, Jakub Narebski <jnareb@gmail.com> wrote:

From past discussions it was suggested to use --staged-only for --cached, and --staged for --index in commands that need this distinction. Alternatively it could be --cached -> --staged, --index -> --stage-and-wd, or something like that.

Cheers.

Felipe Contreras <felipe.contreras@gmail.com> writes:

I completely agree that something needs to be done.

But there are at least two points that were raised during the previous discussions that need to be taken into account:

* Currenly, "index" and "staging area" are not exactly synonyms. When
  used with "git add" and "git commit" (without -a), the index is the
  staging area for the next commit. But when used by "git merge", the
  index is more a "merging area".

* There is currently a distinction in the meaning of --cached and
  --index. See the end of Documentation/gitcli.txt. I think it is good
  to have this distinction, but I agree that the wording of current
  option name is wrong (i.e. without having read gitcli.txt, I don't
  think anyone could have guessed this distinction). Perhaps something
  like --staged-only/--staged-too?

About the name, an alternative to "stage" was suggested earlier: "precommit". If we were to rewrite Git from scratch, I'd argue in favor of this one, which is really easy to understand, especially for non-native (you really need to know what a "commit" is to use Git, and then infering the meaning of precommit is easy). But we probably have already a too long history of changing the name, so introducing yet another one is perhaps counter-productive. I don't know.

On Sun, May 6, 2012 at 12:26 PM, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

And what is the difference? The result of the 'merging area' is still a commit.

I don't know, precommit is not an English word, and it was discussed before, but not many people vouched for it.

Plus, it's not already widely used in the interwebs documentation as staging area is.

Cheers.

On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras <felipe.contreras@gmail.com> wrote:

FWIW in the Icelandic translation I translated "index/stage" to the equivalent of "the commit area".

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

Care to explain why you did not use a translation of the verb/noun "stage"? I actually was having a hard time to come up with Japanese translation (not that I have plan to contribute to ja_JP.po), as the shipping/logistics term "to stage" does not cleanly translate to the language without unnecessary connotation that imply what is described is something the our "index" actually is _not_.

On Mon, May 7, 2012 at 7:52 PM, Junio C Hamano <gitster@pobox.com> wrote:

Because there's no equivalent of "stage" in Icelandic that would make sense as both a verb and a noun. There's a word that means "step" (as in a step on a ladder"), but it doesn't make much sense to say that you'd "step something".

I also think it makes more sense to pick a translation that associates the stage with commits. I.e. a commit is "færsla", the stage is "færslusvæðið".

I might still go for another one, but that's the one I like best so far.

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

Japanese stopped inventing their own words for imported concepts mid 20th century and mostly use English words phonetically transliterated these days. The word "index" is quite well understood: that which points at the information given a headword that refers to it, which is exactly what the "index" we have is. On the other hand, "to stage/staging area" is not as widely used outside the narrow shipping/logistics circles.

I actually was hoping that Japanese was a minority to have trouble with the word "stage" (and my not being a professional translator did not help the matter), and we could declare "it is stage from now on", update the documentation, rename the .git/index to .git/stage (not strictly needed, and I am not looking forward to it, as it would be a messy and pointless transition with backward compatibility headaches) and be done with it, if we wanted to.

But sadly it seems that it may not be the case, at least unless you are familiar with the shipping/logicstics lingo in English, if you are not native. 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.

Spliting the userbase by introducing a new form to an established terminology was bad enough, and making that three is worse.

On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:

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.

How translators work also depends largely on the language they're translating the terms into. In my experience there's three main modes of translation that people aim for:

 * Do we have a common word for it already? If so use, it, if not
   let's just use the English word. Japanese and German largely fall
   into this category.

 * Do we have a word for it at all or can we concoct one that makes
   sense? If so let's try to use it. Some languages like German are
   evidently struggling with the boundary between this and the first
   category.

 * What ideas are these terms trying to convey, and do we have an
   equivalent for those ideas in our language that we can use?
   Icelandic translations mostly aim for this.

So e.g. for Icelandic I'm not aiming to translate the shipping / military concept of "stage".

I'm looking at what it means in the workflow of git (a staging are for commits before they're born) and using a word you'd use in Icelandic if you were trying to talk about some staging/preparation area.

That I have to do this isn't a failure of the original English version, it's an inevitable emergence of different languages using different terms and patterns to express similar ideas.

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

OK.

On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:

That's what git has, *internally*, but that's not how high-level users interact with it. If 'git add file' was a true index from the point of view of the user; then the user would have some kind of identifier, like '1', or possibly and identifier of his own. Then the user could use this identifier, say; give me the file '1', and the operation would be much faster. But that's has *absolutely* nothing to do with how users see these operations. The user does not see an index at all. Maybe git has an index, but it could be replaced by something else, and the user would still see the same; it's an implementation detail; not something the user cares about.

This has been explained and discussed many times.

Cheers.

Felipe Contreras <felipe.contreras@gmail.com> writes:

I agree with that. Explaining users that the <whatever you call it> is the place where you stage content in preparation for the next commit is much more productive than explaining that it is an array of (name, sha1sum) pairs.

On Mon, May 7, 2012 at 1:52 PM, Junio C Hamano <gitster@pobox.com> 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. 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.

Hi Mark,

Mark Lodato wrote:

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

Jonathan Nieder wrote:

For the command-line interface:

Making the "git stage" command more prominent. Unfortunately it is currently a synonym for "git add", which makes "git rm" less discoverable and generally isn't very helpful. But if we discard that property, it could become a nice way to make some operations more discoverable:

	git stage --add <paths>; # stage an addition
	git stage --remove <paths>; # stage a removal
	git stage --edit <paths>; # edit the staged content
	git stage --apply <patch>; # stage the described change

These would be commands that modify the index without touching the worktree.

If anyone claims this is the command for manipulating "the stage", we can apologize for the confusing homonym and point them to a dictionary and images of raised platforms and staging areas and hopefully that will avoid any confusion. The command is named after the verb.

Finding a better mnemonic than "also update the current directory cache" and "trust the current directory cache" for operations like git apply --index and git grep --cached. Better concepts would be "search the content staged for the next commit" and "also update the staged content".

Maybe:

	git apply --index=(yes | no | only)
		# apply         	= apply --index=no
		# apply --index 	= apply --index=yes
		# apply --cached	= apply --index=only

	git grep --index; # (= git grep --cached)

I imagine others can come up with something better.

On Sat, May 19, 2012 at 8:32 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

If they are commands, why do they start with --?

'git stage add' 'git stage remove' 'git stage edit'

Would be more appropriate.

But I think revamping 'git stage' should be a separate task.

'index'? That goes contrary to this request; the term 'index' should be avoided in porcelain commands. s/index/stage/ and the proposal seems sensible, but I fail to see how --stage=no could be helpful, and --stage=yes should be the same as --stage, and then I wonder what would be the purpose of having --stage, and --stage=only, where we could have a --stage(d)-only for commands that need this distinction (not all of them). If in the future we want more --stage=foo options, then it might make sense, but I just don't see that ever happening.

I guess the next step would be to list all the commands that use --index, --staged, and --cached, and propose new options that would eventually help to remove --index and --cached (after some period of deprecation).

Cheers.

Felipe Contreras wrote:

They are commands because they are passed on the command line. I don't care strongly about the details --- I was giving an idea for people to pick up or not pick up.

[...]

[...]

It is 'index' because the command already has an option with that name, which makes this more discoverable and less confusing to existing users. You can like or not like that choice.

How do you negate the "also stage this change for the next commit" option passed earlier on the command line?

I also don't care about the details here and wish you had phrased your critique in terms of an alternate proposal instead of asking me to defend mine. The only part I actually care about is that a person should think carefully about individual changes, in isolation, that improve git and move towards a more pleasant and consistent interface.

I don't see any reason for a flag day.

Hope that helps, Jonathan

From: "Jonathan Nieder" <jrnieder@gmail.com>
Sent: Saturday, May 19, 2012 7:00 AM

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.

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.

I'd agree. The file is an index.

Philip

On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Agreed, that is an implementation detail anyway; the changes should be done with how the a typical user interacts with git, and a typical user doesn't need to know the index exists.

The git's staging area, of course. How is that not clear?

If the (new) user wants to know more about the staging area, she can read about it, just like she currently can. A 'man git staging-area' might actually help.

However, there's no 'man git index', or anything like that, so where do you suppose new users currently look for information when they wonder "what index"? And looking into the .git directory for an "index" file? Seriously? I doubt any new user would do that, I haven't even done so myself. The whole point of documentation is to be user *friendly*.

I find this paragraph completely unnecessary. This is useless distraction; the user wants to know about 'git add', she doesn't need to know about the index, and we should hide it from her.

Instead, the 'git add' documentation should point to the 'man git staging-area', and there, hidden somewhere is the implementation details; the index, and all the gory details.

Cheers.

Felipe Contreras wrote:

Ok. Have you seen the current git-add(1) manpage? Do you have patches that improve it to avoid such useless background information in a non-confusing way?

Jonathan

Jonathan Nieder <jrnieder@gmail.com> writes:

All true.

Comparing between the one before "Instead" and the above one, I would say it is.

I am hoping that we are not wasting people's time by the same experiment that already failed very early in Git's history to hide the "concept" of that which is used to shape the tree that would be recorded in the next commit that is different from either the current commit nor the contents in the working tree, and instead this round is about the name of that thing, which has been called "the index" and also colloquially known as "the staging area" in many third-party documents.

I personally think it is a wrong way of thinking to focus too much on the "name", though. The goal should be increased clarity and ease of learning. For example, the first sentence in your example reads equally well if it said "the content _prepared_ for the next commit" without losing clarity and tells the most important thing it must tell the user: that "add" is about updating "that thing" that is different from the working tree and the latest commit, even if "stage" (verb) does not translate well to other language.

About the "git stage --add/rm" commands in your follow-up message, I have mixed feelings. Once users get that making progress and growing history with Git is all about interacting with "that thing", writing out a new tree out of it and recording it in a new commit with appropriate parents, saying "stage" becomes redundant. You "add", "remove", "patch", etc. to affect that is recorded in "that thing" (e.g. you do not "add" to commit).

Another reason of my "mixed feelings" is that an interface organized around what is affected, instead of around what is achieved, may be counter-productive. "add" that adds the contents in the working tree (i.e. you already made the change you want yourself) to "that thing" makes sense from the work-flow point of view. It is how you edit, test or eyeball to convince yourself that you are happy with what is in your working tree, and then approach one step closer to your next commit.

An interface built around "that thing" may have a subcommand that adds contents to "that thing" regardless of what is in your working tree, but it is useful in only special occasions (e.g. in filter-branch script that does not want/need to use a temporary working tree). Such a functionality does have a place to live, namely at the plumbing level, but already is available as "update-index". But these commands that are organized around "what" they operate on are and should be of "specialized" kind, not "end user everyday activity" commands that are designed to give easier time to people in learning and using the system.

On Sun, May 20, 2012 at 11:11 PM, Junio C Hamano <gitster@pobox.com> wrote:

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.

There have been countless people that say "me too! when I realized it was X", which suggests the current name does not help.

And using a common/well understood name is a step in the right direction.

But also, once we accept that "that thing" is not an index, then it becomes much more easy to distinguish between the abstract concept, and the actual index, and then we can begin to remove the index from the high-level documentation and squash it to a corner where the user does not _have_ to go unless she really does want to know the implementation details.

Right now it's almost impossible to split the "index", and then index.

If the name is not important, why do you think people avoid the official name?

Indeed, but you are missing the important part; everything else in that sentence.

I will put my end-user hat and read while thinking aloud the current text:

"This command updates the index"

OK, you lost me there. I don't know what is that "index", do I need to learn what is that in order to understand the command? Maybe I shouldn't be reading this documentation at all.

But, OK, let's give it a try... Right, an index, well, an index of what to what? No idea. Maybe if I keep reading.

"using the current content found in the working tree, to prepare the content staged for the next commit.

OK, maybe I'm beginning to understand... But I'm still not sure if I should be touching this index thing, I don't understand what is being indexed.

While I would not like to touch the 'git stage' at this point--nor do I think it's needed--, I don't agree with what you said. In certain commands it might be redundant, but I specially disagree on these:

The 'add' command has a long tradition in SCM; it adds a file for content tracking--nothing more.

Using 'add' to *update* the staging area seems completely and totally counter-intuitive to me. Adding something means that something was not there; if it was there, you couldn't add it.

Of course, that's if you think about files, but it makes sense if you think about changes instead, but 'git add file' and 'git add file' do very different things conceptually depending on weather 'file' was tracked or not; one would "add a file" (to git), and the other would "add the changes of the file" (to the staging area). Splitting the command in two would make this difference in concepts clearer.

And then we have all sorts of confusion. --patch; I thought we were adding patches to the staging area, this is redundant, --selectively might make more sense. --update; I thought we were updating! --updated might make more sense. And what happens when you do 'git add --patch untracked-file' (or --update)? That's very strange.

If we have a 'stage' command things become much simpler:

git add untracked-file # maybe as the current 'git add --intent-to-add' git add tracked-file # no-op (error?) git add --patch file # doesn't make sense; option not present git add --update file # doesn't make sense; option not present

git stage untracked-file # add, and stage it, why not? git stage tracked-file git stage --hunks file git stage --updates file

At this point 'git add' would not be doing much, and might even go away, but I guess it's nice for people coming from other SCMs.

'rm' is similar, could be solved by 'unstage'.

Either way, I have proposed to use stage/unstage before I think, without much success, so I think the only realist option to move forward is to add --stage(d) and --stage-only.

Cheers.

Hi Felipe,

Felipe Contreras wrote:

You're probably onto something, but I'm missing the point in your message. Could you repeat, carefully explaining:

 - what change you would like to propose in git
 - whether it is backward compatible, and if it is not, what
   transition plan you propose
 - briefly, the rationale behind the change, in such a way as to
   convince skeptics like me that it is a good idea and to recruit
   us to help in your cause

? For that third part, a good example to take inspiration from is the project to improve Linux to function as a real-time operating system. Each change is so well justified _individually_ that someone not interested at all in that goal can still not help but agree with the changes!

Perhaps your message includes these elements already, but I found it hard to follow, hence this request.

Thanks, Jonathan

On Sun, May 6, 2012 at 7:26 AM, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

Thanks! That was the first that explained to me what cache, index, and stage was talking about. +1 from me (not that count much).

On Sat, May 5, 2012 at 3:04 PM, Felipe Contreras <felipe.contreras@gmail.com> wrote:

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