{"thread":{"id":"17393","subject":"friendlier names","startedAt":"2009-01-27T15:30:04Z","lastAt":"2009-01-28T04:51:25Z","messageCount":10,"participants":["David Abrahams","Felipe Contreras","Shawn O. Pearce","Johannes Schindelin","Junio C Hamano","Jakub Narebski"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"102126","messageId":"87mydc6a2r.fsf@mcbain.luannocracy.com","threadId":"17393","inReplyTo":null,"subject":"friendlier names","fromName":"David Abrahams","fromEmail":"dave@boostpro.com","sentAt":"2009-01-27T15:30:04Z","receivedAt":"2009-01-27T15:30:04Z","isPatch":false,"sender":{"key":"dave@boostpro.com","avatar":"https://gravatar.com/avatar/df0921f05114687777894565de21c052fb137ba7c303a399528b43d08833f065?d=mp&s=160"},"body":"\nI'm absolutely certain I'm not the first person to have raised this\nissue, so feel free to point me at the threads where I can get the\nrationale... but: to me it looks like git's choice of terminology hurts\nits adoption and learnability. \n\nFor example, why couldn't the \"index\" be called the \"stage\" instead?\nThat, along with knowing that \"git add\" was a synonym for \"git stage\"\nwould have flattened the learning curve considerably for me.\n\nThanks,\n\n-- \nDave Abrahams\nBoostPro Computing\nhttp://www.boostpro.com\n"},{"id":"102127","messageId":"94a0d4530901270733q222a6181k25b1da91b35e72d4@mail.gmail.com","threadId":"17393","inReplyTo":"87mydc6a2r.fsf@mcbain.luannocracy.com","subject":"Re: friendlier names","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-01-27T15:33:23Z","receivedAt":"2009-01-27T15:33:23Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Jan 27, 2009 at 5:30 PM, David Abrahams wrote:\n>\n> I'm absolutely certain I'm not the first person to have raised this\n> issue, so feel free to point me at the threads where I can get the\n> rationale... but: to me it looks like git's choice of terminology hurts\n> its adoption and learnability.\n>\n> For example, why couldn't the \"index\" be called the \"stage\" instead?\n> That, along with knowing that \"git add\" was a synonym for \"git stage\"\n> would have flattened the learning curve considerably for me.\n\n+1\n\nI think several people have mentioned it, and there have been\ndifferent possible actions, but nothing concrete AFAIK.\n\n-- \nFelipe Contreras\n"},{"id":"102129","messageId":"20090127153837.GB1321@spearce.org","threadId":"17393","inReplyTo":"87mydc6a2r.fsf@mcbain.luannocracy.com","subject":"Re: friendlier names","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2009-01-27T15:38:37Z","receivedAt":"2009-01-27T15:38:37Z","isPatch":false,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"David Abrahams wrote:\n> \n> For example, why couldn't the \"index\" be called the \"stage\" instead?\n> That, along with knowing that \"git add\" was a synonym for \"git stage\"\n> would have flattened the learning curve considerably for me.\n\nHistorical reasons...\n\nWaaay back the \"index\" was an index of the files git knows about in\nyour working directory. It made sense to call it an index, as like\na book index it was a full listing of what's here, sorted by name.\n\nThat's pre-1.0 days. Like the very first version Linus ever\nreleased. Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.\n\nMuch, much later, over many months, the index morphed into what\nyou see today, which is a \"staging area\", accessed by \"git add\".\n\nThis was all incremental, in small parts. Nobody set out to\ndesign a \"staging area\" or to have \"staging actions\". Back\nwhen it was really the index you updated it with a tool called\ngit-update-index. Adding new files required the --add flag.\n\nPeople found --add annoying, so they wrote \"git add\" as a\nwrapper around it. But modified existing files still had\nto be updated with git-update-index. Then someone pointed\nout that add of an existing file and add of a new file are\nsimiliar enough that they should just be the same command,\n\"git add\".\n\nOnly late last October at the GitTogether did we start to talk about\ncreating a command called \"git stage\", because people have started to\nrealize we seem to call it a \"staging area\" as we train newcomers...\n\nThe tools are _all_ slowly evolved over time. Nothing in git\nwas ever set out from the beginning as a \"this is what we are\ngoing to do\". The only part of Git that is like that is the core\ndata structure on disk for the object store. That hasn't changed\nsince Linus switched from SHA1(COMPRESS(data)) to SHA1(data) for\nthe object naming algorithm, and even that was done in the first\ncouple of weeks.\n\n-- \nShawn.\n"},{"id":"102134","messageId":"87vds04s9a.fsf@mcbain.luannocracy.com","threadId":"17393","inReplyTo":"20090127153837.GB1321@spearce.org","subject":"Re: friendlier names","fromName":"David Abrahams","fromEmail":"dave@boostpro.com","sentAt":"2009-01-27T16:40:17Z","receivedAt":"2009-01-27T16:40:17Z","isPatch":false,"sender":{"key":"dave@boostpro.com","avatar":"https://gravatar.com/avatar/df0921f05114687777894565de21c052fb137ba7c303a399528b43d08833f065?d=mp&s=160"},"body":"\non Tue Jan 27 2009, \"Shawn O. Pearce\" wrote:\n\n> David Abrahams wrote:\n>> \n>> For example, why couldn't the \"index\" be called the \"stage\" instead?\n>> That, along with knowing that \"git add\" was a synonym for \"git stage\"\n>> would have flattened the learning curve considerably for me.\n>\n> Historical reasons...\n>\n> Waaay back the \"index\" was an index of the files git knows about in\n> your working directory. It made sense to call it an index, as like\n> a book index it was a full listing of what's here, sorted by name.\n>\n> That's pre-1.0 days. Like the very first version Linus ever\n> released. Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.\n\nI'm not saying \"index\" doesn't make sense. It _still_ makes sense. It\njust doesn't make as much sense as \"stage.\" Index is a very generic\nterm; it doesn't communicate enough.\n\n> Much, much later, over many months, the index morphed into what\n> you see today, which is a \"staging area\", accessed by \"git add\".\n>\n> This was all incremental, in small parts. Nobody set out to\n> design a \"staging area\" or to have \"staging actions\". Back\n> when it was really the index you updated it with a tool called\n> git-update-index. Adding new files required the --add flag.\n>\n> People found --add annoying, so they wrote \"git add\" as a\n> wrapper around it. But modified existing files still had\n> to be updated with git-update-index. Then someone pointed\n> out that add of an existing file and add of a new file are\n> similiar enough that they should just be the same command,\n> \"git add\".\n>\n> Only late last October at the GitTogether did we start to talk about\n> creating a command called \"git stage\", because people have started to\n> realize we seem to call it a \"staging area\" as we train newcomers...\n\nSounds like, from everything you've said, \"stage\" rather than \"index\"\nwould have been just as sensible in the beginning as it is today; it's\njust that you have a much nicer interface for working with it.\n\n> The tools are _all_ slowly evolved over time. Nothing in git\n> was ever set out from the beginning as a \"this is what we are\n> going to do\". The only part of Git that is like that is the core\n> data structure on disk for the object store. That hasn't changed\n> since Linus switched from SHA1(COMPRESS(data)) to SHA1(data) for\n> the object naming algorithm, and even that was done in the first\n> couple of weeks.\n\nOK, thanks for the history lesson. It's good to know someone is paying\nattention to these things. Is there any movement toward addressing\nthem outside of GitTogether talk?\n\n-- \nDave Abrahams\nBoostPro Computing\nhttp://www.boostpro.com\n"},{"id":"102149","messageId":"alpine.DEB.1.00.0901271910070.3586@pacific.mpi-cbg.de","threadId":"17393","inReplyTo":"20090127153837.GB1321@spearce.org","subject":"Re: friendlier names","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2009-01-27T18:10:34Z","receivedAt":"2009-01-27T18:10:34Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 27 Jan 2009, Shawn O. Pearce wrote:\n\n> David Abrahams wrote:\n> > \n> > For example, why couldn't the \"index\" be called the \"stage\" instead?\n> > That, along with knowing that \"git add\" was a synonym for \"git stage\"\n> > would have flattened the learning curve considerably for me.\n> \n> Historical reasons...\n> \n> Waaay back the \"index\" was an index of the files git knows about in\n> your working directory. It made sense to call it an index, as like\n> a book index it was a full listing of what's here, sorted by name.\n> \n> That's pre-1.0 days. Like the very first version Linus ever\n> released. Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.\n\nActually, it was known by the name \"dircache\" back then :-)\n\nCiao,\nDscho\n"},{"id":"102154","messageId":"7vwscgy56b.fsf@gitster.siamese.dyndns.org","threadId":"17393","inReplyTo":"20090127153837.GB1321@spearce.org","subject":"Re: friendlier names","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-27T18:28:28Z","receivedAt":"2009-01-27T18:28:28Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Shawn O. Pearce\" writes:\n\n> David Abrahams wrote:\n>> \n>> For example, why couldn't the \"index\" be called the \"stage\" instead?\n>> That, along with knowing that \"git add\" was a synonym for \"git stage\"\n>> would have flattened the learning curve considerably for me.\n>\n> Historical reasons...\n>\n> Waaay back the \"index\" was an index of the files git knows about in\n> your working directory. It made sense to call it an index, as like\n> a book index it was a full listing of what's here, sorted by name.\n>\n> That's pre-1.0 days. Like the very first version Linus ever\n> released. Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.\n\nThis part is a bit misleading, if not completely incorrect.\n\nSince day 1, the entity we now call \"the index aka staging area\" has been\njust that. It was originally called \"cache\" and it implemented a cache of\n_contents_ that are meant to go in the tree the next commit records. It\nwas renamed to the \"index\" because it is an index, which you can consult\nwith a pathname as the key to get to the _contents_ as its value.\n\nIt never was \"list of pathnames\" without _contents_. So it was a staging\narea from day one.\n\nThe way to update the cache was called \"update-cache\" then \"update-index\".\nBecause it usually is much rare to actually add a new entry to the index\nthan updating an existing entry in the index, the command had a safeguard\nagainst \"update-cache a-newfile\" without explicit request from the user to\nsay \"oh by the way I know I am adding new entries\". \"git add\" came much\nlater to give you a shorthand for \"update-index --add\". Updating existing\nentries in the index was still done with \"update-index\".\n\nLater Nico taught (after much discussion) \"git add\" to also serve as\n\"update-index\" for existing entries in the index.\n\nWe could have called it \"git update-index\" when we did that switch-over,\nbecause the operation is exactly that --- updating the index.\n\nBut the name somehow stuck.\n\n> Only late last October at the GitTogether did we start to talk about\n> creating a command called \"git stage\", because people have started to\n> realize we seem to call it a \"staging area\" as we train newcomers...\n\nYeah, you may have to consider the possibility that that particular\ntraining lingo is inconsistent with the rest of the system, exactly\nbecause it came from outside.\n"},{"id":"102157","messageId":"m37i4gy2z6.fsf@localhost.localdomain","threadId":"17393","inReplyTo":"7vwscgy56b.fsf@gitster.siamese.dyndns.org","subject":"Re: friendlier names","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2009-01-27T19:17:17Z","receivedAt":"2009-01-27T19:17:17Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano writes:\n> \"Shawn O. Pearce\" writes:\n>> David Abrahams wrote:\n>>> \n>>> For example, why couldn't the \"index\" be called the \"stage\" instead?\n>>> That, along with knowing that \"git add\" was a synonym for \"git stage\"\n>>> would have flattened the learning curve considerably for me.\n>>\n>> Historical reasons...\n\n[...]\n> The way to update the cache was called \"update-cache\" then \"update-index\".\n> Because it usually is much rare to actually add a new entry to the index\n> than updating an existing entry in the index, the command had a safeguard\n> against \"update-cache a-newfile\" without explicit request from the user to\n> say \"oh by the way I know I am adding new entries\". \"git add\" came much\n> later to give you a shorthand for \"update-index --add\". Updating existing\n> entries in the index was still done with \"update-index\".\n> \n> Later Nico taught (after much discussion) \"git add\" to also serve as\n> \"update-index\" for existing entries in the index.\n> \n> We could have called it \"git update-index\" when we did that switch-over,\n> because the operation is exactly that --- updating the index.\n> \n> But the name somehow stuck.\n[...]\n\nIt is a bit of pity that \"git add\" was overloaded to also add new\ncontents and not only add new file (and its contents!), instead of\nhaving new command \"git stage\" to be porcelain version of \n\"git update-index\" porcelain. And perhaps \"git resolved\" to only\nmark resolved entries (so e.g. \"git resolved .\" would not add new\nfiles, nor add new contents of files which were not in conflict).\n\nNow we have to explain that \"git add\" adds new contents... OTOH\nit is perhaps good idea to emphasize differences between Git and\nother lesser^W SCMs. ;-) And introduce \"git add -N\"... \n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"102159","messageId":"7vocxsy1dd.fsf@gitster.siamese.dyndns.org","threadId":"17393","inReplyTo":"m37i4gy2z6.fsf@localhost.localdomain","subject":"Re: friendlier names","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-27T19:50:38Z","receivedAt":"2009-01-27T19:50:38Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski writes:\n\n> It is a bit of pity that \"git add\" was overloaded to also add new\n> contents and not only add new file (and its contents!), instead of\n> having new command \"git stage\" to be porcelain version of \n> \"git update-index\" porcelain. And perhaps \"git resolved\" to only\n> mark resolved entries (so e.g. \"git resolved .\" would not add new\n> files, nor add new contents of files which were not in conflict).\n\nI do not think so.\n\nPeople who are taught with various means (including \"git stage\" alias)\nunderstand that you prepare the contents you want to record in the commit\nyou are about to make by updating the contents registered in the index aka\nstaging area, then you do not need \"git resolved\".\n\nYou resolve, you have the desired content in your work tree, and you\nregister the updated contents from your work tree to the index aka staging\narea, in exactly the same way as you do when you want to include updated\ncontents for any commit.\n"},{"id":"102225","messageId":"200901280312.16717.jnareb@gmail.com","threadId":"17393","inReplyTo":"7vocxsy1dd.fsf@gitster.siamese.dyndns.org","subject":"Re: friendlier names","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2009-01-28T02:12:16Z","receivedAt":"2009-01-28T02:12:16Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano wrote:\n> Jakub Narebski writes:\n> \n> > It is a bit of pity that \"git add\" was overloaded to also add new\n> > contents and not only add new file (and its contents!), instead of\n> > having new command \"git stage\" to be porcelain version of \n> > \"git update-index\" porcelain. And perhaps \"git resolved\" to only\n> > mark resolved entries (so e.g. \"git resolved .\" would not add new\n> > files, nor add new contents of files which were not in conflict).\n> \n> I do not think so.\n> \n> People who are taught with various means (including \"git stage\" alias)\n> understand that you prepare the contents you want to record in the commit\n> you are about to make by updating the contents registered in the index aka\n> staging area, then you do not need \"git resolved\".\n\n\"Who are taught\". This makes for Git to be more \"user selective\".\nNot that this matter much, as world domination is not our goal ;-)\n \n> You resolve, you have the desired content in your work tree, and you\n> register the updated contents from your work tree to the index aka staging\n> area, in exactly the same way as you do when you want to include updated\n> contents for any commit.\n\nWhile I don't think that \"git resolved\" is something really needed,\nthe difference is with \"git add .\" and \"git resolved .\" and between\n\"git add *\" and \"git resolved *\", where the latter would update only\nresolved merge conflict resolutions, and would not pick up independent\nchanges to the files that were not in conflict.\n\nBTW with \"git add\" way you have to know that \"git add\"-ing a file\nwould clear 'is in merge conflict' flags (well, will hide >0 stages...).\n\n-- \nJakub Narebski\nPoland\n"},{"id":"102250","messageId":"7vwscgvxrm.fsf@gitster.siamese.dyndns.org","threadId":"17393","inReplyTo":"200901280312.16717.jnareb@gmail.com","subject":"Re: friendlier names","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-28T04:51:25Z","receivedAt":"2009-01-28T04:51:25Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski writes:\n\n> BTW with \"git add\" way you have to know that \"git add\"-ing a file\n> would clear 'is in merge conflict' flags (well, will hide >0 stages...).\n\nSigh...\n\nAgain, you seem to be affected by the same confusion that caused you to\nthink \"git resolved\" may have some reason to exist.\n\nAn unmerged index with higer stages means that the contents that need to\nbe in the next commit is _unknown_ for the paths.\n\nIf somebody says \"I am telling you that this path has the contents I want\nto have in the commit I will create next\" (which is what \"staging\" the\ncontents in the \"index\" is), what plausible reason does git have to keep\nthe higher stages for them? At that point, the contents the user wants to\nhave for these paths are known.\n"}]}