{"thread":{"id":"23582","subject":"Recent documentation patches, and an RFC on terminology","startedAt":"2010-04-23T21:54:48Z","lastAt":"2010-04-25T00:31:52Z","messageCount":8,"participants":["Eric Raymond","Björn Steinbrink","Nicolas Pitre","Junio C Hamano","Adam Brewster","Aghiles"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"140240","messageId":"20100423215448.1EF5B479E92@snark.thyrsus.com","threadId":"23582","inReplyTo":null,"subject":"Recent documentation patches, and an RFC on terminology","fromName":"Eric Raymond","fromEmail":"esr@snark.thyrsus.com","sentAt":"2010-04-23T21:54:48Z","receivedAt":"2010-04-23T21:54:48Z","isPatch":false,"sender":{"key":"esr@snark.thyrsus.com","avatar":null},"body":"I just sent two documentation patches to the list in quick succession.\nIn case they arrive out of order: the first, smaller one - modifying\nonly the git-status documentation - should be applied before the \nsecond one (distinguishing between \"staging area\" and \"index\"\nthroughout the documentation).\n\nWe may have an opportunity to improve on the term \"staging area\". As\nI reflect on it, I think replacing that with the term \"depot\" might\nnot be a bad idea. In English this word has the general sense of\n\"warehouse\", and the more specialized connotation of a place where\nfreight is temporarily held for transshipment, or where military\nsupplies and recruits are mustered before field deployment. That is,\na depot is a particular kind of staging area.\n\nSince these terms are so similar, why change?\n\nOne reason is that --depot would be a shorter and more graceful choice \nthan --staging-area as a long-form option. It has the same letter\ncount as \"index\", so changing command and option names to use it \nwouldn't add more typing.\n\nAnother reason is that \"depot\" is slightly more distant from normal\nEnglish vocabulary than \"staging area\" is. When you need a word to \nco-opt as a technical term of art, thast's an advantage; it reduces \nthe chances of collisions between term-of-art and normal usages.\n\nIf this proposal is accepted, I can very easly generate a patch to\nimplement it. Teasing apart \"index\" from \"staging area\" was actual \nwork, but now that the distinction has been made replacing the latter\nwould be trivial.\n-- \n\t\tEric S. Raymond\n\nThe politician attempts to remedy the evil by increasing the very thing\nthat caused the evil in the first place: legal plunder.\n\t-- Frederick Bastiat\n"},{"id":"140241","messageId":"20100423221433.GB29661@atjola.homenet","threadId":"23582","inReplyTo":"20100423215448.1EF5B479E92@snark.thyrsus.com","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Björn Steinbrink","fromEmail":"b.steinbrink@gmx.de","sentAt":"2010-04-23T22:14:33Z","receivedAt":"2010-04-23T22:14:33Z","isPatch":false,"sender":{"key":"b.steinbrink@gmx.de","avatar":"https://avatars.githubusercontent.com/u/230962?v=4"},"body":"On 2010.04.23 17:54:48 -0400, Eric Raymond wrote:\n> We may have an opportunity to improve on the term \"staging area\". As\n> I reflect on it, I think replacing that with the term \"depot\" might\n> not be a bad idea.\n\nIIRC Perforce already uses the term \"depot\" for something that's not\nquite git's index (your other mail didn't make it to me yet, so I\ncouldn't quickly look up how you differentiate between the \"staging\narea\" and the index). There have been people in #git that used the term\n\"depot\", and till now I simply guessed that they meant \"repository\", and\nthat seemed to fit. Introducing git's own definition of \"depot\" will\nprobably cause confusion when talking to (former) perforce users, so I'd\nrather avoid that term.\n\nBjörn\n"},{"id":"140244","messageId":"20100423222956.GB21224@thyrsus.com","threadId":"23582","inReplyTo":"20100423221433.GB29661@atjola.homenet","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Eric Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2010-04-23T22:29:56Z","receivedAt":"2010-04-23T22:29:56Z","isPatch":false,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Björn Steinbrink :\n> (your other mail didn't make it to me yet, so I\n> couldn't quickly look up how you differentiate between the \"staging\n> area\" and the index).\n\n*Groan*...is the Great Galactic Ghoul randomly eating my patch submissions\nagain? I'll check the archives...\n\nBasically, I changed the docs to use \"staging area\" when talking about \nworkflow and \"index\" only when describing implementation.\n-- \n\t\tEric S. Raymond\n"},{"id":"140246","messageId":"alpine.LFD.2.00.1004231920580.7232@xanadu.home","threadId":"23582","inReplyTo":"20100423222956.GB21224@thyrsus.com","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-04-23T23:21:55Z","receivedAt":"2010-04-23T23:21:55Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 23 Apr 2010, Eric Raymond wrote:\n\n> Björn Steinbrink :\n> > (your other mail didn't make it to me yet, so I\n> > couldn't quickly look up how you differentiate between the \"staging\n> > area\" and the index).\n> \n> *Groan*...is the Great Galactic Ghoul randomly eating my patch submissions\n> again? I'll check the archives...\n> \n> Basically, I changed the docs to use \"staging area\" when talking about \n> workflow and \"index\" only when describing implementation.\n\nIf so that should be a good thing.\n\n\nNicolas\n"},{"id":"140256","messageId":"7vd3xpqppa.fsf@alter.siamese.dyndns.org","threadId":"23582","inReplyTo":"alpine.LFD.2.00.1004231920580.7232@xanadu.home","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-24T07:23:13Z","receivedAt":"2010-04-24T07:23:13Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre writes:\n\n> On Fri, 23 Apr 2010, Eric Raymond wrote:\n>\n>> Björn Steinbrink :\n>> > (your other mail didn't make it to me yet, so I\n>> > couldn't quickly look up how you differentiate between the \"staging\n>> > area\" and the index).\n>> \n>> *Groan*...is the Great Galactic Ghoul randomly eating my patch submissions\n>> again? I'll check the archives...\n>> \n>> Basically, I changed the docs to use \"staging area\" when talking about \n>> workflow and \"index\" only when describing implementation.\n>\n> If so that should be a good thing.\n\nDo you mean that Ghoul did a good thing to eat such a change?\n"},{"id":"140270","messageId":"alpine.LFD.2.00.1004240903060.7232@xanadu.home","threadId":"23582","inReplyTo":"7vd3xpqppa.fsf@alter.siamese.dyndns.org","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Nicolas Pitre","fromEmail":"nico@fluxnic.net","sentAt":"2010-04-24T13:04:30Z","receivedAt":"2010-04-24T13:04:30Z","isPatch":false,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Sat, 24 Apr 2010, Junio C Hamano wrote:\n\n> Nicolas Pitre writes:\n> \n> > On Fri, 23 Apr 2010, Eric Raymond wrote:\n> >\n> >> Björn Steinbrink :\n> >> > (your other mail didn't make it to me yet, so I\n> >> > couldn't quickly look up how you differentiate between the \"staging\n> >> > area\" and the index).\n> >> \n> >> *Groan*...is the Great Galactic Ghoul randomly eating my patch submissions\n> >> again? I'll check the archives...\n> >> \n> >> Basically, I changed the docs to use \"staging area\" when talking about \n> >> workflow and \"index\" only when describing implementation.\n> >\n> > If so that should be a good thing.\n> \n> Do you mean that Ghoul did a good thing to eat such a change?\n\n:-)\n\nI meant that the proposed change to the doc as described above should be \na good change.\n\n\nNicolas\n"},{"id":"140286","messageId":"l2oc376da901004240956o1af1abeoea0e10a86d8ef277@mail.gmail.com","threadId":"23582","inReplyTo":"20100423215448.1EF5B479E92@snark.thyrsus.com","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Adam Brewster","fromEmail":"adambrewster@gmail.com","sentAt":"2010-04-24T16:56:01Z","receivedAt":"2010-04-24T16:56:01Z","isPatch":false,"sender":{"key":"adambrewster@gmail.com","avatar":"https://avatars.githubusercontent.com/u/223816?v=4"},"body":"On 4/23/10, Eric Raymond wrote:\n> I just sent two documentation patches to the list in quick succession.\n> In case they arrive out of order: the first, smaller one - modifying\n> only the git-status documentation - should be applied before the\n> second one (distinguishing between \"staging area\" and \"index\"\n> throughout the documentation).\n>\n\nI didn't get the patch which distinguishes index vs. staging area, but\nI did get 'Typo fixes and minor cleanups for the big \"index\"/\"staging\narea patch', so I can see some of what it did.\n\nBased on my limited view, I think it makes things more confusing. I'd\nrather see references to the index be replaced with \"the staging area\n(a.k.a. the index)\" than long winded explanations like \"the index is\nthe structure used to store the content of the staging area\" or \"the\nstaging area used to be called the index\".\n\n> We may have an opportunity to improve on the term \"staging area\". As\n> I reflect on it, I think replacing that with the term \"depot\" might\n> not be a bad idea. In English this word has the general sense of\n> \"warehouse\", and the more specialized connotation of a place where\n> freight is temporarily held for transshipment, or where military\n> supplies and recruits are mustered before field deployment. That is,\n> a depot is a particular kind of staging area.\n>\n\nTo me, \"depot\" has connotations of transportation. A depot is a place\nto catch a train or a bus.\n\nStaging area describes exactly how we use the index. An area where\nthings are staged (prepared) to be committed.\n\n> Since these terms are so similar, why change?\n>\n> One reason is that --depot would be a shorter and more graceful choice\n> than --staging-area as a long-form option. It has the same letter\n> count as \"index\", so changing command and option names to use it\n> wouldn't add more typing.\n>\n\nWhy not keep index as a synonym for staging area and use --index?\n\n> Another reason is that \"depot\" is slightly more distant from normal\n> English vocabulary than \"staging area\" is. When you need a word to\n> co-opt as a technical term of art, thast's an advantage; it reduces\n> the chances of collisions between term-of-art and normal usages.\n>\n\nI haven't seen such collisions causing problems.\n\nAdam\n"},{"id":"140311","messageId":"j2g3abd05a91004241731ofcb744b4z266d656ae85bb1b7@mail.gmail.com","threadId":"23582","inReplyTo":"20100423215448.1EF5B479E92@snark.thyrsus.com","subject":"Re: Recent documentation patches, and an RFC on terminology","fromName":"Aghiles","fromEmail":"aghilesk@gmail.com","sentAt":"2010-04-25T00:31:52Z","receivedAt":"2010-04-25T00:31:52Z","isPatch":false,"sender":{"key":"aghilesk@gmail.com","avatar":null},"body":"Hello Eric,\n\n> We may have an opportunity to improve on the term \"staging area\". As\n> I reflect on it, I think replacing that with the term \"depot\" might\n> not be a bad idea. In English this word has the general sense of\n> \"warehouse\", and the more specialized connotation of a place where\n> freight is temporarily held for transshipment, or where military\n> supplies and recruits are mustered before field deployment. That is,\n> a depot is a particular kind of staging area.\n\nFor what it's worth: I am a non-expert git user and I find the name \"staging\narea\" to be perfectly adapted. With this terminology, it makes it easier\nfor me to explain some git principles to new git users.\n\nThe name \"depot\" is confusing because there is no expectation of a\nfollowing action. I already see this question coming: \"can I leave my files in\nthe depot now?\"\n\n -- aghiles\n"}]}