{"thread":{"id":"21344","subject":"[PATCH v2 0/2] user-manual: new \"getting started\" section","startedAt":"2009-10-24T09:44:47Z","lastAt":"2009-11-18T00:05:47Z","messageCount":28,"participants":["Felipe Contreras","Nanako Shiraishi","Björn Steinbrink","Junio C Hamano","J. Bruce Fields","Jonathan Nieder","Michael J Gruber","Matthieu Moy"],"isPatch":true,"patchVersion":2,"patchTotal":2},"messages":[{"id":"125831","messageId":"1256377489-16719-1-git-send-email-felipe.contreras@gmail.com","threadId":"21344","inReplyTo":null,"subject":"[PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T09:44:47Z","receivedAt":"2009-10-24T09:44:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This basically introduces the \"getting started\" section so users get familiar\nwith the configuration from the get-go, and also, most people prefer to teach\n'git config --global' to setup the user name and email. Here are a few\nexamples:\n\ngit tutorial:\nhttp://www.kernel.org/pub/software/scm/git/docs/gittutorial.html\n\nGNOME:\nhttp://live.gnome.org/Git/Developers\n\nSourceForge:\nhttp://sourceforge.net/apps/trac/sourceforge/wiki/Git\n\ngithub:\nhttp://help.github.com/git-email-settings/\n\nv2:\n\nReworded the getting started section based on comments from Michael J Gruber,\nJonathan Nieder and Junio C Hamano.\n\nFelipe Contreras (2):\n user-manual: add global config section\n user-manual: simplify the user configuration\n\n Documentation/user-manual.txt | 37 ++++++++++++++++++++++++++++++++-----\n 1 files changed, 32 insertions(+), 5 deletions(-)\n"},{"id":"125832","messageId":"1256377489-16719-2-git-send-email-felipe.contreras@gmail.com","threadId":"21344","inReplyTo":"1256377489-16719-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 1/2] user-manual: add global config section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T09:44:48Z","receivedAt":"2009-10-24T09:44:48Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Comments from Michael J Gruber, Jonathan Nieder and Junio C Hamano.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/user-manual.txt | 29 +++++++++++++++++++++++++++++\n 1 files changed, 29 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 67ebffa..3fcbc36 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -40,6 +40,35 @@ without any explanation.\n Finally, see <> for ways that you can help make this manual more\n complete.\n \n+[[getting-started]]\n+Getting started\n+=============\n+\n+Various configuration options affect how git operates. Some are specific to\n+the user (e.g. if you prefer to see the output in colour), while some are\n+specific to a repository (e.g. what other repositories it interacts with).\n+\n+For example, you can tell git to use color in the output of commands such as\n+`git diff` by setting the `color.ui` option:\n+------------------------------------------------\n+$ git config --global color.ui auto\n+------------------------------------------------\n+\n+Note that in this case the option is stored in the 'global' configuration. If\n+you don't specify `--global`, then the option will be stored on the local\n+(repository) configuration, which is probably not what you want.\n+\n+The options are stored in plain text files that you can view, or edit manually\n+using the `--edit` option, and the format is very simple:\n+------------------------------------------------\n+$ git config --global --edit\n+[color]\n+ ui = auto\n+------------------------------------------------\n+\n+This manual covers many configuration options (such as `color.ui`). For\n+more details on the `git config` command, as well as all configuration\n+options see linkgit:git-config[1].\n \n [[repositories-and-branches]]\n Repositories and Branches\n-- \n1.6.5.1\n"},{"id":"125833","messageId":"1256377489-16719-3-git-send-email-felipe.contreras@gmail.com","threadId":"21344","inReplyTo":"1256377489-16719-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v2 2/2] user-manual: simplify the user configuration","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T09:44:49Z","receivedAt":"2009-10-24T09:44:49Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This is shorter, avoids the burder to think about the format of the\nconfiguration file, and git config is already used in other places in\nthe manual.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/user-manual.txt | 8 +++-----\n 1 files changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 3fcbc36..a0a75af 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1010,13 +1010,11 @@ Telling git your name\n ---------------------\n \n Before creating any commits, you should introduce yourself to git. The\n-easiest way to do so is to make sure the following lines appear in a\n-file named .gitconfig in your home directory:\n+easiest way is to use the linkgit:git-config[1] command:\n \n ------------------------------------------------\n-[user]\n-\tname = Your Name Comes Here\n-\temail = you@yourdomain.example.com\n+$ git config --global user.name \"Your Name Comes Here\"\n+$ git config --global user.email you@yourdomain.example.com\n ------------------------------------------------\n \n (See the \"CONFIGURATION FILE\" section of linkgit:git-config[1] for\n-- \n1.6.5.1\n"},{"id":"125841","messageId":"20091024220644.6117@nanako3.lavabit.com","threadId":"21344","inReplyTo":"1256377489-16719-1-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-10-24T13:06:44Z","receivedAt":"2009-10-24T13:06:44Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Felipe Contreras writes:\n\n> ...\n> Reworded the getting started section based on comments from Michael J Gruber,\n> Jonathan Nieder and Junio C Hamano.\n\nI'm surprised that you ignored comments from the original \nauthor of the document you are updating.\n\n Date: Tue, 13 Oct 2009 22:49:40 -0400\n Message-ID: <20091014024940.GB9700@fieldses.org>\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"125844","messageId":"94a0d4530910240708l7cb59b36s8d6ddebd4af48e7f@mail.gmail.com","threadId":"21344","inReplyTo":"20091024220644.6117@nanako3.lavabit.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T14:08:06Z","receivedAt":"2009-10-24T14:08:06Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi wrote:\n> Quoting Felipe Contreras writes:\n>\n>> ...\n>> Reworded the getting started section based on comments from Michael J Gruber,\n>> Jonathan Nieder and Junio C Hamano.\n>\n> I'm surprised that you ignored comments from the original\n> author of the document you are updating.\n\nI did not. His comment was that if we do this, it must be short, and\nit is. If it's not, then it would be more productive to suggest ways\nto trim it down.\n\n>  Date: Tue, 13 Oct 2009 22:49:40 -0400\n>  Message-ID: <20091014024940.GB9700@fieldses.org>\n\nI've no way of figuring out what is that. Most people use a direct\nlink to a mail archive.\n\n-- \nFelipe Contreras\n"},{"id":"125845","messageId":"20091024141445.GA2078@atjola.homenet","threadId":"21344","inReplyTo":"94a0d4530910240708l7cb59b36s8d6ddebd4af48e7f@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Björn Steinbrink","fromEmail":"b.steinbrink@gmx.de","sentAt":"2009-10-24T14:14:45Z","receivedAt":"2009-10-24T14:14:45Z","isPatch":true,"sender":{"key":"b.steinbrink@gmx.de","avatar":"https://avatars.githubusercontent.com/u/230962?v=4"},"body":"On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote:\n> On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi wrote:\n> >  Date: Tue, 13 Oct 2009 22:49:40 -0400\n> >  Message-ID: <20091014024940.GB9700@fieldses.org>\n> \n> I've no way of figuring out what is that. Most people use a direct\n> link to a mail archive.\n\nHaving the Message-ID is quite useful, so you can search your local mbox\nto find the right message. You can also use gmane's Message-ID search:\nhttp://mid.gmane.org/message_id_here\n\nSo: http://mid.gmane.org/20091014024940.GB9700@fieldses.org\n\nBjörn\n"},{"id":"125847","messageId":"94a0d4530910240722vd6839f0r49487a3a174fa179@mail.gmail.com","threadId":"21344","inReplyTo":"20091024141445.GA2078@atjola.homenet","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T14:22:16Z","receivedAt":"2009-10-24T14:22:16Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"2009/10/24 Björn Steinbrink :\n> On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote:\n>> On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi wrote:\n>> >  Date: Tue, 13 Oct 2009 22:49:40 -0400\n>> >  Message-ID: <20091014024940.GB9700@fieldses.org>\n>>\n>> I've no way of figuring out what is that. Most people use a direct\n>> link to a mail archive.\n>\n> Having the Message-ID is quite useful, so you can search your local mbox\n> to find the right message.\n\nI don't have a local mbox, and I suspect I'm not the only one.\n\n> You can also use gmane's Message-ID search:\n> http://mid.gmane.org/message_id_here\n\nThat's a nice trick, but then using the following link would serve\nexactly the same purpose, wouldn't it?\n\n> So: http://mid.gmane.org/20091014024940.GB9700@fieldses.org\n\n-- \nFelipe Contreras\n"},{"id":"125850","messageId":"7vy6n065os.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"1256377489-16719-1-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-24T17:51:47Z","receivedAt":"2009-10-24T17:51:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> Reworded the getting started section based on comments from Michael J Gruber,\n> Jonathan Nieder and Junio C Hamano.\n\nHmm, I thought JBF also had some input...\n"},{"id":"125851","messageId":"7vr5ss64e5.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"7vy6n065os.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-24T18:19:46Z","receivedAt":"2009-10-24T18:19:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Felipe Contreras writes:\n>\n>> Reworded the getting started section based on comments from Michael J Gruber,\n>> Jonathan Nieder and Junio C Hamano.\n>\n> Hmm, I thought JBF also had some input...\n\nAh, nevermind. Yes, he did have input, and I tend to agree with him, and\nmore importantly trust his judgement on the manual.\n\nI think a \"Getting started\" section that only covers \"git config\" looks\nway out of place in the beginning of this document.\n\nManuals by other people that teach \"here is how you would do a hello-world\nrepository\" would want to teach user.name before reaching that point, but\nbecause the user-manual is written in such a way that it first introduces\nconcepts to understand what is going on without changing anything, we do\nnot have much need user.name until it gets to \"Developing with git\"\nsection.\n\n\"Many people prefer to teach it this way\" does not justify \"everybody must\nteach it this way\" an iota, when teaching \"config user.name\" upfront will\nfit the flow of how they teach but does not fit the flow of how this\nmanual teaches [*1*].\n\nI'm inclined to to discard the first patch.\n\nThe point of the original text the second patch touches was to show how\nsimple the contents of the configuration file is and give the users that\nthere is nothing magic there. While I do not like the second patch as-is,\nbecause it destroys that nice property and treats the end users mindless\n\"cut-and-paste without thinking\" sheeples, I think that it is rather vague\nand unhelpful to the current target audience to say:\n\n ... The easiest way to do so is to make sure the following lines\n appear in a file named .gitconfig in your home directory:\n\nand the parts can use some improvement. For example, \"home directory\"\ndoes not hold true for people on platforms that lack the concept. Keeping\nthe current \"the following lines appear\", rewording \"in a file named\n.gitconfig in your home directory\" with \"in your per-user configuration\nfile\", keeping the display that shows how the config snippet should look\nlike, and using \"config --global -e\" might be a better approach.\n\n\n[Footnote]\n\n*1* Unless you are changing the flow of how this manual teaches at the\nsame time, that is. And no, I am not suggesting that we should start from\n\"let's do a hello-world repository from scratch\". I think the current\n\"start from read-only and then learn how to grow history later\" is one\nvalid way to teach.\n"},{"id":"125857","messageId":"94a0d4530910241316r3fc4136emd036d18aa45a4192@mail.gmail.com","threadId":"21344","inReplyTo":"7vr5ss64e5.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-24T20:16:51Z","receivedAt":"2009-10-24T20:16:51Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sat, Oct 24, 2009 at 9:19 PM, Junio C Hamano wrote:\n> Junio C Hamano writes:\n>\n>> Felipe Contreras writes:\n>>\n>>> Reworded the getting started section based on comments from Michael J Gruber,\n>>> Jonathan Nieder and Junio C Hamano.\n>>\n>> Hmm, I thought JBF also had some input...\n>\n> Ah, nevermind. Yes, he did have input, and I tend to agree with him, and\n> more importantly trust his judgement on the manual.\n\nJBF said this[1]:\nIf we have to do this, just keep it short....\n\nAnd I am trying to keep it short.\n\n> I think a \"Getting started\" section that only covers \"git config\" looks\n> way out of place in the beginning of this document.\n\nNow you are saying that the fact that it's short is a bad thing? That\ngoes against to what JBF said.\n\nAnd let's not forget your previous comments\n\n[2]: I think a \"getting started\" section near the beginning of the manual is a\ngood idea (and ll.40- is a very early part of the manual).\n\n[3]: I actually wish this section appeared a lot earlier in the document, but\nthat is a separate issue.\n\n> Manuals by other people that teach \"here is how you would do a hello-world\n> repository\" would want to teach user.name before reaching that point, but\n> because the user-manual is written in such a way that it first introduces\n> concepts to understand what is going on without changing anything, we do\n> not have much need user.name until it gets to \"Developing with git\"\n> section.\n>\n> \"Many people prefer to teach it this way\" does not justify \"everybody must\n> teach it this way\" an iota, when teaching \"config user.name\" upfront will\n> fit the flow of how they teach but does not fit the flow of how this\n> manual teaches [*1*].\n\nNobody argued that \"everybody must teach it this way\", the argument\nwas that most people find it easier, and considering the section is\nabout \"developing with git\" it is sensible to avoid burdening the\nreader with concepts that don't pertain to the objective at hand,\nwhich is getting them to configure their user.\n\nAnd let's not forget that the current text is broken for Windows users.\n\n> I'm inclined to to discard the first patch.\n\nAnd you decided to mention that after many people including you, have\nagreed that it's a good idea?\n\n> The point of the original text the second patch touches was to show how\n> simple the contents of the configuration file is and give the users that\n> there is nothing magic there.  While I do not like the second patch as-is,\n> because it destroys that nice property and treats the end users mindless\n> \"cut-and-paste without thinking\" sheeples,\n\nWhat's wrong with teaching one thing at a time? Configuring the user\nis something so essential, I don't think it makes sense to make the\ntask difficult on purpose. Some people might avoid doing it precisely\nbecause of that.\n\n> I think that it is rather vague\n> and unhelpful to the current target audience to say:\n>\n>    ...  The easiest way to do so is to make sure the following lines\n>    appear in a file named .gitconfig in your home directory:\n>\n> and the parts can use some improvement.  For example, \"home directory\"\n> does not hold true for people on platforms that lack the concept.  Keeping\n> the current \"the following lines appear\", rewording \"in a file named\n> .gitconfig in your home directory\" with \"in your per-user configuration\n> file\", keeping the display that shows how the config snippet should look\n> like, and using \"config --global -e\" might be a better approach.\n\nIf you read the results of the last git survey you'll see that the\narea that needs most improvement is the documentation. Also I still\nsee many people doing commits without configuring the user name and\nemail properly and so I've tried very hard to improve the user manual\nto make it easier for them to understand they must do that. In the\nprocess I've added the --edit option to 'git config' and the new\n\"getting started\" section, in order to address all the issues\nmentioned in previous threads and gone through several iterations of\nthese patches already.\n\nI'm starting to think that all the previous \"constructive\" feedback\nwas actually targeted to deter people from making any changes.\n\nI'm CC'ing people that have been involved in previous threads.\n\n> [Footnote]\n>\n> *1* Unless you are changing the flow of how this manual teaches at the\n> same time, that is.  And no, I am not suggesting that we should start from\n> \"let's do a hello-world repository from scratch\".  I think the current\n> \"start from read-only and then learn how to grow history later\" is one\n> valid way to teach.\n\nI also don't think the flow should be changed, that's why I didn't put\nthe user configuration on the \"getting started\" section. It goes into\nthe \"developing with git\" section.\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/130236\n[2] http://article.gmane.org/gmane.comp.version-control.git/115649\n[3] http://article.gmane.org/gmane.comp.version-control.git/106667\n\n-- \nFelipe Contreras\n"},{"id":"125866","messageId":"20091025002657.GB15242@fieldses.org","threadId":"21344","inReplyTo":"94a0d4530910241316r3fc4136emd036d18aa45a4192@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2009-10-25T00:26:57Z","receivedAt":"2009-10-25T00:26:57Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Oct 24, 2009 at 11:16:51PM +0300, Felipe Contreras wrote:\n> And let's not forget that the current text is broken for Windows users.\n\nJust out of curiosity: do you have a list of what would need to be done\nto make the manual work for windows users?\n\nI haven't used any Windows/DOS commandline since, um, 1980-something, so\nI'm a little clueless here.\n\n--b.\n"},{"id":"125867","messageId":"7vy6n02mrk.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"94a0d4530910241316r3fc4136emd036d18aa45a4192@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-25T03:08:47Z","receivedAt":"2009-10-25T03:08:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n>> I'm inclined to to discard the first patch.\n>\n> And you decided to mention that after many people including you, have\n> agreed that it's a good idea?\n\nThis line of argument is wrong and counterproductive. Of course, after\nreading what others said and thinking about it more myself, I can change\nmy mind based on their opinions. Otherwise there is no point in having\nany mailing list discussion.\n\nPeople propose changes, and two things can happen:\n\n (1) I and others may think it is not a good idea, clarifying argument may\n come from the original author and/or additional arguments defending\n the change may come from others. People who thought it was not a\n good idea may change their mind, and the patch gets accepted. git\n becomes better.\n\n If people cannot change their mind, it is useless to make supporting\n arguments to nudge them to reconsider.\n\n (2) I and others may think it is a good idea, a counterargument comes,\n and people who originally thought it was a good idea may change their\n mind, and the patch does not go in. git is saved from becoming\n worse.\n\n If people cannot change their mind, it is useless to make counter-\n arguments to nudge them to reconsider.\n\nYes, I originally thought a \"getting started\" section may be a good idea.\nThere is no need to point it out to me.\n\nBut after I saw that the original author said \"_if_ we have to do this,\nkeep it short\", the comment made me question my previous assumption one\nmore time: is it really a good idea to add \"getting started\", and is it a\ngood idea to cover the config command in that section?\n\nAfter re-reading the first thousand lines of the user manual, I realized\nthat the explanation was carefully laid out so that you do not have to be\ntaught \"git config\" in the beginning to be able to follow it. Now, after\napplying your latest patch, if we do not have to teach \"config\" there,\nwhat else is left in the section? --- Nothing.\n\nWhat conclusion do you expect me to reach after such a consideration,\nother than \"then let's not have it\"?\n\n> If you read the results of the last git survey you'll see that the\n> area that needs most improvement is the documentation.\n\nYes, I did read it, but what about it? You already know we both want to\nhave a good set of documentation.\n\nRemember that \"changing\" and \"improving\" is different; some changes may\nnot necessarily be improvements. \"It needs improving, so let's change it\"\nis not an argument. This isn't obviously limited to the documentation but\nalso applies to UI changes.\n\n> Also I still\n> see many people doing commits without configuring the user name and\n> email properly and so I've tried very hard to improve the user manual\n> to make it easier for them to understand they must do that.\n\nThe \"unconfigured user.name is wrong\" is the least of the problems for\npeople who start commiting without understanding the basic principles.\nPeople may ask \"how do I publish my changes\", \"how do I discard the\ncommit\" and \"how do I modify the commit two days ago\", and teaching them\nthings like \"reset HEAD^\" and \"rebase -i\", without making them aware of\nthe implications will do disservice to them in the long run. That kind of\nself-teaching is already done by people (and for doing so sometimes they\nhurt themselves) by diving into man pages of individual commands before\nunderstanding the distributedness and its implications, and my hope has\nalways been to keep the user-manual a document that teaches things in one\ncoherent and hopefully the most useful order.\n\nThe early part of the manual (the first thousand lines) does not talk\nabout making commits but lays out the groundwork for a good reason. And\nin order to follow the current structure of the manual, you do not need to\nbe taught \"config\" as the first thing.\n\nIt is a totally different story if we are going to rewrite the manual in\nsuch a way that we start from \"hello world\". I am not necessarily saying\nit is a bad way to teach [*1*].\n\nBut the current \"starting from a sightseer, while learning the basic\nconcepts like reachability and stuff, and then learn to build on top of\nothers' work\" structure would also be a valid way to teach, and in that\npresentation order, I do not think teaching \"config\" sits well at the\nbeginning.\n\n\n[Footnote]\n\n*1* Indeed, the book I did recently does just that, starting from a solo\nuser who develops on his own from scratch, and then uses another\nrepository as a back up repository, and then works on two different\nmachines with a repository each, still working solo no the same project.\nAfter that working with other users collaboratively comes. If you teach in\nthat order, you have to cover config before you cover commit, which pretty\nmuch means config is mentioned at the very beginning.\n"},{"id":"125876","messageId":"94a0d4530910250243k4cbc3c18l5e018a05e5afdb2d@mail.gmail.com","threadId":"21344","inReplyTo":"7vy6n02mrk.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-25T09:43:08Z","receivedAt":"2009-10-25T09:43:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, Oct 25, 2009 at 6:08 AM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>>> I'm inclined to to discard the first patch.\n>>\n>> And you decided to mention that after many people including you, have\n>> agreed that it's a good idea?\n>\n> This line of argument is wrong and counterproductive.  Of course, after\n> reading what others said and thinking about it more myself, I can change\n> my mind based on their opinions.  Otherwise there is no point in having\n> any mailing list discussion.\n>\n> People propose changes, and two things can happen:\n>\n>  (1) I and others may think it is not a good idea, clarifying argument may\n>     come from the original author and/or additional arguments defending\n>     the change may come from others.  People who thought it was not a\n>     good idea may change their mind, and the patch gets accepted.  git\n>     becomes better.\n>\n>     If people cannot change their mind, it is useless to make supporting\n>     arguments to nudge them to reconsider.\n>\n>  (2) I and others may think it is a good idea, a counterargument comes,\n>     and people who originally thought it was a good idea may change their\n>     mind, and the patch does not go in.  git is saved from becoming\n>     worse.\n>\n>     If people cannot change their mind, it is useless to make counter-\n>     arguments to nudge them to reconsider.\n\nYes, people can change their mind, but if they do so, they must tell\nit as it is, and you didn't:\n I think a \"Getting started\" section that only covers \"git config\" looks\n way out of place in the beginning of this document.\n\nIf you would have said it properly \"I've changed my mind\" there's an\nobvious question that arises: Why? What made you change your mind. You\ndidn't say that either.\n\n> Yes, I originally thought a \"getting started\" section may be a good idea.\n> There is no need to point it out to me.\n\nOne never knows =/\n\n> But after I saw that the original author said \"_if_ we have to do this,\n> keep it short\", the comment made me question my previous assumption one\n> more time: is it really a good idea to add \"getting started\", and is it a\n> good idea to cover the config command in that section?\n>\n> After re-reading the first thousand lines of the user manual, I realized\n> that the explanation was carefully laid out so that you do not have to be\n> taught \"git config\" in the beginning to be able to follow it.  Now, after\n> applying your latest patch, if we do not have to teach \"config\" there,\n> what else is left in the section? --- Nothing.\n>\n> What conclusion do you expect me to reach after such a consideration,\n> other than \"then let's not have it\"?\n\nAha! That's the explanation I was looking for, and what I think you\nshould have said in the first place. Now we can do some productive\ndiscussion.\n\nI disagree. I think it's awfully useful to have color.ui = auto\nconfigured before reading the multitude of 'git branch', 'git show',\nand 'git diff' commands that are presented on first two sections. So\nuseful, in fact, that I think it should be enabled by default.\n\nSupposing that color.ui is 'auto' by default, then yeah, I don't see\nthe point of such a \"git config\" section so early in the document, but\nit must be explained somewhere.\n\n>> If you read the results of the last git survey you'll see that the\n>> area that needs most improvement is the documentation.\n>\n> Yes, I did read it, but what about it?  You already know we both want to\n> have a good set of documentation.\n>\n> Remember that \"changing\" and \"improving\" is different; some changes may\n> not necessarily be improvements.  \"It needs improving, so let's change it\"\n> is not an argument.  This isn't obviously limited to the documentation but\n> also applies to UI changes.\n\nNo, but \"improving\" needs \"changing\", and the discussion I see is\nbiased towards \"not changing\".\n\n>> Also I still\n>> see many people doing commits without configuring the user name and\n>> email properly and so I've tried very hard to improve the user manual\n>> to make it easier for them to understand they must do that.\n>\n> The \"unconfigured user.name is wrong\" is the least of the problems for\n> people who start commiting without understanding the basic principles.\n> People may ask \"how do I publish my changes\", \"how do I discard the\n> commit\" and \"how do I modify the commit two days ago\", and teaching them\n> things like \"reset HEAD^\" and \"rebase -i\", without making them aware of\n> the implications will do disservice to them in the long run.  That kind of\n> self-teaching is already done by people (and for doing so sometimes they\n> hurt themselves) by diving into man pages of individual commands before\n> understanding the distributedness and its implications, and my hope has\n> always been to keep the user-manual a document that teaches things in one\n> coherent and hopefully the most useful order.\n\nI don't think the user manual is achieving that purpose. I don't know\nif it's the user manual's fault, or git's UI. Both areas need a lot of\nimprovement (as the git user survey suggests), and I've tried to\nimprove both with a lot resistance in both. So I'm not very hopeful\nanymore.\n\n> The early part of the manual (the first thousand lines) does not talk\n> about making commits but lays out the groundwork for a good reason.  And\n> in order to follow the current structure of the manual, you do not need to\n> be taught \"config\" as the first thing.\n>\n> It is a totally different story if we are going to rewrite the manual in\n> such a way that we start from \"hello world\".  I am not necessarily saying\n> it is a bad way to teach [*1*].\n>\n> But the current \"starting from a sightseer, while learning the basic\n> concepts like reachability and stuff, and then learn to build on top of\n> others' work\" structure would also be a valid way to teach, and in that\n> presentation order, I do not think teaching \"config\" sits well at the\n> beginning.\n\nIMO the vast majority of git users will use it to just fetch a\nrepository, and browse through it, and that's because most people are\nnot developers. Even developers most probably will start that way, and\nonly start committing after a while.\n\nHowever, I haven't met any proficient git user that got to that point\nby reading the user manual, so I think it must be completely\nre-thought. Judging from the luck I've had pushing even the simplest\nchanges I don't think it will improve much more, unfortunately.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"125877","messageId":"20091025111438.GA11252@progeny.tock","threadId":"21344","inReplyTo":"94a0d4530910250243k4cbc3c18l5e018a05e5afdb2d@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-25T11:14:38Z","receivedAt":"2009-10-25T11:14:38Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Felipe,\n\nFelipe Contreras wrote:\n\n> I disagree. I think it's awfully useful to have color.ui = auto\n> configured before reading the multitude of 'git branch', 'git show',\n> and 'git diff' commands that are presented on first two sections. So\n> useful, in fact, that I think it should be enabled by default.\n\nThis is why I think you had a good idea here. When a program doesn’t\nbehave as I would like, it can be very comforting to know where its\ndotfile is and be able to edit it (I’m not sure how I learn this for\nmost programs). And it is much easier to parse git output without\nreading it all when color is turned on, so that is a setting I imagine\ncould be useful to people.\n\nOn the other hand, it is far more pleasant to use a program that\ndoesn’t need configuration at all. And as I mentioned before, it is\nbest to avoid wasted time at the beginning of the manual.\n\n> Supposing that color.ui is 'auto' by default,\n\nShould it be? I think it would not be too hard to detect a color\nterminal by checking $TERM. Are many people bothered by color? Do we\nneed some way to make it more obvious how to turn color _off_?\n\n> No, but \"improving\" needs \"changing\", and the discussion I see is\n> biased towards \"not changing\".\n[...]\n> I don't think the user manual is achieving that purpose. I don't know\n> if it's the user manual's fault, or git's UI. Both areas need a lot of\n> improvement (as the git user survey suggests), and I've tried to\n> improve both with a lot resistance in both. So I'm not very hopeful\n> anymore.\n\nI hope you have not misunderstood. I cannot speak for everyone else\nhere, but I know I am happier when (1) fixes match problems to be\nsolved in a documented way and (2) fixes do not unnecessarily break\nunrelated habits. One way to bring this about is to justify each\nchange by explaining what real problem it will solve and how it avoids\ncollateral damage. Without that justification, a change is indeed\ndangerous and might be worth resisting until it gets clarified. But\nthis is not meant to prevent fixes from occuring at all.\n\nCould you list some UI patches that were overlooked or not properly\naddressed? Maybe people just forgot about them or were waiting for an\nupdated version, or maybe the problems some solve weren’t articulated\nclearly yet. I would be glad to help out in any way I can.\n\n> However, I haven't met any proficient git user that got to that point\n> by reading the user manual, so I think it must be completely\n> re-thought.\n\nI have met one. (Well, he read the git tutorial and learned by using\ngit, too.) I think the user manual’s pretty well written, though it\ncertainly has its gaps and rough spots.\n\n> Judging from the luck I've had pushing even the simplest\n> changes I don't think it will improve much more, unfortunately.\n\nEven the simplest changes can be hard. But I hope they do not amount\nto nothing. I hope at the very least the git-config manual page will\nimprove...\n\nThank you for working on this. I hope you succeed in improving git’s\nusability, one way or another.\n\nRegards,\nJonathan\n"},{"id":"127393","messageId":"94a0d4530911111515q643e263bn3adc6b47cd968d3d@mail.gmail.com","threadId":"21344","inReplyTo":"20091025111438.GA11252@progeny.tock","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-11T23:15:11Z","receivedAt":"2009-11-11T23:15:11Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder wrote:\n> Felipe Contreras wrote:\n>> Supposing that color.ui is 'auto' by default,\n>\n> Should it be?  I think it would not be too hard to detect a color\n> terminal by checking $TERM.  Are many people bothered by color?  Do we\n> need some way to make it more obvious how to turn color _off_?\n\nI think it should be.\n\n>> No, but \"improving\" needs \"changing\", and the discussion I see is\n>> biased towards \"not changing\".\n> [...]\n>> I don't think the user manual is achieving that purpose. I don't know\n>> if it's the user manual's fault, or git's UI. Both areas need a lot of\n>> improvement (as the git user survey suggests), and I've tried to\n>> improve both with a lot resistance in both. So I'm not very hopeful\n>> anymore.\n>\n> I hope you have not misunderstood.  I cannot speak for everyone else\n> here, but I know I am happier when (1) fixes match problems to be\n> solved in a documented way and (2) fixes do not unnecessarily break\n> unrelated habits.  One way to bring this about is to justify each\n> change by explaining what real problem it will solve and how it avoids\n> collateral damage.  Without that justification, a change is indeed\n> dangerous and might be worth resisting until it gets clarified.  But\n> this is not meant to prevent fixes from occuring at all.\n\nWell. I've sent many patches, and gone through several iterations.\nAfter fixing all outstanding issues, addressing all the comments, and\ngetting several \"I like this\" votes, Junio suddenly decides he doesn't\nlike the initial changes at all and doesn't provide any way forward.\n\nI don't see how that's an environment that fosters changes.\n\n> Could you list some UI patches that were overlooked or not properly\n> addressed?  Maybe people just forgot about them or were waiting for an\n> updated version, or maybe the problems some solve weren’t articulated\n> clearly yet.  I would be glad to help out in any way I can.\n\nFor example there have been many attempts to bring the 'git stage' to\nforeground of the UI; right now it's kind of hidden and many people\ndon't even realize it's there. Even simplistic attempts as\nstandardizing --index, --cache and so on into --stage have failed\nmiserably.\n\nAgain, there doesn't seem to be a path forward. Perhaps the git's\nstage will remain an obscure feature of git forever. (all the input\nfrom git user's survey points out that people are not really using it)\n\n>> Judging from the luck I've had pushing even the simplest\n>> changes I don't think it will improve much more, unfortunately.\n>\n> Even the simplest changes can be hard.  But I hope they do not amount\n> to nothing.  I hope at the very least the git-config manual page will\n> improve...\n\nWhat I mean is: if the simplest changes are *impossible*, then there's\nbarely any hope of progress.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"127439","messageId":"4AFBF18E.7070906@drmicha.warpmail.net","threadId":"21344","inReplyTo":"94a0d4530911111515q643e263bn3adc6b47cd968d3d@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-11-12T11:29:18Z","receivedAt":"2009-11-12T11:29:18Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 12.11.2009 00:15:\n> On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder wrote:\n>> Felipe Contreras wrote:\n>>> Supposing that color.ui is 'auto' by default,\n>>\n>> Should it be? I think it would not be too hard to detect a color\n>> terminal by checking $TERM. Are many people bothered by color? Do we\n>> need some way to make it more obvious how to turn color _off_?\n> \n> I think it should be.\n\nBack then (before my involvement with git) the result of the discussion\nwas something like: \"Since some of us are way more opposed to the use of\ncolors than others are in favor...\" This does not sound overly democratic.\n\nFeel free to bring this issue on for a change in Git 1.7.0. It would be\ngood to research any possible incompatibilities this would imply (other\nthan the looks of the output),\n\n>>> No, but \"improving\" needs \"changing\", and the discussion I see is\n>>> biased towards \"not changing\".\n>> [...]\n>>> I don't think the user manual is achieving that purpose. I don't know\n>>> if it's the user manual's fault, or git's UI. Both areas need a lot of\n>>> improvement (as the git user survey suggests), and I've tried to\n>>> improve both with a lot resistance in both. So I'm not very hopeful\n>>> anymore.\n>>\n>> I hope you have not misunderstood. I cannot speak for everyone else\n>> here, but I know I am happier when (1) fixes match problems to be\n>> solved in a documented way and (2) fixes do not unnecessarily break\n>> unrelated habits. One way to bring this about is to justify each\n>> change by explaining what real problem it will solve and how it avoids\n>> collateral damage. Without that justification, a change is indeed\n>> dangerous and might be worth resisting until it gets clarified. But\n>> this is not meant to prevent fixes from occuring at all.\n> \n> Well. I've sent many patches, and gone through several iterations.\n> After fixing all outstanding issues, addressing all the comments, and\n> getting several \"I like this\" votes, Junio suddenly decides he doesn't\n> like the initial changes at all and doesn't provide any way forward.\n> \n> I don't see how that's an environment that fosters changes.\n\nThe process can be frustrating at times. Many patches go through many\nrounds. I've had occasions where I got frustrated and gave up, as well\nas those where I learned a lot and the actual result was much better\nthan it would have been without thorough discussions. It's this process\nwhich tries to ensure that the project is moving forward most of the\ntime, rather than sporadically back and forth; moving forward maybe a\nbit slower, but still at an impressive overall rate.\n\nRegarding this specific patch series: I took part in the initial\ndiscussion, and got frustrated by the original poster's seemingly\nunwillingness to accept advice, so I left. I'm not drawing any general\nconclusions, and please don't take this as an ad hominem argument.\nSometimes it's simply a matter of mismatching participants.\n\nIt's just my impression that many people retreat from a discussion\nbecause they feel it's getting unproductive (from their particular point\nof view), maybe hoping the thread will die out sooner or later. Once it\nlooks as if something they object to could be included they come back\nwith counter arguments. This makes the discussion seemingly go back and\nforth, but is a natural sociological effect.\n\n>> Could you list some UI patches that were overlooked or not properly\n>> addressed? Maybe people just forgot about them or were waiting for an\n>> updated version, or maybe the problems some solve weren’t articulated\n>> clearly yet. I would be glad to help out in any way I can.\n> \n> For example there have been many attempts to bring the 'git stage' to\n> foreground of the UI; right now it's kind of hidden and many people\n> don't even realize it's there. Even simplistic attempts as\n> standardizing --index, --cache and so on into --stage have failed\n> miserably.\n> \n> Again, there doesn't seem to be a path forward. Perhaps the git's\n> stage will remain an obscure feature of git forever. (all the input\n> from git user's survey points out that people are not really using it)\n\nI didn't read that out of the survey. On the other hand, the last survey\npretty impressively showed where it had been publicized most\nprominently. One should keep that in mind when interpreting the results.\n\nIf you care to go back to that discussion you see that there is good\nreason for having both --cached and --index. They are different. \"git\nhelp cli\" explains this nicely.\n\n\"To stage\" has been introduced to describe what \"git add\" does to people\nwho hard wire \"add\" to the meaning it has in other VCSes. In fact, this\nwould be unnecessary if the concept of Git as a *content* tracker could\nbe transmitted more successfully. Git cares about content only, so what\ncould \"git add\" possibly mean?\n\n\"git stage\" is a failed follow up ui experiment.\n\nIn this regard, I think the problem is that there are really two kinds\nof people in terms of learning style:\n\n- Some prefer recipes, similarities with previously known recipes. \"How\ndo I...?\" And then try do understand \"How does (G)it...?\" from that.\n\n- Some want to understand concepts first: \"How does (G)it...?\" And then\nfigure out how to use (G)it to do what they want.\n\nI'd guess most developers and a large fraction of the \"technical crowd\"\nbelong in the second camp.\n\nI still think we should both\n\n- try and teach concepts early, emphasize that Git is different\n(content, index, branch - that's it)\n- make Git behave in \"expected ways\", making it easy for the (willing)\nbeginner) without compromising its usefulness as a power tool.\n\nI better stop before I digress even more from the original topic :)\n\nMichael\n"},{"id":"127469","messageId":"94a0d4530911121204o59f94bbcv84bd11b8c79b6009@mail.gmail.com","threadId":"21344","inReplyTo":"4AFBF18E.7070906@drmicha.warpmail.net","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-12T20:04:23Z","receivedAt":"2009-11-12T20:04:23Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Thu, Nov 12, 2009 at 1:29 PM, Michael J Gruber\n wrote:\n> Feel free to bring this issue on for a change in Git 1.7.0. It would be\n> good to research any possible incompatibilities this would imply (other\n> than the looks of the output),\n\nIsn't that what we are doing just now?\n\n> The process can be frustrating at times. Many patches go through many\n> rounds. I've had occasions where I got frustrated and gave up, as well\n> as those where I learned a lot and the actual result was much better\n> than it would have been without thorough discussions. It's this process\n> which tries to ensure that the project is moving forward most of the\n> time, rather than sporadically back and forth; moving forward maybe a\n> bit slower, but still at an impressive overall rate.\n\nExcept in this case there is no path forward. If there is, I would\nlike to hear it.\n\n> Regarding this specific patch series: I took part in the initial\n> discussion, and got frustrated by the original poster's seemingly\n> unwillingness to accept advice, so I left. I'm not drawing any general\n> conclusions, and please don't take this as an ad hominem argument.\n> Sometimes it's simply a matter of mismatching participants.\n\nWhat are you talking about? All your comments were addressed in\nsubsequent patches, as the commit message of the patch in this thread\npoints out.\n\nMoreover, in the paragraph before you argued that these thorough\ndiscussions are actually a good thing. Or are patch committers not\nallowed to discuss?\n\n> I didn't read that out of the survey. On the other hand, the last survey\n> pretty impressively showed where it had been publicized most\n> prominently. One should keep that in mind when interpreting the results.\n\nSo? What are the surveys supposed to be for, if not to use the results?\n\n> If you care to go back to that discussion you see that there is good\n> reason for having both --cached and --index. They are different. \"git\n> help cli\" explains this nicely.\n\n\"good\" is a very subjective term; I don't think \"they are different\"\nis a good reason. By that logic --only-index and\n--index-and-working-dir serve the same purpose, just like --gogo and\n--dance.\n\nBut there's no point in discussing this until people accept there is a\nproblem, and there seems to be unwillingness to accept that very few\npeople use the stage properly.\n\n> \"To stage\" has been introduced to describe what \"git add\" does to people\n> who hard wire \"add\" to the meaning it has in other VCSes. In fact, this\n> would be unnecessary if the concept of Git as a *content* tracker could\n> be transmitted more successfully. Git cares about content only, so what\n> could \"git add\" possibly mean?\n\nusage: git add [options] [--] ...\n\nI don't see any mention of this \"blob\" mythical creature. In the vast\nmajority of the minds of git users, 'git add' adds files to the\nrepository, just like any other VCS.\n\nProof of that is that only 23% of the people use \"git add -i / -p\" and\n15% \"git add -u / -A\" often.\n\n> \"git stage\" is a failed follow up ui experiment.\n\nI agree with that. But assuming because one UI experiment failed, all\nother \"stage\" proposals are doomed.\n\n> In this regard, I think the problem is that there are really two kinds\n> of people in terms of learning style:\n>\n> - Some prefer recipes, similarities with previously known recipes. \"How\n> do I...?\" And then try do understand \"How does (G)it...?\" from that.\n>\n> - Some want to understand concepts first: \"How does (G)it...?\" And then\n> figure out how to use (G)it to do what they want.\n>\n> I'd guess most developers and a large fraction of the \"technical crowd\"\n> belong in the second camp.\n\nI actually belong to the two groups. When I started to use git I\nlearned it through recipes and grew fond of it, but didn't really know\nwhat was really happening even thought I used it for years. It wasn't\nuntil a colleague recommended me to read \"Git from the bottom up\",\nthen I really started to understand git and realized I didn't know\nsquat. Sure, I heard concepts such as \"feature branches\", \"rebase\" and\n\"stage interactive\", and I had in my to-do list to learn them, but\nthat was it.\n\nI'm pretty sure the vast majority of users are in the darkness just as I was.\n\n> I still think we should both\n\nWhat?\n\n> - try and teach concepts early, emphasize that Git is different\n> (content, index, branch - that's it)\n\nWell, that's the first failure right there. If your objective is to\nconfuse people, then sure, call it \"index\", otherwise choose a name\nthat corresponds with it's purpose: stage.\n\n> - make Git behave in \"expected ways\", making it easy for the (willing)\n> beginner) without compromising its usefulness as a power tool.\n\nSure, but if the UI was more friendly people would learn to use the\nadvanced features through it's use. Currently there are no ropes to do\nthat. You have to read a book or something.\n\n-- \nFelipe Contreras\n"},{"id":"127518","messageId":"20091114060600.6117@nanako3.lavabit.com","threadId":"21344","inReplyTo":"4AFBF18E.7070906@drmicha.warpmail.net","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-13T21:06:00Z","receivedAt":"2009-11-13T21:06:00Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Michael J Gruber \n\n> Regarding this specific patch series: I took part in the initial\n> discussion, and got frustrated by the original poster's seemingly\n> unwillingness to accept advice, so I left. I'm not drawing any general\n> conclusions, and please don't take this as an ad hominem argument.\n> Sometimes it's simply a matter of mismatching participants.\n\nI didn't get myself involved in the follow-up discussion exactly \nfor the same reason.\n\n> If you care to go back to that discussion you see that there is good\n> reason for having both --cached and --index. They are different. \"git\n> help cli\" explains this nicely.\n\nThe need to support both options in the same command (eg. apply) means \nthat anybody who says \"I don't like 'index' nor 'cache'; why don't we \nchange them all to 'stage'\" doesn't understand the issue.\n\nBut that doesn't mean \"apply --cached\" vs \"apply --index\" is the best \nway to let the users specify which operation is requested. I don't \nthink Felipe seriously wants to change them to --gogo vs --dance, but \nif he made a more constructive proposal, instead of making such a \ncomment whose intended effect is only to annoy people, we may see \nan improved UI at the end. Proposing \"--index-only\" vs \"--index-too\" \nor even \"--stage-only\" vs \"--stage-too\" would have helped him appear \nto be more serious and constructive and I think your expression \n\"mismatching participants\" was a great way to say this.\n\nThere was a similar discussion about \"diff --cached\". The command \ncompares two things and the current syntax relies on counting the \nnumber of treeish on the command line to specify what these two things \nare, and sometimes people are confused which way the comparison occurs.\n\n * If you have two treeish, it compares the two treeish. Specifically, \n it shows the change to make one treeish into the other treeish.\n\n * If you have one treeish, it compares the treeish with working tree \n or the index (it shows the change to make the treeish into working \n tree or the index). You need --cached to choose the \"index\", and\n this can safely be aliased to --staged.\n\n * If you have zero treeish, it compares the index with working tree \n (it shows the change to make the index into working tree).\n\nBut it is also possible to have an alternate syntax to explicitly say\nwhat you are comparing with what. Perhaps these may make it unnecessary\nto remember which way the comparison occurs:\n\n git diff --tree-vs-staged HEAD\n\tsame as \"git diff --cached HEAD\"\n git diff --staged-vs-tree HEAD\n\tsame as \"git diff -R --cached HEAD\"\n\n git diff --staged-vs-working\n\tsame as \"git diff\"\n git diff --working-vs-staged\n\tsame as \"git diff -R\"\n\n git diff --tree-vs-working HEAD\n\tsame as \"git diff HEAD\"\n git diff --working-vs-tree HEAD\n\tsame as \"git diff -R HEAD\"\n\nIf people like this as a concept we can introduce shorter way to spell \nthem, eg. \"git diff --ts HEAD\", etc.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"127706","messageId":"94a0d4530911161452xe82858el322a1985341bf13c@mail.gmail.com","threadId":"21344","inReplyTo":"20091114060600.6117@nanako3.lavabit.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-16T22:52:37Z","receivedAt":"2009-11-16T22:52:37Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi wrote:\n> Quoting Michael J Gruber \n>> If you care to go back to that discussion you see that there is good\n>> reason for having both --cached and --index. They are different. \"git\n>> help cli\" explains this nicely.\n>\n> The need to support both options in the same command (eg. apply) means\n> that anybody who says \"I don't like 'index' nor 'cache'; why don't we\n> change them all to 'stage'\" doesn't understand the issue.\n>\n> But that doesn't mean \"apply --cached\" vs \"apply --index\" is the best\n> way to let the users specify which operation is requested. I don't\n> think Felipe seriously wants to change them to --gogo vs --dance, but\n> if he made a more constructive proposal, instead of making such a\n> comment whose intended effect is only to annoy people, we may see\n> an improved UI at the end.  Proposing \"--index-only\" vs \"--index-too\"\n> or even \"--stage-only\" vs \"--stage-too\" would have helped him appear\n> to be more serious and constructive and I think your expression\n> \"mismatching participants\" was a great way to say this.\n\nRight, your explanation is more clear: the fact that we need both\ndoesn't mean we cannot use the term \"stage\". As to \"constructive\nproposal\" I deliberately tried to avoid them in case somebody tried to\ndisregard it as bike-shedding, and move on. What I'm trying to do is\nbring up the issue that the stage is not user friendly.\n\n> There was a similar discussion about \"diff --cached\". The command\n> compares two things and the current syntax relies on counting the\n> number of treeish on the command line to specify what these two things\n> are, and sometimes people are confused which way the comparison occurs.\n>\n>  * If you have two treeish, it compares the two treeish. Specifically,\n>   it shows the change to make one treeish into the other treeish.\n>\n>  * If you have one treeish, it compares the treeish with working tree\n>   or the index (it shows the change to make the treeish into working\n>   tree or the index). You need --cached to choose the \"index\", and\n>   this can safely be aliased to --staged.\n>\n>  * If you have zero treeish, it compares the index with working tree\n>   (it shows the change to make the index into working tree).\n>\n> But it is also possible to have an alternate syntax to explicitly say\n> what you are comparing with what. Perhaps these may make it unnecessary\n> to remember which way the comparison occurs:\n>\n>  git diff --tree-vs-staged HEAD\n>        same as \"git diff --cached HEAD\"\n>  git diff --staged-vs-tree HEAD\n>        same as \"git diff -R --cached HEAD\"\n>\n>  git diff --staged-vs-working\n>        same as \"git diff\"\n>  git diff --working-vs-staged\n>        same as \"git diff -R\"\n>\n>  git diff --tree-vs-working HEAD\n>        same as \"git diff HEAD\"\n>  git diff --working-vs-tree HEAD\n>        same as \"git diff -R HEAD\"\n\nI like David Kågedal's suggestion more:\nhttp://kerneltrap.org/mailarchive/git/2008/10/29/3857134\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"127760","messageId":"20091117210625.6117@nanako3.lavabit.com","threadId":"21344","inReplyTo":"94a0d4530911161452xe82858el322a1985341bf13c@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-17T12:06:25Z","receivedAt":"2009-11-17T12:06:25Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Felipe Contreras \n\n> On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi wrote:\n>> ... I don't\n>> think Felipe seriously wants to change them to --gogo vs --dance, but\n>> if he made a more constructive proposal, instead of making such a\n>> comment whose intended effect is only to annoy people, we may see\n>> an improved UI at the end. Proposing \"--index-only\" vs \"--index-too\"\n>> or even \"--stage-only\" vs \"--stage-too\" would have helped him appear\n>> to be more serious and constructive and I think your expression\n>> \"mismatching participants\" was a great way to say this.\n>\n> Right, your explanation is more clear:\n\nYou have a funny way of saying \"I'm sorry, I wasn't constructive, \nand my attitude repelled many participants from the discussion\".\n\n> the fact that we need both\n> doesn't mean we cannot use the term \"stage\". As to \"constructive\n> proposal\" I deliberately tried to avoid them in case somebody tried to\n> disregard it as bike-shedding, and move on.\n\nIf the only constructive proposal you could make is to replace \nwords used in two operations without clarifying concepts any \nbetter to newbies, then what you are doing is bike-shedding. \nI don't think trying to hide that by not making any proposal \nchanges that.\n\n> What I'm trying to do is\n> bring up the issue that the stage is not user friendly.\n\nI thought you were the one who wanted to use \"stage\" everywhere?\n\nFor what it's worth, \"stage\" isn't very user friendly to me; \nmaybe it is because I'm not a native English speaker. I'm not \nsaying that when I hear \"index\" or \"cached\" I'll understand \nwhat they mean even if I didn't have any prior knowledge of \ngit, but I am saying \"stage\" isn't any better than these two \nwords in that respect. Of course the user needs to understand \nwhat it is and how it is used, no matter what word you use.\n\nI think a proposal to replace the word \"index\" with \"stage\" \nwill sound nothing but bike-shedding to anybody, especially \nafter getting familiar with \"index\" and seeing it taught on \nmany web pages and books.\n\n> I like David Kågedal's suggestion more:\n> http://kerneltrap.org/mailarchive/git/2008/10/29/3857134\n\nFor people who like a usable threaded interface to read \nthe message in context here is its URL.\n\nhttp://thread.gmane.org/gmane.comp.version-control.git/99332/focus=99401\n\nYes, I had David's proposal in mind when I wrote my response. \nEven though the fundamental idea is the same, I used --X-vs-Y \noption to avoid the problems David's proposal has in a slightly \nnicer way.\n\nDavid's proposal introduced two magic tokens STAGE and WORKTREE.\n\n git diff STAGE WORKTREE (like \"git diff\" today)\n git diff HEAD WORKTREE (like \"git diff HEAD\" today)\n git diff WORKTREE HEAD (like \"git diff -R HEAD\" today)\n git diff HEAD STAGE (like \"git diff --cached\" today)\n git diff commit STAGE (like \"git diff --cached commit\" today)\n\nThis looks nice on surface, but I think the apparent niceness \nis shallow. If of course has a small problem of introducing an \nobvious backward incompatibility. You can't use a branch whose \nname is STAGE anymore, but a deeper problem is that these two \nmagic tokens pretend to be refs. But they do so only to the diff \ncommand. I don't see how you can make them sanely be usable to \nother commands like \"git log v1.0.0..WORKTREE\".\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"127766","messageId":"20091117172815.GH31767@fieldses.org","threadId":"21344","inReplyTo":"20091117210625.6117@nanako3.lavabit.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2009-11-17T17:28:15Z","receivedAt":"2009-11-17T17:28:15Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote:\n> David's proposal introduced two magic tokens STAGE and WORKTREE.\n> \n> git diff STAGE WORKTREE (like \"git diff\" today)\n> git diff HEAD WORKTREE (like \"git diff HEAD\" today)\n> git diff WORKTREE HEAD (like \"git diff -R HEAD\" today)\n> git diff HEAD STAGE (like \"git diff --cached\" today)\n> git diff commit STAGE (like \"git diff --cached commit\" today)\n> \n> This looks nice on surface, but I think the apparent niceness \n> is shallow. If of course has a small problem of introducing an \n> obvious backward incompatibility. You can't use a branch whose \n> name is STAGE anymore, but a deeper problem is that these two \n> magic tokens pretend to be refs. But they do so only to the diff \n> command. I don't see how you can make them sanely be usable to \n> other commands like \"git log v1.0.0..WORKTREE\".\n\nDoesn't appear that refs have to point to commits; e.g., on the linux\nproject:\n\n\tgit log v2.6.11-tree..v2.6.32-rc7\n\terror: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a\n\tcommit\n\tfatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7\n\n\nYou might be able to add some extra syntax to prevent conflicts with\nbranch names. Uh, :STAGE, :WORKTREE ?? But I think that conflicts with\nsomething else. And the \"magic tokens\" get a little uglier and harder\nto remember. Bah.\n\n--b.\n"},{"id":"127767","messageId":"vpqpr7havh4.fsf@bauges.imag.fr","threadId":"21344","inReplyTo":"20091117210625.6117@nanako3.lavabit.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2009-11-17T17:53:43Z","receivedAt":"2009-11-17T17:53:43Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Nanako Shiraishi writes:\n\n> I don't see how you can make them sanely be usable to \n> other commands like \"git log v1.0.0..WORKTREE\".\n\nSee what gitk is showing you when you have uncommited changes. You\nhave some kind of \"pseudo-commits\" on top of your history for the\nindex and the worktree. \"git log v1.0.0..WORKTREE\" could very well be\na text-mode version of what's already in gitk.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"127771","messageId":"7vocn1dn5d.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"20091117172815.GH31767@fieldses.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-17T18:25:18Z","receivedAt":"2009-11-17T18:25:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"J. Bruce Fields\" writes:\n\n> On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote:\n>> David's proposal introduced two magic tokens STAGE and WORKTREE.\n>> \n>> git diff STAGE WORKTREE (like \"git diff\" today)\n>> git diff HEAD WORKTREE (like \"git diff HEAD\" today)\n>> git diff WORKTREE HEAD (like \"git diff -R HEAD\" today)\n>> git diff HEAD STAGE (like \"git diff --cached\" today)\n>> git diff commit STAGE (like \"git diff --cached commit\" today)\n>> \n>> This looks nice on surface, but I think the apparent niceness \n>> is shallow. If of course has a small problem of introducing an \n>> obvious backward incompatibility. You can't use a branch whose \n>> name is STAGE anymore, but a deeper problem is that these two \n>> magic tokens pretend to be refs. But they do so only to the diff \n>> command. I don't see how you can make them sanely be usable to \n>> other commands like \"git log v1.0.0..WORKTREE\".\n>\n> Doesn't appear that refs have to point to commits; e.g., on the linux\n> project:\n>\n> \tgit log v2.6.11-tree..v2.6.32-rc7\n> \terror: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a\n> \tcommit\n> \tfatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7\n\nTrue. A ref can even point to a blob.\n\nI think \"diff\" always takes two (pseudo-)tree-ish in David's world, and\nyou should be able to use these magic topens anywhere that expects a\ntree-ish. For example:\n\n $ git checkout STAGE Makefile\n\nwould be a way to say \"please check out the version of Makefile in the\nstaging area\". And\n\n $ git archive WORKTREE\n $ git archive STAGE\n\nwould be a version of tar that is index-aware.\n\nBut we do not have to support commit-ish operations, such as \"git log\".\n\nIt is a different story if these pseudo-refs that denote tree-ish are\nuseful outside the context of \"diff\". I do not think of many commands\nthat take arbitrary tree-ish other than the ones I mentioned above. Even\nthough they take arbitrary tree-ish, people almost always use commit-ish\nwith them.\n\nWhich points to another issue with the approach.\n\nThe original intention of these magic tokens are to make things easier,\nbut they actually may make things _harder_ to teach, because you have to\nexplain why \"git log WORKTREE\" does not work but \"git archive WORKTREE\"\ndoes. Admittedly, you already have to explain your example to people\nsaying \"it does not work because v2.6.11 is a tree and a tree by itself\ndoes not have a point in history\", but the thing is, v2.6.11-tree and\nv2.6.11 are oddballs, and you do not have to give that explanation very\noften, simply because the users are not exposed to a raw tree.\n\nBut WORKTREE and STAGE tokens are _meant_ to be exposed to them much more\nprominently. That's the whole point of the \"git diff STAGE WORKTREE\"\nproposal.\n\nPeople would become aware that they are very different from ordinary\ncommits, and then eventually they will realize that they are not even\ntrees [*1*]. \n\nAt that point, I suspect that these magic tokens become larger UI warts\nthemselves; they behave differently from everything else that is spelled\nin all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD).\n\nAs to --tree-vs-index counterproposal (was it a counterproposal?), except\nfor that I think they are too long to type in practice and need to be\nshortened to be useful, I do not have a fundamental objection against it.\n\n\n[Footnote]\n\n*1* For example, I would not expect that we will make \"git show WORKTREE\"\nto build a tree on the fly by running \"git add -A && git write-tree\" with\na temporary index and then running \"git show\" on the resulting tree\nobject, because there would be a better response than that if a user asks\n\"please show my worktree\".\n"},{"id":"127776","messageId":"94a0d4530911171400ub3b093ai668fd2404b12272f@mail.gmail.com","threadId":"21344","inReplyTo":"7vocn1dn5d.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-17T22:00:46Z","receivedAt":"2009-11-17T22:00:46Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Nov 17, 2009 at 8:25 PM, Junio C Hamano wrote:\n> But we do not have to support commit-ish operations, such as \"git log\".\n\nRight, and actuallly don't have to support WORKTREE/STAGE on all the\ncommands that work with the stage. For example I think 'git apply'\nbehaves completely different than 'git diff', since you cannot apply a\npatch on top of a commit, therefore it doesn't make sense to stage\nstuff as pseudo-refs; it makes sense to keep the --foo options\n(although I would prefer something like --stage and --stage-only).\n\n> It is a different story if these pseudo-refs that denote tree-ish are\n> useful outside the context of \"diff\".  I do not think of many commands\n> that take arbitrary tree-ish other than the ones I mentioned above.  Even\n> though they take arbitrary tree-ish, people almost always use commit-ish\n> with them.\n>\n> Which points to another issue with the approach.\n>\n> The original intention of these magic tokens are to make things easier,\n> but they actually may make things _harder_ to teach, because you have to\n> explain why \"git log WORKTREE\" does not work but \"git archive WORKTREE\"\n> does.  Admittedly, you already have to explain your example to people\n> saying \"it does not work because v2.6.11 is a tree and a tree by itself\n> does not have a point in history\", but the thing is, v2.6.11-tree and\n> v2.6.11 are oddballs, and you do not have to give that explanation very\n> often, simply because the users are not exposed to a raw tree.\n>\n> But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more\n> prominently.  That's the whole point of the \"git diff STAGE WORKTREE\"\n> proposal.\n>\n> People would become aware that they are very different from ordinary\n> commits, and then eventually they will realize that they are not even\n> trees [*1*].\n>\n> At that point, I suspect that these magic tokens become larger UI warts\n> themselves; they behave differently from everything else that is spelled\n> in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD).\n\nThat could be easily fixed by making explicit in the syntax that these\nare not typical refs: i.e. @stage and @work.\n\n-- \nFelipe Contreras\n"},{"id":"127779","messageId":"7v4ooseqvb.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"94a0d4530911171400ub3b093ai668fd2404b12272f@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-17T22:19:36Z","receivedAt":"2009-11-17T22:19:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> That could be easily fixed by making explicit in the syntax that these\n> are not typical refs: i.e. @stage and @work.\n\nThe message I get from that suggestion is that the most sensible approach,\nif we are going to add something from this discussion to \"git diff\", is to\ndo what you did _not_ quote from my message, which is:\n\n As to --tree-vs-index counterproposal (was it a counterproposal?),\n except for that I think they are too long to type in practice and need\n to be shortened to be useful, I do not have a fundamental objection\n against it.\n\nIOW, this is about options, and should not be done as syntax sugar that\ndoes a half-baked job of pretending to be refs.\n"},{"id":"127782","messageId":"94a0d4530911171506o2b08954bw4acba8ea9193e65d@mail.gmail.com","threadId":"21344","inReplyTo":"7v4ooseqvb.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-17T23:06:17Z","receivedAt":"2009-11-17T23:06:17Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Nov 18, 2009 at 12:19 AM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>> That could be easily fixed by making explicit in the syntax that these\n>> are not typical refs: i.e. @stage and @work.\n>\n> The message I get from that suggestion is that the most sensible approach,\n> if we are going to add something from this discussion to \"git diff\", is to\n> do what you did _not_ quote from my message, which is:\n>\n>    As to --tree-vs-index counterproposal (was it a counterproposal?),\n>    except for that I think they are too long to type in practice and need\n>    to be shortened to be useful, I do not have a fundamental objection\n>    against it.\n>\n> IOW, this is about options, and should not be done as syntax sugar that\n> does a half-baked job of pretending to be refs.\n\nSorry, I thought your only objection to STAGE and WORKTREE was that\nthey were not clearly differentiated, and my proposal gets rid of that\nissue. Now I fail to see what's the problem since you didn't explain\nwhat's wrong with adding syntactic sugar.\n\nIf the goal of the change is to make things more user-friendly, then\nI'd say \"git diff HEAD @stage\" is better than \"git diff\n--tree-vs-staged HEAD\".\n\n-- \nFelipe Contreras\n"},{"id":"127783","messageId":"7vzl6kd9t3.fsf@alter.siamese.dyndns.org","threadId":"21344","inReplyTo":"94a0d4530911171506o2b08954bw4acba8ea9193e65d@mail.gmail.com","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-17T23:13:28Z","receivedAt":"2009-11-17T23:13:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> If the goal of the change is to make things more user-friendly, then\n> I'd say \"git diff HEAD @stage\" is better than \"git diff\n> --tree-vs-staged HEAD\".\n\nExactly. That is where we disagree. The funny \"@stage\" does not convey\nthe fact that it is affecting how \"git diff\" operates, like any other\noption like \"-R\" does in \"git diff -R\" command line does. Now the user\nneeds to know git commands take -option like other normal tools do, but in\naddition they need to remember that an oddball \"diff\" subcommand takes\n\"@funny\" in addition to the usual \"-option\".\n\nHow would that be an improvement?\n"},{"id":"127788","messageId":"94a0d4530911171605y3d366786jbc977a2e583bb57f@mail.gmail.com","threadId":"21344","inReplyTo":"7vzl6kd9t3.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 0/2] user-manual: new \"getting started\" section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-11-18T00:05:47Z","receivedAt":"2009-11-18T00:05:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Nov 18, 2009 at 1:13 AM, Junio C Hamano wrote:\n> Exactly.  That is where we disagree.  The funny \"@stage\" does not convey\n> the fact that it is affecting how \"git diff\" operates, like any other\n> option like \"-R\" does in \"git diff -R\" command line does.  Now the user\n> needs to know git commands take -option like other normal tools do, but in\n> addition they need to remember that an oddball \"diff\" subcommand takes\n> \"@funny\" in addition to the usual \"-option\".\n\nRight now there are 4 modes of operations, the user would need to\nremember all of them... instead, the @stage pointer would reduce the\nmodes to 1, so the user would have to look on the man-page only once,\nquickly.\n\nAlso, to me it feels more natural to do \"git diff b a\" rather than\n\"git diff -R a b\", therefore \"git diff @stage HEAD\" beats \"git diff -R\n--cached HEAD\".\n\nMoreover, I wonder if these modes are really properly implemented. For\nexample, what's with these funky commands:\ngit diff HEAD master next <- shouldn't only 2 be allowed?\ngit diff HEAD..master HEAD..next\n\nAnyway, you are making the assumption that users actually use, and\nunderstand the different modes of operation, but I'm claiming most of\nthem don't, and one of the reasons could be that they are not\nintuitive.\n\n> How would that be an improvement?\n\nIt might make people actually start using the stage, which again, it\nseems apparent to me they don't. This can be easily interpreted from\nreading the git user survey (only 23% of the people use \"git add -i /\n-p\", and 15% \"git add -u / -A\" often), but if you don't believe so, we\ncan wait for the next one and ask the question explicitly.\n\n-- \nFelipe Contreras\n"}]}