{"thread":{"id":"30433","subject":"[1.8.0] use 'stage' term consistently","startedAt":"2012-05-05T13:04:25Z","lastAt":"2012-05-21T01:32:34Z","messageCount":34,"participants":["Felipe Contreras","Philip Oakley","Zbigniew Jędrzejewski-Szmek","Jakub Narebski","Matthieu Moy","Ævar Arnfjörð Bjarmason","Junio C Hamano","Sebastien Douche","Thiago Farina","Mark Lodato","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"190839","messageId":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","threadId":"30433","inReplyTo":null,"subject":"[1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-05T13:04:25Z","receivedAt":"2012-05-05T13:04:25Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Proposal:\n\nAvoid the terms 'cache' and 'index' in favor of 'stage'.\n\nAdvantages:\n\nThe term 'stage' is more intuitive for newcomers which are more\nfamiliar with English than with git, and it seems to be a\nstraightforward mental notion for people from different mother\ntongues.\n\nIt is so intuitive that it is used already in a lot online\ndocumentation, and the people that do teach git professionally use\nthis term.\n\nRisks:\n\nPeople might be accustomed to the current options, and might take some\ntime to get used to the new term. Scripts might be relying on the\ncurrent options.\n\nThere's also the possibility that a lot of people prefer the terms\n'cache' and 'index', but from the countless discussions on this\nsubject, that seems to be rather unlikely.\n\nMigration plan:\n\nFollow a typical obsolete/deprecate process; for a period of time warn\nthat the options are obsolete and shouldn't be used, in case there's a\nlot of people against this, this period would allow for them to shout;\nthen remove them.\n\nRationale:\n\nFirst of all, this discussion _always_ keeps coming back, so its clear\nsomething needs to be done, and in the last big discussion the\nconsensus was that 'stage' was the best option. In summary:\n\ncache: a 'cache' is a place for easier access; a squirrel caches nuts\nso it doesn't have to go looking for them in the future when it might\nbe much more difficult. Git porcelain is not using the staging area\nfor easier future access; it's not a cache.\n\nindex: an 'index' is a guide of pointers to something else; a book\nindex has a list of entries so the reader can locate information\neasily without having to go through the whole book. Git porcelain is\nnot using the staging area to find out entries quicker; it's not an\nindex.\n\nstage: a 'stage' is a special area designated for convenience in order\nfor some activity to take place; an orator would prepare a stage in\norder for her speak to be successful, otherwise many people might not\nbe able to hear, or see her. Git porcelain is using the staging area\nprecisly as a special area to be separated from the working directory\nfor convenience.\n\nThe term 'stage' is a good noun itself, but also 'staging area', it\nhas a good verb; 'to stage', and a nice past-participle; 'staged'.\n\n-- \nFelipe Contreras\n"},{"id":"190853","messageId":"703DFCB358F74F9D87F12C22B782EA61@PhilipOakley","threadId":"30433","inReplyTo":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-05-05T16:52:16Z","receivedAt":"2012-05-05T16:52:16Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Felipe Contreras\" Sent: Saturday, May \n05, 2012 2:04 PM\n> Proposal:\n>\n> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n>\n> Advantages:\n>\n> The term 'stage' is more intuitive for newcomers which are more\n> familiar with English than with git, and it seems to be a\n> straightforward mental notion for people from different mother\n> tongues.\n>\n> It is so intuitive that it is used already in a lot online\n> documentation, and the people that do teach git professionally use\n> this term.\n\nI've never found any of the terms to be great (as per this discussion ;-).\n\nThe term that helped me most, heard on one of the git videos, was \"it's like \na manifest\", alluding to a 'shipping manifest', which then leads to both the \n\"staging area\" and \"index\" terms. Though \"index\" is probably too technical \nfor most folk.\n\nThe allusion to shipping a consignment or rail marshalling (classification) \nyards, and similar frieght flows, may be another way for _explaining_ the \nterm chosen for the preparation, consolidation and aggregation of the next \nshipment (commit). Most other VCS systems hide this stage (sic), hence the \ndifficulty in explaining this to the lay person.\n\n> Risks:\n>\n> People might be accustomed to the current options, and might take some\n> time to get used to the new term. Scripts might be relying on the\n> current options.\n>\n> There's also the possibility that a lot of people prefer the terms\n> 'cache' and 'index', but from the countless discussions on this\n> subject, that seems to be rather unlikely.\n>\n> Migration plan:\n>\n> Follow a typical obsolete/deprecate process; for a period of time warn\n> that the options are obsolete and shouldn't be used, in case there's a\n> lot of people against this, this period would allow for them to shout;\n> then remove them.\n>\n> Rationale:\n>\n> First of all, this discussion _always_ keeps coming back, so its clear\n> something needs to be done, and in the last big discussion the\n> consensus was that 'stage' was the best option. In summary:\n>\n> cache: a 'cache' is a place for easier access; a squirrel caches nuts\n> so it doesn't have to go looking for them in the future when it might\n> be much more difficult. Git porcelain is not using the staging area\n> for easier future access; it's not a cache.\n>\n> index: an 'index' is a guide of pointers to something else; a book\n> index has a list of entries so the reader can locate information\n> easily without having to go through the whole book. Git porcelain is\n> not using the staging area to find out entries quicker; it's not an\n> index.\n>\n> stage: a 'stage' is a special area designated for convenience in order\n> for some activity to take place; an orator would prepare a stage in\n> order for her speak to be successful, otherwise many people might not\n> be able to hear, or see her. Git porcelain is using the staging area\n> precisly as a special area to be separated from the working directory\n> for convenience.\n>\n> The term 'stage' is a good noun itself, but also 'staging area', it\n> has a good verb; 'to stage', and a nice past-participle; 'staged'.\n>\n> -- \n> Felipe Contreras\n\nPhilip \n"},{"id":"190856","messageId":"CAMP44s1isa2a=a-QLGaE9ThW1iUBj0je2NUi8FVxqA=OELLmyA@mail.gmail.com","threadId":"30433","inReplyTo":"703DFCB358F74F9D87F12C22B782EA61@PhilipOakley","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-05T17:30:41Z","receivedAt":"2012-05-05T17:30:41Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sat, May 5, 2012 at 6:52 PM, Philip Oakley wrote:\n> From: \"Felipe Contreras\" Sent: Saturday, May\n> 05, 2012 2:04 PM\n>\n>> Proposal:\n>>\n>> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n>>\n>> Advantages:\n>>\n>> The term 'stage' is more intuitive for newcomers which are more\n>> familiar with English than with git, and it seems to be a\n>> straightforward mental notion for people from different mother\n>> tongues.\n>>\n>> It is so intuitive that it is used already in a lot online\n>> documentation, and the people that do teach git professionally use\n>> this term.\n>\n>\n> I've never found any of the terms to be great (as per this discussion ;-).\n>\n> The term that helped me most, heard on one of the git videos, was \"it's like\n> a manifest\", alluding to a 'shipping manifest', which then leads to both the\n> \"staging area\" and \"index\" terms. Though \"index\" is probably too technical\n> for most folk.\n>\n> The allusion to shipping a consignment or rail marshalling (classification)\n> yards, and similar frieght flows\n\nPerhaps, but these terms are not already used everywhere, unlike\n'stage', and haven't been brought in past discussions. Personally the\nword 'manifest' says nothing to me (manifesto?), neither does\nconsignment, or marshalling. As discussed before, we need a term that\nhas a nice noun (stage), verb (to stage), and past-participle\n(staged). There have been a lot of suggestions, but nothing as good as\n'stage', which is presumably the reason why it's so prevalent in\nonline documentation.\n\nMaybe you are quite familiar with ships :)\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"190863","messageId":"38B7BCC61E844EAD97CC18D5D7299DD5@PhilipOakley","threadId":"30433","inReplyTo":"CAMP44s1isa2a=a-QLGaE9ThW1iUBj0je2NUi8FVxqA=OELLmyA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-05-05T19:53:36Z","receivedAt":"2012-05-05T19:53:36Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Felipe Contreras\" Sent: Saturday, May\n05, 2012 6:30 PM\n> On Sat, May 5, 2012 at 6:52 PM, Philip Oakley \n> wrote:\n>> From: \"Felipe Contreras\" Sent: Saturday, May\n>> 05, 2012 2:04 PM\n>>\n>>> Proposal:\n>>>\n>>> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n>>>\n>>> Advantages:\n>>>\n>>> The term 'stage' is more intuitive for newcomers which are more\n>>> familiar with English than with git, and it seems to be a\n>>> straightforward mental notion for people from different mother\n>>> tongues.\n>>>\n>>> It is so intuitive that it is used already in a lot online\n>>> documentation, and the people that do teach git professionally use\n>>> this term.\n>>\n>>\n>> I've never found any of the terms to be great (as per this discussion\n>> ;-).\n>>\n>> The term that helped me most, heard on one of the git videos, was \"it's\n>> like\n>> a manifest\", alluding to a 'shipping manifest', which then leads to both\n>> the\n>> \"staging area\" and \"index\" terms. Though \"index\" is probably too\n>> technical\n>> for most folk.\n>>\n>> The allusion to shipping a consignment or rail marshalling\n>> (classification)\n>> yards, and similar freight flows\n>\n> Perhaps, but these terms are not already used everywhere, unlike\n> 'stage', and haven't been brought in past discussions. Personally the\n> word 'manifest' says nothing to me (manifesto?), neither does\n> consignment, or marshalling.\n\nUseful to know.. The fact that there is such a variety of terms, usually\nbased on specialist transport, is an indication of our on-going\ndifficulties - people just don't talk about this aspect of 'work'. Usually\nit (packaging) is 'someone else's problem' ;-) E.g. what's it called when\nthe post office batches up mail in the 'sorting' office? - I don't know, nor \nusually care, except when I just post 60 letters to Hawaii - should I put a \nband around them to 'help' the post office ... In the git case, unusually \nfor a VCS, we do our own grouping, but need a verb.\n\nAside: wikipedia notes that even UK and US English railways can't agree \ntheir term\n(http://en.wikipedia.org/wiki/Marshalling_yards) on what to call the\n'staging' process we are discussing\n\nI looked up a translation (I hope I haven't mis-chosen):\n shipping manifest (n) (bill or inventory enclosed with a consignment)\n manifiesto de carga (nm)\nso (to me) it does look like \"index\" is the best word for our *list* of what \nwe have\nprepared, and the stage of preparation of those items for our next commit \n(shipment to the repo).\n\nIt probably doesn't help that the concepts and the implementation aren't \nalways in alignment (a generic DVCS problem). e.g. when we `add` a file, a \ncopy goes straight into our objects store, but isn't actually 'in' the repo. \nSo the discussion suffers from knowing too much.\n\n> As discussed before, we need a term that\n> has a nice noun (stage), verb (to stage), and past-participle\n> (staged). There have been a lot of suggestions, but nothing as good as\n> 'stage', which is presumably the reason why it's so prevalent in\n> online documentation.\n\nOoops, my note about my wording suggestions being used for *explanation* got \nlost in\nthe trimming. I wasn't suggesting a change to the candidate terms.\n\n>\n> Maybe you are quite familiar with ships :)\n>\nUK - home of the railways, and the SS Great Britain, and the Titanic ...\nPhilip \n"},{"id":"190886","messageId":"4FA64A26.1020406@in.waw.pl","threadId":"30433","inReplyTo":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Zbigniew Jędrzejewski-Szmek","fromEmail":"zbyszek@in.waw.pl","sentAt":"2012-05-06T09:53:42Z","receivedAt":"2012-05-06T09:53:42Z","isPatch":false,"sender":{"key":"zbyszek@in.waw.pl","avatar":"https://avatars.githubusercontent.com/u/349618?v=4"},"body":"On 05/05/2012 03:04 PM, Felipe Contreras wrote:\n> Proposal:\n> \n> Avoid the terms 'cache' and 'index' in favor of 'stage'.\nYeah, I think that this is a very good idea. Having three different\nterms for this great but relatively obscure idea adds an unnecessary\ncognitive burden for newcomers to git. 'stage' is certainly the best of\nthe three options.\n\n> stage: a 'stage' is a special area designated for convenience in order\n> for some activity to take place; an orator would prepare a stage in\n> order for her speak to be successful, otherwise many people might not\n> be able to hear, or see her. Git porcelain is using the staging area\n> precisly as a special area to be separated from the working directory\n> for convenience.\nI think you missed the most relevant meaning-of/phrase-with this word in\nthis context, the one that is really the reason why it is used in git:\n\n\"A staging area (or staging point) is a location where organisms,\npeople, vehicles, equipment or material are assembled before use.\"\n[http://en.wikipedia.org/wiki/Staging_area]\n\n> The term 'stage' is a good noun itself, but also 'staging area', it\n> has a good verb; 'to stage', and a nice past-participle; 'staged'.\n\n-\nZbyszek\n"},{"id":"190888","messageId":"201205061221.29592.jnareb@gmail.com","threadId":"30433","inReplyTo":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2012-05-06T10:21:28Z","receivedAt":"2012-05-06T10:21:28Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Sat, 5 May 2012, Felipe Contreras wrote:\n\n> Proposal:\n> \n> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n[...]\n> Rationale:\n> \n> First of all, this discussion _always_ keeps coming back, so its clear\n> something needs to be done, and in the last big discussion the\n> consensus was that 'stage' was the best option. In summary:\n> \n> cache: a 'cache' is a place for easier access; a squirrel caches nuts\n> so it doesn't have to go looking for them in the future when it might\n> be much more difficult. Git porcelain is not using the staging area\n> for easier future access; it's not a cache.\n\nActually Git porcelain does use 'the index' as a cache (computing),\ni.e. as a place to store redundant information (stat data, sha-1\nfor trees with DIRC dircache extension) for faster access.\n\nBut is not all it does...\n \n\nNb. 'the index' started as dircache at the very begining, and this \nhistorical legacy shows through in a few places (including \ndocumentation and plumbing error messages).\n\n> index: an 'index' is a guide of pointers to something else; a book\n> index has a list of entries so the reader can locate information\n> easily without having to go through the whole book. Git porcelain is\n> not using the staging area to find out entries quicker; it's not an\n> index.\n\nActually 'the index' is index in that sense; it stores _references_\nfrom filename to file contents, using SHA-1 identifier of a file/tree \ncontents in place of page number in the book index. The SHA-1 \nidentifier of object which is stored in database of repository, not the \nindex itself.\n\nBut it is not all it does...\n\n> stage: a 'stage' is a special area designated for convenience in order\n> for some activity to take place; an orator would prepare a stage in\n> order for her speak to be successful, otherwise many people might not\n> be able to hear, or see her. Git porcelain is using the staging area\n> precisly as a special area to be separated from the working directory\n> for convenience.\n\nTrue, 'the index' serves a staging area to build a commit, or to resolve \na merge conflict.\n\nBut from above comments you can see that it is not all it does...\n\n> The term 'stage' is a good noun itself, but also 'staging area', it\n> has a good verb; 'to stage', and a nice past-participle; 'staged'.\n\nAnyway another issue to resolve is '--cached' and '--index' command line \noptions, as described in gitcli(7) manpage:\n\n Many commands that can work on files in the working tree\n and/or in the index can take `--cached` and/or `--index`\n options. Sometimes people incorrectly think that, because\n the index was originally called cache, these two are\n synonyms. They are *not* -- these two options mean very\n different things.\n\n * The `--cached` option is used to ask a command that\n usually works on files in the working tree to *only* work\n with the index. For example, `git grep`, when used\n without a commit to specify from which commit to look for\n strings in, usually works on files in the working tree,\n but with the `--cached` option, it looks for strings in\n the index.\n\n * The `--index` option is used to ask a command that\n usually works on files in the working tree to *also*\n affect the index. For example, `git stash apply` usually\n merges changes recorded in a stash to the working tree,\n but with the `--index` option, it also merges changes to\n the index as well.\n\nYou can use '--staged' in place of '--cached', but what about '--index'?\nHow do you replace it?\n\n\nBTW. here is the list of porcelain commands that use those command\nline options:\n\n Command --cached --index\n ----------------------------------------\n git-apply X X\n git-diff X\n git-grep X\n git-ls-files X\n git-rm X\n git-stash^* X\n git-submodule^# X\n\n\n Footnotes\n .........\n [*] \"git stash pop\" and \"git stash apply\" subcommands\n [#] \"git submodule status\" and \"git submodule summary\" subcommands\n\n-- \nJakub Narebski\nPoland\n"},{"id":"190890","messageId":"vpqehqxmwpj.fsf@bauges.imag.fr","threadId":"30433","inReplyTo":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-05-06T10:26:48Z","receivedAt":"2012-05-06T10:26:48Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Felipe Contreras writes:\n\n> Proposal:\n>\n> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n\nI completely agree that something needs to be done.\n\nBut there are at least two points that were raised during the previous\ndiscussions that need to be taken into account:\n\n* Currenly, \"index\" and \"staging area\" are not exactly synonyms. When\n used with \"git add\" and \"git commit\" (without -a), the index is the\n staging area for the next commit. But when used by \"git merge\", the\n index is more a \"merging area\".\n\n* There is currently a distinction in the meaning of --cached and\n --index. See the end of Documentation/gitcli.txt. I think it is good\n to have this distinction, but I agree that the wording of current\n option name is wrong (i.e. without having read gitcli.txt, I don't\n think anyone could have guessed this distinction). Perhaps something\n like --staged-only/--staged-too?\n\nAbout the name, an alternative to \"stage\" was suggested earlier:\n\"precommit\". If we were to rewrite Git from scratch, I'd argue in favor\nof this one, which is really easy to understand, especially for\nnon-native (you really need to know what a \"commit\" is to use Git, and\nthen infering the meaning of precommit is easy). But we probably have\nalready a too long history of changing the name, so introducing yet\nanother one is perhaps counter-productive. I don't know.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"190892","messageId":"vpqtxztlhjd.fsf@bauges.imag.fr","threadId":"30433","inReplyTo":"201205061221.29592.jnareb@gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-05-06T10:39:50Z","receivedAt":"2012-05-06T10:39:50Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jakub Narebski writes:\n\n> Actually Git porcelain does use 'the index' as a cache (computing),\n> i.e. as a place to store redundant information (stat data, sha-1\n> for trees with DIRC dircache extension) for faster access.\n\nThis is an implementation optimization, that is not supposed to be\nvisible for the user. Commands refering to the \"cache\" are not about\nstat data cache (e.g. \"git diff --cached\" is really about the content,\nnot the stat cache).\n\n>> index: an 'index' is a guide of pointers to something else; a book\n>> index has a list of entries so the reader can locate information\n>> easily without having to go through the whole book. Git porcelain is\n>> not using the staging area to find out entries quicker; it's not an\n>> index.\n>\n> Actually 'the index' is index in that sense; it stores _references_\n> from filename to file contents, using SHA-1 identifier of a file/tree \n> contents in place of page number in the book index. The SHA-1 \n> identifier of object which is stored in database of repository, not the \n> index itself.\n\nThe implementation is done like this, but the user doesn't really care\nabout this. For example, git-add(1) says \"The index holds a snapshot\nof the content of the working tree\", not \"The index holds a set of\nreferences to sha1sums\".\n\nThere's no need to expose these two implementation details in the\nterminology used in the interface. Indeed, I've often seen people from\nother VCS confused by Git's index just because of the terminology.\nBecause we sometimes call it \"cache\", they think it is basically a\nstat-cache, and wonder why it is shown to the user. I've even seen\nGit users think that others VCS didn't have a stat-cache because they\nhad read that the \"cache\" was a unique Git feature.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"190935","messageId":"CAMP44s3kkEn+_fhdrXyT9znNDE_u39pv1cFvZ+kLFyzOVpsjHg@mail.gmail.com","threadId":"30433","inReplyTo":"vpqtxztlhjd.fsf@bauges.imag.fr","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-06T20:15:34Z","receivedAt":"2012-05-06T20:15:34Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, May 6, 2012 at 12:39 PM, Matthieu Moy\n wrote:\n> Jakub Narebski writes:\n>\n>> Actually Git porcelain does use 'the index' as a cache (computing),\n>> i.e. as a place to store redundant information (stat data, sha-1\n>> for trees with DIRC dircache extension) for faster access.\n>\n> This is an implementation optimization, that is not supposed to be\n> visible for the user. Commands refering to the \"cache\" are not about\n> stat data cache (e.g. \"git diff --cached\" is really about the content,\n> not the stat cache).\n\nExactly; that's an implementation detail that doesn't affect how the\nuser actually interacts with the staging area.\n\n-- \nFelipe Contreras\n"},{"id":"190940","messageId":"CAMP44s2ubKqDeYz9r+FM+bn88uZBpNtyU94_79q0af9MZeuG9A@mail.gmail.com","threadId":"30433","inReplyTo":"201205061221.29592.jnareb@gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-06T21:09:49Z","receivedAt":"2012-05-06T21:09:49Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, May 6, 2012 at 12:21 PM, Jakub Narebski wrote:\n\n> Anyway another issue to resolve is '--cached' and '--index' command line\n> options, as described in gitcli(7) manpage:\n>\n>  Many commands that can work on files in the working tree\n>  and/or in the index can take `--cached` and/or `--index`\n>  options.  Sometimes people incorrectly think that, because\n>  the index was originally called cache, these two are\n>  synonyms.  They are *not* -- these two options mean very\n>  different things.\n>\n>   * The `--cached` option is used to ask a command that\n>     usually works on files in the working tree to *only* work\n>     with the index.  For example, `git grep`, when used\n>     without a commit to specify from which commit to look for\n>     strings in, usually works on files in the working tree,\n>     but with the `--cached` option, it looks for strings in\n>     the index.\n>\n>   * The `--index` option is used to ask a command that\n>     usually works on files in the working tree to *also*\n>     affect the index.  For example, `git stash apply` usually\n>     merges changes recorded in a stash to the working tree,\n>     but with the `--index` option, it also merges changes to\n>     the index as well.\n>\n> You can use '--staged' in place of '--cached', but what about '--index'?\n> How do you replace it?\n\nFrom past discussions it was suggested to use --staged-only for\n--cached, and --staged for --index in commands that need this\ndistinction. Alternatively it could be --cached -> --staged, --index\n-> --stage-and-wd, or something like that.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"190942","messageId":"CAMP44s2DU_3UnHxhgwsTVT59KjLi0+=iW7utuofEyis+_06jGA@mail.gmail.com","threadId":"30433","inReplyTo":"vpqehqxmwpj.fsf@bauges.imag.fr","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-06T21:16:37Z","receivedAt":"2012-05-06T21:16:37Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, May 6, 2012 at 12:26 PM, Matthieu Moy\n wrote:\n> Felipe Contreras writes:\n\n> * Currenly, \"index\" and \"staging area\" are not exactly synonyms. When\n>  used with \"git add\" and \"git commit\" (without -a), the index is the\n>  staging area for the next commit. But when used by \"git merge\", the\n>  index is more a \"merging area\".\n\nAnd what is the difference? The result of the 'merging area' is still a commit.\n\n> About the name, an alternative to \"stage\" was suggested earlier:\n> \"precommit\". If we were to rewrite Git from scratch, I'd argue in favor\n> of this one, which is really easy to understand, especially for\n> non-native (you really need to know what a \"commit\" is to use Git, and\n> then infering the meaning of precommit is easy). But we probably have\n> already a too long history of changing the name, so introducing yet\n> another one is perhaps counter-productive. I don't know.\n\nI don't know, precommit is not an English word, and it was discussed\nbefore, but not many people vouched for it.\n\nPlus, it's not already widely used in the interwebs documentation as\nstaging area is.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"190943","messageId":"201205062321.52148.jnareb@gmail.com","threadId":"30433","inReplyTo":"CAMP44s3kkEn+_fhdrXyT9znNDE_u39pv1cFvZ+kLFyzOVpsjHg@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2012-05-06T21:21:49Z","receivedAt":"2012-05-06T21:21:49Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Sun, May 6, 2012, Felipe Contreras wrote:\n> On Sun, May 6, 2012 at 12:39 PM, Matthieu Moy\n> wrote:\n> > Jakub Narebski writes:\n> >\n> > > Actually Git porcelain does use 'the index' as a cache (computing),\n> > > i.e. as a place to store redundant information (stat data, sha-1\n> > > for trees with DIRC dircache extension) for faster access.\n> >\n> > This is an implementation optimization, that is not supposed to be\n> > visible for the user. Commands refering to the \"cache\" are not about\n> > stat data cache (e.g. \"git diff --cached\" is really about the content,\n> > not the stat cache).\n> \n> Exactly; that's an implementation detail that doesn't affect how the\n> user actually interacts with the staging area.\n\nWell, it does (or hopefully just did) affect the user: _if it fails_,\nin the form of empty diff on no changes because of stat-dirtyness\nor racy-git :-P\n\n-- \nJakub Narebski\nPoland\n"},{"id":"190944","messageId":"CACBZZX4_wjFG4D4_2w8UcvbRwBmJ583QpoP_n-tq+dNds3Bi7Q@mail.gmail.com","threadId":"30433","inReplyTo":"CAMP44s2DU_3UnHxhgwsTVT59KjLi0+=iW7utuofEyis+_06jGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-06T21:30:13Z","receivedAt":"2012-05-06T21:30:13Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras\n wrote:\n> I don't know, precommit is not an English word, and it was discussed\n> before, but not many people vouched for it.\n\nFWIW in the Icelandic translation I translated \"index/stage\" to the\nequivalent of \"the commit area\".\n"},{"id":"191014","messageId":"7v1umv7ub0.fsf@alter.siamese.dyndns.org","threadId":"30433","inReplyTo":"CACBZZX4_wjFG4D4_2w8UcvbRwBmJ583QpoP_n-tq+dNds3Bi7Q@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-07T17:52:19Z","receivedAt":"2012-05-07T17:52:19Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras\n> wrote:\n>> I don't know, precommit is not an English word, and it was discussed\n>> before, but not many people vouched for it.\n>\n> FWIW in the Icelandic translation I translated \"index/stage\" to the\n> equivalent of \"the commit area\".\n\nCare to explain why you did not use a translation of the verb/noun\n\"stage\"? I actually was having a hard time to come up with Japanese\ntranslation (not that I have plan to contribute to ja_JP.po), as the\nshipping/logistics term \"to stage\" does not cleanly translate to the\nlanguage without unnecessary connotation that imply what is described is\nsomething the our \"index\" actually is _not_.\n"},{"id":"191030","messageId":"CACBZZX6u7rJer+tSqPddKdAF=bd216pZH5qUQNcrdr4nCmT46Q@mail.gmail.com","threadId":"30433","inReplyTo":"7v1umv7ub0.fsf@alter.siamese.dyndns.org","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-07T20:05:27Z","receivedAt":"2012-05-07T20:05:27Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, May 7, 2012 at 7:52 PM, Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras\n>> wrote:\n>>> I don't know, precommit is not an English word, and it was discussed\n>>> before, but not many people vouched for it.\n>>\n>> FWIW in the Icelandic translation I translated \"index/stage\" to the\n>> equivalent of \"the commit area\".\n>\n> Care to explain why you did not use a translation of the verb/noun\n> \"stage\"?  I actually was having a hard time to come up with Japanese\n> translation (not that I have plan to contribute to ja_JP.po), as the\n> shipping/logistics term \"to stage\" does not cleanly translate to the\n> language without unnecessary connotation that imply what is described is\n> something the our \"index\" actually is _not_.\n\nBecause there's no equivalent of \"stage\" in Icelandic that would make\nsense as both a verb and a noun. There's a word that means \"step\" (as\nin a step on a ladder\"), but it doesn't make much sense to say that\nyou'd \"step something\".\n\nI also think it makes more sense to pick a translation that associates\nthe stage with commits. I.e. a commit is \"færsla\", the stage is\n\"færslusvæðið\".\n\nI might still go for another one, but that's the one I like best so\nfar.\n"},{"id":"191063","messageId":"7vbolz1gay.fsf@alter.siamese.dyndns.org","threadId":"30433","inReplyTo":"vpqtxztlhjd.fsf@bauges.imag.fr","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-08T03:51:17Z","receivedAt":"2012-05-08T03:51:17Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Just a few factoid corrections.\n\nMatthieu Moy writes:\n\n>> Actually Git porcelain does use 'the index' as a cache (computing),\n>> i.e. as a place to store redundant information (stat data, sha-1\n>> for trees with DIRC dircache extension) for faster access.\n>\n> This is an implementation optimization, that is not supposed to be\n> visible for the user. Commands refering to the \"cache\" are not about\n> stat data cache (e.g. \"git diff --cached\" is really about the content,\n> not the stat cache).\n\nYes. It has been pointed out number of times that \"--cached\" option is\nmisnamed and deserves a better name, perhaps \"--index-only\", with the\ncurrent name kept as a backward compatibility synonym.\n\n>> Actually 'the index' is index in that sense; it stores _references_\n>> from filename to file contents,...\n\nCorrect. It is the table-of-contents for whatever tree the next\n\"write-tree\" would write out. But it also was named \"cache\" originally\nbecause that it is not a huge loss if you lose it; you can repopulate it\nfrom the working tree. Over time, the operation you can do to the \"index\"\nbecame richer and finer grained, mostly thanks to \"add -p\" family of\nfeatures, so it no longer is \"not a big deal\" to lose the distinction\nbetween what has and has not yet been added to the index (iow, \"git reset\"\nwithout any options), and the reason to consider it \"cache\" has diminished.\n\nContrary to the popular belief by outsiders, i.e. what you wrote at the\nend of the message I left below, the \"stat cache\" part was not the primary\norigin of the name \"dircache\".\n\n> ...\n> Because we sometimes call it \"cache\", they think it is basically a\n> stat-cache, and wonder why it is shown to the user. I've even seen\n> Git users think that others VCS didn't have a stat-cache because they\n> had read that the \"cache\" was a unique Git feature.\n"},{"id":"191064","messageId":"7v62c71fl7.fsf@alter.siamese.dyndns.org","threadId":"30433","inReplyTo":"CACBZZX6u7rJer+tSqPddKdAF=bd216pZH5qUQNcrdr4nCmT46Q@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-08T04:06:44Z","receivedAt":"2012-05-08T04:06:44Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> On Mon, May 7, 2012 at 7:52 PM, Junio C Hamano wrote:\n>\n>> ... I actually was having a hard time to come up with Japanese\n>> translation (not that I have plan to contribute to ja_JP.po), as the\n>> shipping/logistics term \"to stage\" does not cleanly translate to the\n>> language without unnecessary connotation that imply what is described is\n>> something the our \"index\" actually is _not_.\n>\n> Because there's no equivalent of \"stage\" in Icelandic that would make\n> sense as both a verb and a noun. There's a word that means \"step\" (as\n> in a step on a ladder\"), but it doesn't make much sense to say that\n> you'd \"step something\".\n\nJapanese stopped inventing their own words for imported concepts mid 20th\ncentury and mostly use English words phonetically transliterated these\ndays. The word \"index\" is quite well understood: that which points at the\ninformation given a headword that refers to it, which is exactly what the\n\"index\" we have is. On the other hand, \"to stage/staging area\" is not as\nwidely used outside the narrow shipping/logistics circles.\n\nI actually was hoping that Japanese was a minority to have trouble with\nthe word \"stage\" (and my not being a professional translator did not help\nthe matter), and we could declare \"it is stage from now on\", update the\ndocumentation, rename the .git/index to .git/stage (not strictly needed,\nand I am not looking forward to it, as it would be a messy and pointless\ntransition with backward compatibility headaches) and be done with it, if\nwe wanted to.\n\nBut sadly it seems that it may not be the case, at least unless you are\nfamiliar with the shipping/logicstics lingo in English, if you are not\nnative. I didn't necessarily wanted to use \"stage\", it is \"sad\" because a\nnew word-hunt may be needed for a replacement to \"index\" (as \"stage\" may\nnot be a good word for i18n audience), and then we would need to keep\n\"index\", \"stage\" and that third word as interchangeable terms.\n\nSpliting the userbase by introducing a new form to an established\nterminology was bad enough, and making that three is worse.\n"},{"id":"191074","messageId":"CACBZZX7LOKqKNe09636N0xJ_VvmKP58BMDtjoKn1t5e9hJ0OiQ@mail.gmail.com","threadId":"30433","inReplyTo":"7v62c71fl7.fsf@alter.siamese.dyndns.org","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-08T08:55:56Z","receivedAt":"2012-05-08T08:55:56Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano wrote:\n\n> I didn't necessarily wanted to use \"stage\", it is \"sad\" because a\n> new word-hunt may be needed for a replacement to \"index\" (as \"stage\" may\n> not be a good word for i18n audience), and then we would need to keep\n> \"index\", \"stage\" and that third word as interchangeable terms.\n>\n> Spliting the userbase by introducing a new form to an established\n> terminology was bad enough, and making that three is worse.\n\nI don't think that line of reasoning makes sense at all. We shouldn't\nbe picking terms in the original English translation of Git that we\nthink would be more amenable to translation.\n\nWe should be picking terms that make the most sense in English, and\nthen translators will translate those into whatever makes the most\nsense in their language.\n\nHow translators work also depends largely on the language they're\ntranslating the terms into. In my experience there's three main modes\nof translation that people aim for:\n\n * Do we have a common word for it already? If so use, it, if not\n let's just use the English word. Japanese and German largely fall\n into this category.\n\n * Do we have a word for it at all or can we concoct one that makes\n sense? If so let's try to use it. Some languages like German are\n evidently struggling with the boundary between this and the first\n category.\n\n * What ideas are these terms trying to convey, and do we have an\n equivalent for those ideas in our language that we can use?\n Icelandic translations mostly aim for this.\n\nSo e.g. for Icelandic I'm not aiming to translate the shipping /\nmilitary concept of \"stage\".\n\nI'm looking at what it means in the workflow of git (a staging are for\ncommits before they're born) and using a word you'd use in Icelandic\nif you were trying to talk about some staging/preparation area.\n\nThat I have to do this isn't a failure of the original English\nversion, it's an inevitable emergence of different languages using\ndifferent terms and patterns to express similar ideas.\n"},{"id":"191093","messageId":"CAAGHeXEu6c9Sn7u4W5nk7cOE+Ao3zjyF4peHGaXe-BoUoJEisA@mail.gmail.com","threadId":"30433","inReplyTo":"CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Sebastien Douche","fromEmail":"sdouche@gmail.com","sentAt":"2012-05-08T14:01:43Z","receivedAt":"2012-05-08T14:01:43Z","isPatch":false,"sender":{"key":"sdouche@gmail.com","avatar":"https://gravatar.com/avatar/1b4a6cb11f6237ff9dc78b953ce48e416afa42e947143e14273cdc2c7f6f9c1a?d=mp&s=160"},"body":"On Sat, May 5, 2012 at 3:04 PM, Felipe Contreras\n wrote:\n> Proposal:\n>\n> Avoid the terms 'cache' and 'index' in favor of 'stage'.\n\n+1000. An anecdote: many attendees said to me \"I didn't understand\nuntil you explained it that way\". Now I use always the term \"stage\" in\nmy training (and banned the term index). Far better.\n\n\n-- \nSebastien Douche \nTwitter: @sdouche / G+: +sdouche\n"},{"id":"191098","messageId":"7vlil2zpuv.fsf@alter.siamese.dyndns.org","threadId":"30433","inReplyTo":"CACBZZX7LOKqKNe09636N0xJ_VvmKP58BMDtjoKn1t5e9hJ0OiQ@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-08T14:53:12Z","receivedAt":"2012-05-08T14:53:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano wrote:\n>\n>> I didn't necessarily wanted to use \"stage\", it is \"sad\" because a\n>> new word-hunt may be needed for a replacement to \"index\" (as \"stage\" may\n>> not be a good word for i18n audience), and then we would need to keep\n>> \"index\", \"stage\" and that third word as interchangeable terms.\n>>\n>> Spliting the userbase by introducing a new form to an established\n>> terminology was bad enough, and making that three is worse.\n>\n> I don't think that line of reasoning makes sense at all....\n> We should be picking terms that make the most sense in English, and\n> then translators will translate those into whatever makes the most\n> sense in their language.\n\nOK.\n"},{"id":"191195","messageId":"CAMP44s0DRrqMdHzOBTeQGmKtP7LzFerLZTaNgbHfj0XtebW9wA@mail.gmail.com","threadId":"30433","inReplyTo":"7v62c71fl7.fsf@alter.siamese.dyndns.org","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-09T13:10:28Z","receivedAt":"2012-05-09T13:10:28Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano wrote:\n> The word \"index\" is quite well understood: that which points at the\n> information given a headword that refers to it, which is exactly what the\n> \"index\" we have is. On the other hand, \"to stage/staging area\" is not as\n> widely used outside the narrow shipping/logistics circles.\n\nThat's what git has, *internally*, but that's not how high-level users\ninteract with it. If 'git add file' was a true index from the point of\nview of the user; then the user would have some kind of identifier,\nlike '1', or possibly and identifier of his own. Then the user could\nuse this identifier, say; give me the file '1', and the operation\nwould be much faster. But that's has *absolutely* nothing to do with\nhow users see these operations. The user does not see an index at all.\nMaybe git has an index, but it could be replaced by something else,\nand the user would still see the same; it's an implementation detail;\nnot something the user cares about.\n\nThis has been explained and discussed many times.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"191202","messageId":"vpqehqtferq.fsf@bauges.imag.fr","threadId":"30433","inReplyTo":"CAMP44s0DRrqMdHzOBTeQGmKtP7LzFerLZTaNgbHfj0XtebW9wA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-05-09T17:25:13Z","receivedAt":"2012-05-09T17:25:13Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Felipe Contreras writes:\n\n> On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano wrote:\n>> The word \"index\" is quite well understood: that which points at the\n>> information given a headword that refers to it, which is exactly what the\n>> \"index\" we have is. On the other hand, \"to stage/staging area\" is not as\n>> widely used outside the narrow shipping/logistics circles.\n>\n> That's what git has, *internally*, but that's not how high-level users\n> interact with it.\n\nI agree with that. Explaining users that the is\nthe place where you stage content in preparation for the next commit is\nmuch more productive than explaining that it is an array of\n(name, sha1sum) pairs.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"191676","messageId":"CACnwZYepxGaFqDYNEn9uW1R=Rbi_45J6pERR54btAC_vF-rJUQ@mail.gmail.com","threadId":"30433","inReplyTo":"vpqehqxmwpj.fsf@bauges.imag.fr","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2012-05-18T20:34:43Z","receivedAt":"2012-05-18T20:34:43Z","isPatch":false,"sender":{"key":"tfransosi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/970071?v=4"},"body":"On Sun, May 6, 2012 at 7:26 AM, Matthieu Moy\n wrote:\n> About the name, an alternative to \"stage\" was suggested earlier:\n> \"precommit\"\nThanks! That was the first that explained to me what cache, index, and\nstage was talking about. +1 from me (not that count much).\n"},{"id":"191708","messageId":"CAHREChgTHZL0sNJ3TkZOL7x4k9x=4GRhrZ6Gm0W+Ai_UnX2FEg@mail.gmail.com","threadId":"30433","inReplyTo":"7v1umv7ub0.fsf@alter.siamese.dyndns.org","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2012-05-19T00:50:55Z","receivedAt":"2012-05-19T00:50:55Z","isPatch":false,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Mon, May 7, 2012 at 1:52 PM, Junio C Hamano wrote:\n> the\n> shipping/logistics term \"to stage\" does not cleanly translate to the\n> language without unnecessary connotation that imply what is described is\n> something the our \"index\" actually is _not_.\n\nI agree with Felipe that \"staging\" is the most appropriate term for\n\"adding to the index\" in git. As a native English speaker, I have\nnever thought of \"to stage\" as relating to shipping in any way. To\nme, by far the most common usage is in real estate. The seller of a\nhome \"stages\" it by setting up furniture and decorations to make the\nhome as appealing to prospective buyers as possible. Just search on\nGoogle for \"home staging\" and you will get plenty of hits. This usage\nclearly originates from theater but can be found in other contexts as\nwell.\n"},{"id":"191723","messageId":"20120519060031.GB23799@burratino","threadId":"30433","inReplyTo":"CAHREChgTHZL0sNJ3TkZOL7x4k9x=4GRhrZ6Gm0W+Ai_UnX2FEg@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2012-05-19T06:00:32Z","receivedAt":"2012-05-19T06:00:32Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Mark,\n\nMark Lodato wrote:\n\n> I agree with Felipe that \"staging\" is the most appropriate term for\n> \"adding to the index\" in git. As a native English speaker, I have\n> never thought of \"to stage\" as relating to shipping in any way. To\n> me, by far the most common usage is in real estate. The seller of a\n> home \"stages\" it by setting up furniture and decorations to make the\n> home as appealing to prospective buyers as possible.\n\nI think staging a home does not fit very well here, actually. As you\nsaid, staging a home is like staging a play, creating an illusion and\nputting on a production. It is not obvious how this concept would\nhelp me understand what it means to add content to the index.\n\nBy contrast, if you run an image search for \"staging area\", you will\nsee examples in all sorts of fields --- shipping, military logistics,\ndata warehousing, disaster relief. It is a familiar, non\ndomain-specific term for native English speakers. In all these\nfields, staging means to put everything needed in one place before\ndeploying. This matches the concept of a file that tracks the content\nof the commit being prepared very well.\n\n\"aire de rassemblement\" doesn't get as many hits from a web search,\nalas, so I guess the idiom is not as popular in other languages.\n\nFor the sake of having a proposal: :)\n\n - the file representing the content of the next command would still\n be called .git/index and not be renamed\n\n - adding and removing content to and from the index is \"staging a\n change\". Since it is not safe to assume the reader already\n knows what that means, when working on the manual authors should\n try to imagine themselves as a new user and make the text\n unambiguous enough to help such a person.\n\n For example, the first sentence of the \"git add\" manual:\n\n\tThis command updates the index using the current content found in the\n\tworking tree, to prepare the content staged for the next commit.\n\n should not be changed to:\n\n\tThis command updates the staging area using ...\n\n because that just makes it less clear. Before, it said \"the index\"\n and I could look in the glossary or the .git directory to at least\n find what file it was talking about. Afterwards, it is using an\n everyday term and the new user wonders \"which staging area?\".\n\n Instead, it would be better to change it to something like:\n\n\tThis command modifies the content staged for the next commit\n\tusing content found in the working tree. It typically adds ...\n\n\tThe \"index\" file (see gitindex(5)) typically holds a snapshot of\n\tthe content of the working tree, and it is this snapshot that is\n\ttaken as the content of the next commit. Thus after making any\n\tchanges to the working directory, and before running the commit\n\tcommand, you must use the add command to add any new or modified\n\tfiles.\n\nSensible? If so, patches welcome. :) If not, what sort of changes\nwould you like to see instead?\n\nBy the way, I don't mean that \"the .git/index file will not be\nrenamed\" above to be non-negotiable. I didn't get the impression\nanyone wanted it to be renamed, but if someone does want to rename it\nto .git/staging-area, then I suppose we could discuss that.\n\nHope that helps,\nJonathan\n"},{"id":"191724","messageId":"20120519063208.GA24556@burratino","threadId":"30433","inReplyTo":"20120519060031.GB23799@burratino","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2012-05-19T06:32:09Z","receivedAt":"2012-05-19T06:32:09Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jonathan Nieder wrote:\n\n> For the sake of having a proposal: :)\n\nFor the command-line interface:\n\nMaking the \"git stage\" command more prominent. Unfortunately it is\ncurrently a synonym for \"git add\", which makes \"git rm\" less\ndiscoverable and generally isn't very helpful. But if we discard that\nproperty, it could become a nice way to make some operations more\ndiscoverable:\n\n\tgit stage --add ; # stage an addition\n\tgit stage --remove ; # stage a removal\n\tgit stage --edit ; # edit the staged content\n\tgit stage --apply ; # stage the described change\n\nThese would be commands that modify the index without touching the\nworktree.\n\nIf anyone claims this is the command for manipulating \"the stage\", we\ncan apologize for the confusing homonym and point them to a dictionary\nand images of raised platforms and staging areas and hopefully that\nwill avoid any confusion. The command is named after the verb.\n\nFinding a better mnemonic than \"also update the current directory cache\"\nand \"trust the current directory cache\" for operations like git apply\n--index and git grep --cached. Better concepts would be \"search the\ncontent staged for the next commit\" and \"also update the staged\ncontent\".\n\nMaybe:\n\n\tgit apply --index=(yes | no | only)\n\t\t# apply \t= apply --index=no\n\t\t# apply --index \t= apply --index=yes\n\t\t# apply --cached\t= apply --index=only\n\n\tgit grep --index; # (= git grep --cached)\n\nI imagine others can come up with something better.\n"},{"id":"191733","messageId":"C03B8CAB76CA449FB887C5430FDAA470@PhilipOakley","threadId":"30433","inReplyTo":"20120519060031.GB23799@burratino","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-05-19T10:14:09Z","receivedAt":"2012-05-19T10:14:09Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jonathan Nieder\" \nSent: Saturday, May 19, 2012 7:00 AM\n> Hi Mark,\n>\n> Mark Lodato wrote:\n>\n>> I agree with Felipe that \"staging\" is the most appropriate term for\n>> \"adding to the index\" in git. As a native English speaker, I have\n>> never thought of \"to stage\" as relating to shipping in any way. To\n>> me, by far the most common usage is in real estate. The seller of a\n>> home \"stages\" it by setting up furniture and decorations to make the\n>> home as appealing to prospective buyers as possible.\n>\n> I think staging a home does not fit very well here, actually. As you\n> said, staging a home is like staging a play, creating an illusion and\n> putting on a production. It is not obvious how this concept would\n> help me understand what it means to add content to the index.\n>\n> By contrast, if you run an image search for \"staging area\", you will\n> see examples in all sorts of fields --- shipping, military logistics,\n> data warehousing, disaster relief. It is a familiar, non\n> domain-specific term for native English speakers. In all these\n> fields, staging means to put everything needed in one place before\n> deploying. This matches the concept of a file that tracks the content\n> of the commit being prepared very well.\n\nAgreed. (both sentences)\nIt's about making it up as you go along. (1: it = the commit ;-)\nIn particular it's about the 'area' (noun) that we use for that \npreparation.\nUnfortunately there are no common terms because every industry, and\nlanguage, came up with its own terminology. To assist translation, we\nshould avoid being too concise in the explanation, while being \nconsistent\nwith our base terms.\n\n>\n> \"aire de rassemblement\" doesn't get as many hits from a web search,\n> alas, so I guess the idiom is not as popular in other languages.\n>\n> For the sake of having a proposal: :)\n>\n> - the file representing the content of the next command would still\n> be called .git/index and not be renamed\n>\n> - adding and removing content to and from the index is \"staging a\n> change\". Since it is not safe to assume the reader already\n> knows what that means, when working on the manual authors should\n> try to imagine themselves as a new user and make the text\n> unambiguous enough to help such a person.\n>\n> For example, the first sentence of the \"git add\" manual:\n>\n> This command updates the index using the current content found in the\n> working tree, to prepare the content staged for the next commit.\n>\n> should not be changed to:\n>\n> This command updates the staging area using ...\n>\n> because that just makes it less clear. Before, it said \"the index\"\n> and I could look in the glossary or the .git directory to at least\n> find what file it was talking about. Afterwards, it is using an\n> everyday term and the new user wonders \"which staging area?\".\n>\n> Instead, it would be better to change it to something like:\n>\n> This command modifies the content staged for the next commit\n> using content found in the working tree. It typically adds ...\n>\n> The \"index\" file (see gitindex(5)) typically holds a snapshot of\n> the content of the working tree, and it is this snapshot that is\n\nThis line, if it is a carry on from the previous, also suffers the same\nconfusion. The index file by itself does not have any of the content. We\nneed to say in some way that - The 'staging area' has the content, and\nis indexed by the index file. The staging area content itself is held\nsecurely in the object storage ready for the commit.\n\n> taken as the content of the next commit. Thus after making any\n> changes to the working directory, and before running the commit\n> command, you must use the add command to add any new or modified\n> files.\n>\n> Sensible? If so, patches welcome. :) If not, what sort of changes\n> would you like to see instead?\n>\n> By the way, I don't mean that \"the .git/index file will not be\n> renamed\" above to be non-negotiable. I didn't get the impression\n> anyone wanted it to be renamed, but if someone does want to rename it\n> to .git/staging-area, then I suppose we could discuss that.\n\nI'd agree. The file is an index.\n\n>\n> Hope that helps,\n> Jonathan\n> --\n\nPhilip\n"},{"id":"191759","messageId":"CAMP44s2cGeQq3V=jS1Xjg-S0-rMyKS79XFN9yFm+4KxMo963OA@mail.gmail.com","threadId":"30433","inReplyTo":"20120519060031.GB23799@burratino","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-20T11:49:13Z","receivedAt":"2012-05-20T11:49:13Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder wrote:\n\n> For the sake of having a proposal: :)\n>\n>  - the file representing the content of the next command would still\n>   be called .git/index and not be renamed\n\nAgreed, that is an implementation detail anyway; the changes should be\ndone with how the a typical user interacts with git, and a typical\nuser doesn't need to know the index exists.\n\n>  - adding and removing content to and from the index is \"staging a\n>   change\".  Since it is not safe to assume the reader already\n>   knows what that means, when working on the manual authors should\n>   try to imagine themselves as a new user and make the text\n>   unambiguous enough to help such a person.\n>\n>   For example, the first sentence of the \"git add\" manual:\n>\n>        This command updates the index using the current content found in the\n>        working tree, to prepare the content staged for the next commit.\n>\n>   should not be changed to:\n>\n>        This command updates the staging area using ...\n>\n>   because that just makes it less clear.  Before, it said \"the index\"\n>   and I could look in the glossary or the .git directory to at least\n>   find what file it was talking about.  Afterwards, it is using an\n>   everyday term and the new user wonders \"which staging area?\".\n\nThe git's staging area, of course. How is that not clear?\n\nIf the (new) user wants to know more about the staging area, she can\nread about it, just like she currently can. A 'man git staging-area'\nmight actually help.\n\nHowever, there's no 'man git index', or anything like that, so where\ndo you suppose new users currently look for information when they\nwonder \"what index\"? And looking into the .git directory for an\n\"index\" file? Seriously? I doubt any new user would do that, I haven't\neven done so myself. The whole point of documentation is to be user\n*friendly*.\n\n>   Instead, it would be better to change it to something like:\n>\n>        This command modifies the content staged for the next commit\n>        using content found in the working tree.  It typically adds ...\n\n>        The \"index\" file (see gitindex(5)) typically holds a snapshot of\n>        the content of the working tree, and it is this snapshot that is\n>        taken as the content of the next commit.  Thus after making any\n>        changes to the working directory, and before running the commit\n>        command, you must use the add command to add any new or modified\n>        files.\n\nI find this paragraph completely unnecessary. This is useless\ndistraction; the user wants to know about 'git add', she doesn't need\nto know about the index, and we should hide it from her.\n\nInstead, the 'git add' documentation should point to the 'man git\nstaging-area', and there, hidden somewhere is the implementation\ndetails; the index, and all the gory details.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"191760","messageId":"CAMP44s2bbJLgqOdi49jS34E79EvNtRifpCbDE_bQUys+3xrs3w@mail.gmail.com","threadId":"30433","inReplyTo":"20120519063208.GA24556@burratino","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-20T12:04:46Z","receivedAt":"2012-05-20T12:04:46Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sat, May 19, 2012 at 8:32 AM, Jonathan Nieder wrote:\n> Jonathan Nieder wrote:\n>\n>> For the sake of having a proposal: :)\n>\n> For the command-line interface:\n>\n> Making the \"git stage\" command more prominent.  Unfortunately it is\n> currently a synonym for \"git add\", which makes \"git rm\" less\n> discoverable and generally isn't very helpful.  But if we discard that\n> property, it could become a nice way to make some operations more\n> discoverable:\n>\n>        git stage --add ; # stage an addition\n>        git stage --remove ; # stage a removal\n>        git stage --edit ; # edit the staged content\n>        git stage --apply ; # stage the described change\n>\n> These would be commands that modify the index without touching the\n> worktree.\n\nIf they are commands, why do they start with --?\n\n'git stage add'\n'git stage remove'\n'git stage edit'\n\nWould be more appropriate.\n\nBut I think revamping 'git stage' should be a separate task.\n\n> Finding a better mnemonic than \"also update the current directory cache\"\n> and \"trust the current directory cache\" for operations like git apply\n> --index and git grep --cached.  Better concepts would be \"search the\n> content staged for the next commit\" and \"also update the staged\n> content\".\n>\n> Maybe:\n>\n>        git apply --index=(yes | no | only)\n>                # apply                 = apply --index=no\n>                # apply --index         = apply --index=yes\n>                # apply --cached        = apply --index=only\n>\n>        git grep --index; # (= git grep --cached)\n>\n> I imagine others can come up with something better.\n\n'index'? That goes contrary to this request; the term 'index' should\nbe avoided in porcelain commands. s/index/stage/ and the proposal\nseems sensible, but I fail to see how --stage=no could be helpful, and\n--stage=yes should be the same as --stage, and then I wonder what\nwould be the purpose of having --stage, and --stage=only, where we\ncould have a --stage(d)-only for commands that need this distinction\n(not all of them). If in the future we want more --stage=foo options,\nthen it might make sense, but I just don't see that ever happening.\n\nI guess the next step would be to list all the commands that use\n--index, --staged, and --cached, and propose new options that would\neventually help to remove --index and --cached (after some period of\ndeprecation).\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"191766","messageId":"20120520175828.GB3000@burratino","threadId":"30433","inReplyTo":"CAMP44s2cGeQq3V=jS1Xjg-S0-rMyKS79XFN9yFm+4KxMo963OA@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2012-05-20T17:58:28Z","receivedAt":"2012-05-20T17:58:28Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Felipe Contreras wrote:\n> On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder wrote:\n\n>>        The \"index\" file (see gitindex(5)) typically holds a snapshot of\n>>        the content of the working tree, and it is this snapshot that is\n>>        taken as the content of the next commit.  Thus after making any\n>>        changes to the working directory, and before running the commit\n>>        command, you must use the add command to add any new or modified\n>>        files.\n>\n> I find this paragraph completely unnecessary. This is useless\n> distraction; the user wants to know about 'git add', she doesn't need\n> to know about the index, and we should hide it from her.\n\nOk. Have you seen the current git-add(1) manpage? Do you have\npatches that improve it to avoid such useless background information\nin a non-confusing way?\n\nJonathan\n"},{"id":"191767","messageId":"20120520180606.GC3000@burratino","threadId":"30433","inReplyTo":"CAMP44s2bbJLgqOdi49jS34E79EvNtRifpCbDE_bQUys+3xrs3w@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2012-05-20T18:06:06Z","receivedAt":"2012-05-20T18:06:06Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Felipe Contreras wrote:\n> On Sat, May 19, 2012 at 8:32 AM, Jonathan Nieder wrote:\n\n>>        git stage --add ; # stage an addition\n>>        git stage --remove ; # stage a removal\n>>        git stage --edit ; # edit the staged content\n>>        git stage --apply ; # stage the described change\n>>\n>> These would be commands that modify the index without touching the\n>> worktree.\n>\n> If they are commands, why do they start with --?\n\nThey are commands because they are passed on the command line. I don't\ncare strongly about the details --- I was giving an idea for people to\npick up or not pick up.\n\n[...]\n>> Maybe:\n>>\n>>        git apply --index=(yes | no | only)\n[...]\n> 'index'? That goes contrary to this request; the term 'index' should\n> be avoided in porcelain commands. s/index/stage/ and the proposal\n> seems sensible, but I fail to see how --stage=no could be helpful\n\nIt is 'index' because the command already has an option with that\nname, which makes this more discoverable and less confusing to\nexisting users. You can like or not like that choice.\n\nHow do you negate the \"also stage this change for the next commit\"\noption passed earlier on the command line?\n\nI also don't care about the details here and wish you had phrased your\ncritique in terms of an alternate proposal instead of asking me to\ndefend mine. The only part I actually care about is that a person\nshould think carefully about individual changes, in isolation, that\nimprove git and move towards a more pleasant and consistent interface.\n\nI don't see any reason for a flag day.\n\nHope that helps,\nJonathan\n"},{"id":"191771","messageId":"7vzk92a76z.fsf@alter.siamese.dyndns.org","threadId":"30433","inReplyTo":"20120519060031.GB23799@burratino","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-20T21:11:48Z","receivedAt":"2012-05-20T21:11:48Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Mark Lodato wrote:\n>\n>> I agree with Felipe that \"staging\" is the most appropriate term for\n>> \"adding to the index\" in git. As a native English speaker, I have\n>> never thought of \"to stage\" as relating to shipping in any way. To\n>> me, by far the most common usage is in real estate. The seller of a\n>> home \"stages\" it by setting up furniture and decorations to make the\n>> home as appealing to prospective buyers as possible.\n>\n> I think staging a home does not fit very well here, actually....\n> By contrast, if you run an image search for \"staging area\", you will\n> see examples in all sorts of fields...\n> \"aire de rassemblement\" doesn't get as many hits from a web search,\n> alas, so I guess the idiom is not as popular in other languages.\n\nAll true.\n\n> Instead, it would be better to change it to something like:\n>\n> \tThis command modifies the content staged for the next commit\n> \tusing content found in the working tree. It typically adds ...\n>\n> \tThe \"index\" file (see gitindex(5)) typically holds a snapshot of\n> \tthe content of the working tree, and it is this snapshot that is\n> \ttaken as the content of the next commit. Thus after making any\n> \tchanges to the working directory, and before running the commit\n> \tcommand, you must use the add command to add any new or modified\n> \tfiles.\n>\n> Sensible?\n\nComparing between the one before \"Instead\" and the above one, I would say\nit is.\n\nI am hoping that we are not wasting people's time by the same experiment\nthat already failed very early in Git's history to hide the \"concept\" of\nthat which is used to shape the tree that would be recorded in the next\ncommit that is different from either the current commit nor the contents\nin the working tree, and instead this round is about the name of that\nthing, which has been called \"the index\" and also colloquially known as\n\"the staging area\" in many third-party documents. \n\nI personally think it is a wrong way of thinking to focus too much on the\n\"name\", though. The goal should be increased clarity and ease of learning.\nFor example, the first sentence in your example reads equally well if it\nsaid \"the content _prepared_ for the next commit\" without losing clarity\nand tells the most important thing it must tell the user: that \"add\" is\nabout updating \"that thing\" that is different from the working tree and\nthe latest commit, even if \"stage\" (verb) does not translate well to other\nlanguage.\n\nAbout the \"git stage --add/rm\" commands in your follow-up message, I have\nmixed feelings. Once users get that making progress and growing history\nwith Git is all about interacting with \"that thing\", writing out a new\ntree out of it and recording it in a new commit with appropriate parents,\nsaying \"stage\" becomes redundant. You \"add\", \"remove\", \"patch\", etc. to\naffect that is recorded in \"that thing\" (e.g. you do not \"add\" to commit).\n\nAnother reason of my \"mixed feelings\" is that an interface organized\naround what is affected, instead of around what is achieved, may be\ncounter-productive. \"add\" that adds the contents in the working tree\n(i.e. you already made the change you want yourself) to \"that thing\" makes\nsense from the work-flow point of view. It is how you edit, test or\neyeball to convince yourself that you are happy with what is in your\nworking tree, and then approach one step closer to your next commit.\n\nAn interface built around \"that thing\" may have a subcommand that adds\ncontents to \"that thing\" regardless of what is in your working tree, but\nit is useful in only special occasions (e.g. in filter-branch script that\ndoes not want/need to use a temporary working tree). Such a functionality\ndoes have a place to live, namely at the plumbing level, but already is\navailable as \"update-index\". But these commands that are organized around\n\"what\" they operate on are and should be of \"specialized\" kind, not \"end\nuser everyday activity\" commands that are designed to give easier time to\npeople in learning and using the system.\n"},{"id":"191774","messageId":"CAMP44s1Bghc6zXRQ7fJxJORiHqAgs5dg-8_cp_FoChnBG7oD4w@mail.gmail.com","threadId":"30433","inReplyTo":"7vzk92a76z.fsf@alter.siamese.dyndns.org","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-05-21T01:12:01Z","receivedAt":"2012-05-21T01:12:01Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, May 20, 2012 at 11:11 PM, Junio C Hamano wrote:\n\n> I personally think it is a wrong way of thinking to focus too much on the\n> \"name\", though.\n\nNames are important. Name it 'jaberwocky' and people would have a\nharder time trying to understand what you are talking about. Maybe\njust by hearing the name they would give up, thinking it's too\nadvanced, or too obscure, or what not.\n\nThere have been countless people that say \"me too! when I realized it\nwas X\", which suggests the current name does not help.\n\n> The goal should be increased clarity and ease of learning.\n\nAnd using a common/well understood name is a step in the right direction.\n\nBut also, once we accept that \"that thing\" is not an index, then it\nbecomes much more easy to distinguish between the abstract concept,\nand the actual index, and then we can begin to remove the index from\nthe high-level documentation and squash it to a corner where the user\ndoes not _have_ to go unless she really does want to know the\nimplementation details.\n\nRight now it's almost impossible to split the \"index\", and then index.\n\nIf the name is not important, why do you think people avoid the official name?\n\n> For example, the first sentence in your example reads equally well if it\n> said \"the content _prepared_ for the next commit\" without losing clarity\n> and tells the most important thing it must tell the user: that \"add\" is\n> about updating \"that thing\" that is different from the working tree and\n> the latest commit, even if \"stage\" (verb) does not translate well to other\n> language.\n\nIndeed, but you are missing the important part; everything else in\nthat sentence.\n\nI will put my end-user hat and read while thinking aloud the current text:\n\n\"This command updates the index\"\n\nOK, you lost me there. I don't know what is that \"index\", do I need to\nlearn what is that in order to understand the command? Maybe I\nshouldn't be reading this documentation at all.\n\nBut, OK, let's give it a try... Right, an index, well, an index of\nwhat to what? No idea. Maybe if I keep reading.\n\n\"using the current content found in the working tree, to prepare the\ncontent staged for the next commit.\n\nOK, maybe I'm beginning to understand... But I'm still not sure if I\nshould be touching this index thing, I don't understand what is being\nindexed.\n\n> About the \"git stage --add/rm\" commands in your follow-up message, I have\n> mixed feelings.  Once users get that making progress and growing history\n> with Git is all about interacting with \"that thing\", writing out a new\n> tree out of it and recording it in a new commit with appropriate parents,\n> saying \"stage\" becomes redundant.  You \"add\", \"remove\", \"patch\", etc. to\n> affect that is recorded in \"that thing\" (e.g. you do not \"add\" to commit).\n\nWhile I would not like to touch the 'git stage' at this point--nor do\nI think it's needed--, I don't agree with what you said. In certain\ncommands it might be redundant, but I specially disagree on these:\n\nThe 'add' command has a long tradition in SCM; it adds a file for\ncontent tracking--nothing more.\n\nUsing 'add' to *update* the staging area seems completely and totally\ncounter-intuitive to me. Adding something means that something was not\nthere; if it was there, you couldn't add it.\n\nOf course, that's if you think about files, but it makes sense if you\nthink about changes instead, but 'git add file' and 'git add file' do\nvery different things conceptually depending on weather 'file' was\ntracked or not; one would \"add a file\" (to git), and the other would\n\"add the changes of the file\" (to the staging area). Splitting the\ncommand in two would make this difference in concepts clearer.\n\nAnd then we have all sorts of confusion. --patch; I thought we were\nadding patches to the staging area, this is redundant, --selectively\nmight make more sense. --update; I thought we were updating! --updated\nmight make more sense. And what happens when you do 'git add --patch\nuntracked-file' (or --update)? That's very strange.\n\nIf we have a 'stage' command things become much simpler:\n\ngit add untracked-file # maybe as the current 'git add --intent-to-add'\ngit add tracked-file # no-op (error?)\ngit add --patch file # doesn't make sense; option not present\ngit add --update file # doesn't make sense; option not present\n\ngit stage untracked-file # add, and stage it, why not?\ngit stage tracked-file\ngit stage --hunks file\ngit stage --updates file\n\nAt this point 'git add' would not be doing much, and might even go\naway, but I guess it's nice for people coming from other SCMs.\n\n'rm' is similar, could be solved by 'unstage'.\n\nEither way, I have proposed to use stage/unstage before I think,\nwithout much success, so I think the only realist option to move\nforward is to add --stage(d) and --stage-only.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"191776","messageId":"20120521013234.GA3055@burratino","threadId":"30433","inReplyTo":"CAMP44s1Bghc6zXRQ7fJxJORiHqAgs5dg-8_cp_FoChnBG7oD4w@mail.gmail.com","subject":"Re: [1.8.0] use 'stage' term consistently","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2012-05-21T01:32:34Z","receivedAt":"2012-05-21T01:32:34Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Felipe,\n\nFelipe Contreras wrote:\n\n> Indeed, but you are missing the important part; everything else in\n> that sentence.\n\nYou're probably onto something, but I'm missing the point in your\nmessage. Could you repeat, carefully explaining:\n\n - what change you would like to propose in git\n - whether it is backward compatible, and if it is not, what\n transition plan you propose\n - briefly, the rationale behind the change, in such a way as to\n convince skeptics like me that it is a good idea and to recruit\n us to help in your cause\n\n? For that third part, a good example to take inspiration from is the\nproject to improve Linux to function as a real-time operating system.\nEach change is so well justified _individually_ that someone not\ninterested at all in that goal can still not help but agree with the\nchanges!\n\nPerhaps your message includes these elements already, but I found it\nhard to follow, hence this request.\n\nThanks,\nJonathan\n"}]}