{"thread":{"id":"25893","subject":"[PATCH] git-reset.txt: Use commit~1 notation over commit^","startedAt":"2010-12-01T18:14:18Z","lastAt":"2010-12-02T19:05:54Z","messageCount":23,"participants":["jari.aalto@cante.net","Drew Northup","Jari Aalto","Kevin Ballard","Junio C Hamano","Santi Béjar","Andreas Schwab","Miles Bader","jari","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"156974","messageId":"1291227258-17922-1-git-send-email-jari.aalto@cante.net","threadId":"25893","inReplyTo":null,"subject":"[PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T18:14:18Z","receivedAt":"2010-12-01T18:14:18Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"From: Jari Aalto \n\nIn order to easily read paragraphs, use same notation and do not mixed\nboth ^ and ~N. This helps digesting the information more easier as the\ntokens stay the same (dcumentation uniformity).\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-reset.txt | 6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex fd72976..b679c99 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -129,7 +129,7 @@ Undo a commit and redo::\n +\n ------------\n $ git commit ...\n-$ git reset --soft HEAD^ <1>\n+$ git reset --soft HEAD~1 <1>\n $ edit <2>\n $ git commit -a -c ORIG_HEAD <3>\n ------------\n@@ -166,7 +166,7 @@ $ git commit ...\n $ git reset --hard HEAD~3 <1>\n ------------\n +\n-<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad\n+<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad\n and you do not want to ever see them again. Do *not* do this if\n you have already given these commits to somebody else. (See the\n \"RECOVERING FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1] for\n@@ -237,7 +237,7 @@ $ git checkout master\n $ fix fix fix\n $ git commit ;# commit with real log\n $ git checkout feature\n-$ git reset --soft HEAD^ ;# go back to WIP state <2>\n+$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n $ git reset <3>\n ------------\n +\n-- \n1.7.2.3\n"},{"id":"156985","messageId":"1291230820.11917.25.camel@drew-northup.unet.maine.edu","threadId":"25893","inReplyTo":"1291227258-17922-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-12-01T19:13:35Z","receivedAt":"2010-12-01T19:13:35Z","isPatch":true,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Wed, 2010-12-01 at 20:14 +0200, jari.aalto@cante.net wrote:\n> From: Jari Aalto \n> \n> In order to easily read paragraphs, use same notation and do not mixed\n> both ^ and ~N. This helps digesting the information more easier as the\n> tokens stay the same (dcumentation uniformity).\n> \n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-reset.txt | 6 +++---\n> 1 files changed, 3 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\n> index fd72976..b679c99 100644\n> --- a/Documentation/git-reset.txt\n> +++ b/Documentation/git-reset.txt\n> @@ -129,7 +129,7 @@ Undo a commit and redo::\n> +\n> ------------\n> $ git commit ...\n> -$ git reset --soft HEAD^ <1>\n> +$ git reset --soft HEAD~1 <1>\n> $ edit <2>\n> $ git commit -a -c ORIG_HEAD <3>\n> ------------\n> @@ -166,7 +166,7 @@ $ git commit ...\n> $ git reset --hard HEAD~3 <1>\n> ------------\n> +\n> -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad\n> +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad\n> and you do not want to ever see them again. Do *not* do this if\n> you have already given these commits to somebody else. (See the\n> \"RECOVERING FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1] for\n> @@ -237,7 +237,7 @@ $ git checkout master\n> $ fix fix fix\n> $ git commit ;# commit with real log\n> $ git checkout feature\n> -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n> $ git reset <3>\n> ------------\n> +\n\nI have to disagree here. Part of the task of good documentation is to\nshow not just what any one user may prefer (unless it is an accepted\nstandard, such as an RFC) but also what is possible. Removing the non\n\"~\" examples is actually a disservice to the documentation reader in a\ngreat many cases. What makes more sense in this case is to refer at some\npoint to the documentation which describes the allowed reference\nformats. This makes it clear that:\n(1) There are several allowed reference formats, and these are examples\nusing them;\n(2) These, over here, are descriptions of the allowed reference formats.\n\nAlso, strictly speaking, each separate operation example is a\n\"paragraph\" inside of a subsection and \"EXAMPLES\" is the containing\nsection. If you look at it this way it is already reasonably internally\nconsistent.\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"156992","messageId":"877hftuvvz.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"1291230820.11917.25.camel@drew-northup.unet.maine.edu","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T19:37:52Z","receivedAt":"2010-12-01T19:37:52Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-01 21:13 Drew Northup :\n> \"~\" examples is actually a disservice to the documentation reader in a\n\nWell. What I can say. I have witnessed close hand for thousands of\nlearners. Unfortunately they don't get educated that way. Bright people\nmay. But I'd rather address average Joe who is switching from SVN or the\nlike.\n\nWhat people appreciate, while learning, is constency. Sticking to one\nnotation is better than giving multiple choices. And the \"^\" isn't\nexactly readable, don't you agree?\n\n HEAD^^^^^^^^\n\nRight. How many was there again?\n\nBesides, the \"^\" key was probably inverted to work easily in US keybord.\nIt is not so in other parts of the world.\n\nThe fine print can be reserved to git-rev-parse(1) where you can get all\nthe details.\n\nJari\n"},{"id":"157029","messageId":"26B3CE3C-0C45-4D0B-8588-3769467AF527@sb.org","threadId":"25893","inReplyTo":"877hftuvvz.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T22:01:43Z","receivedAt":"2010-12-01T22:01:43Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Dec 1, 2010, at 11:37 AM, Jari Aalto wrote:\n\n> 2010-12-01 21:13 Drew Northup :\n>> \"~\" examples is actually a disservice to the documentation reader in a\n> \n> Well. What I can say. I have witnessed close hand for thousands of\n> learners. Unfortunately they don't get educated that way. Bright people\n> may. But I'd rather address average Joe who is switching from SVN or the\n> like.\n> \n> What people appreciate, while learning, is constency. Sticking to one\n> notation is better than giving multiple choices. And the \"^\" isn't\n> exactly readable, don't you agree?\n> \n> HEAD^^^^^^^^\n> \n> Right. How many was there again?\n\nYour patch isn't touching any example of HEAD^^^^^^^. Every single one that\nyou've changed was a simple HEAD^. And this, I feel, is absolutely wrong.\nHEAD^ is far more common notation than HEAD~1, and should be preserved as\nsuch in the manpage. I also agree with Drew that giving examples with\ndifferent notation is useful to show alternative syntax. If the manpages\nall use a single notation when there are several options, it gives the\nimpression that this one notation is what you should always use. And that's\nnot what the manpage is trying to say.\n\n-Kevin Ballard\n"},{"id":"157033","messageId":"7vfwuhtafr.fsf@alter.siamese.dyndns.org","threadId":"25893","inReplyTo":"877hftuvvz.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-01T22:06:32Z","receivedAt":"2010-12-01T22:06:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> What people appreciate, while learning, is constency. Sticking to one\n> notation is better than giving multiple choices. And the \"^\" isn't\n> exactly readable, don't you agree?\n>\n> HEAD^^^^^^^^\n>\n> Right. How many was there again?\n\nThere is no question that you need to really count them, and that is why\nwe invented HEAD~8 notation in the first place. It however is wrong to\nuse the above illustration to defend your change that replaces \"HEAD^\"\nwith \"HEAD~1\". \n\nThe thing is, you need to name/call the previous one a lot more often than\nyou need to call the eighth previous one. The previous one \"HEAD~1\" is\nspecial because it directly relates to the current commit (it is the first\nparent of the current commit) and that is why people often need to access\nit.\n\nAnd \"HEAD^\" is shorter and much easier to type, and more importantly, it\nis more often used in the wild, so the readers of the documentation needs\nto know it anyway to understand what other people do.\n"},{"id":"157040","messageId":"87ipzdt8gb.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"26B3CE3C-0C45-4D0B-8588-3769467AF527@sb.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T22:49:24Z","receivedAt":"2010-12-01T22:49:24Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 00:01 Kevin Ballard :\n> On Dec 1, 2010, at 11:37 AM, Jari Aalto wrote:\n>\n> Your patch isn't touching any example of HEAD^^^^^^^. Every single one that\n> you've changed was a simple HEAD^.\n\nYes of course:\n\n >> What people appreciate, while learning, is constency. Sticking to one\n >> notation is better than giving multiple choices.\n\n> And this, I feel, is absolutely wrong.\n\nWhatever you feel. Consistency is important viewpoint. Try explaining to\na group of people these two variations. The make them write scripts to\nuse git commands. Guess which notation they choose? The \"^\" isnt' even\nscriptable.\n\nJari\n"},{"id":"157042","messageId":"87eia1t8ef.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"7vfwuhtafr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-01T22:50:32Z","receivedAt":"2010-12-01T22:50:32Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 00:06 Junio C Hamano :\n> And \"HEAD^\" is shorter and much easier to type\n\nI don't know in which part of world that is, probably only using US\nkeyboard. Not so elsewhere with keyboards more than just only ASCII\ncharacters.\n\nJari\n"},{"id":"157043","messageId":"F13BED73-8C90-46D9-8AC9-054EF24DC688@sb.org","threadId":"25893","inReplyTo":"87ipzdt8gb.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2010-12-01T22:56:20Z","receivedAt":"2010-12-01T22:56:20Z","isPatch":true,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Dec 1, 2010, at 2:49 PM, Jari Aalto wrote:\n\n> Whatever you feel. Consistency is important viewpoint. Try explaining to\n> a group of people these two variations. The make them write scripts to\n> use git commands. Guess which notation they choose? The \"^\" isnt' even\n> scriptable.\n\nWhat do you mean? I've personally taught nearly everybody at my office how\nto use git, and every single one of them uses ^ when they want to go to the\nprevious commit and ~n when they want to go n commits back (where n > 1).\nEven the few people who knew git before I talked to them use this convention.\nAnd guess where those people learned it? By seeing the different syntaxes\nin the manpage. Even for the people I taught, I never told them expressly to\nuse HEAD^ vs HEAD~3, but through the combination of my examples and the\nexamples in the manpages, they all understood both operators and how to use\nthem without any difficulty whatsoever.\n\nYou stated that you have \"witnessed close hand for thousands of learners.\"\nAnd you state that these people don't understand this sort of documentation.\nI don't mean to give offense, but have you ever considered what the common\nelement here is?\n\n-Kevin Ballard\n"},{"id":"157044","messageId":"AANLkTik8TNedGBQh7KXvRSf3HTTQf2-yMJC4VA4OOBjQ@mail.gmail.com","threadId":"25893","inReplyTo":"7vfwuhtafr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Santi Béjar","fromEmail":"santi@agolina.net","sentAt":"2010-12-01T22:56:21Z","receivedAt":"2010-12-01T22:56:21Z","isPatch":true,"sender":{"key":"santi@agolina.net","avatar":null},"body":"On Wed, Dec 1, 2010 at 11:06 PM, Junio C Hamano wrote:\n> Jari Aalto writes:\n>\n>> What people appreciate, while learning, is constency. Sticking to one\n>> notation is better than giving multiple choices. And the \"^\" isn't\n>> exactly readable, don't you agree?\n>>\n>>     HEAD^^^^^^^^\n>>\n>> Right. How many was there again?\n>\n> There is no question that you need to really count them, and that is why\n> we invented HEAD~8 notation in the first place.  It however is wrong to\n> use the above illustration to defend your change that replaces \"HEAD^\"\n> with \"HEAD~1\".\n>\n> The thing is, you need to name/call the previous one a lot more often than\n> you need to call the eighth previous one.  The previous one \"HEAD~1\" is\n> special because it directly relates to the current commit (it is the first\n> parent of the current commit) and that is why people often need to access\n> it.\n\nAdditionaly, you must know about the ^ notation. That is the only way\nrefer to the second parent HEAD^2, for example.\n\nHTH,\nSanti\n"},{"id":"157062","messageId":"m2pqtlqbq0.fsf@igel.home","threadId":"25893","inReplyTo":"87eia1t8ef.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-12-02T00:07:03Z","receivedAt":"2010-12-02T00:07:03Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Jari Aalto writes:\n\n> 2010-12-02 00:06 Junio C Hamano :\n>> And \"HEAD^\" is shorter and much easier to type\n>\n> I don't know in which part of world that is, probably only using US\n> keyboard. Not so elsewhere with keyboards more than just only ASCII\n> characters.\n\nOn a German keyboard ~ is awkward to type (AltGr-+) whereas ^ is on an\nunshifted key.\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"157073","messageId":"87k4js51u7.fsf@catnip.gol.com","threadId":"25893","inReplyTo":"7vfwuhtafr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-12-02T02:46:08Z","receivedAt":"2010-12-02T02:46:08Z","isPatch":true,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Junio C Hamano writes:\n> And \"HEAD^\" is shorter and much easier to type, and more importantly, it\n> is more often used in the wild, so the readers of the documentation needs\n> to know it anyway to understand what other people do.\n\nSeriously: People like ^.\n\nThis doc change is not good (and seems to demonstrate a lack of\nfamiliarity with typical git usage)....\n\n-Miles\n\n-- \no The existentialist, not having a pillow, goes everywhere with the book by\n Sullivan, _I am going to spit on your graves_.\n"},{"id":"157079","messageId":"87wrnsspkv.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"m2pqtlqbq0.fsf@igel.home","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T05:37:04Z","receivedAt":"2010-12-02T05:37:04Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 02:07 Andreas Schwab :\n> Jari Aalto writes:\n>\n>> 2010-12-02 00:06 Junio C Hamano :\n>>> And \"HEAD^\" is shorter and much easier to type\n>>\n>> I don't know in which part of world that is, probably only using US\n>> keyboard. Not so elsewhere with keyboards more than just only ASCII\n>> characters.\n>\n> On a German keyboard ~ is awkward to type (AltGr-+) whereas ^ is on an\n> unshifted key.\n\nAnd notebook/laptops in German? For FI-keyboards everything is pain.\n\nJari\n"},{"id":"157078","messageId":"87sjygspgy.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"AANLkTik8TNedGBQh7KXvRSf3HTTQf2-yMJC4VA4OOBjQ@mail.gmail.com","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T05:39:25Z","receivedAt":"2010-12-02T05:39:25Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 00:56 Santi Béjar :\n> On Wed, Dec 1, 2010 at 11:06 PM, Junio C Hamano wrote:\n>\n> Additionaly, you must know about the ^ notation. That is the only way\n> refer to the second parent HEAD^2, for example.\n\nIf \"must\" is a requirement, I have to regret that there has yet to have\nbeen a situation where I would ahve a need to refer to \"second parent\".\n\nI guess most of the basic features can be used without it.\n\nJari\n"},{"id":"157086","messageId":"buo39qg8zrf.fsf@dhlpc061.dev.necel.com","threadId":"25893","inReplyTo":"87sjygspgy.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-12-02T06:17:24Z","receivedAt":"2010-12-02T06:17:24Z","isPatch":true,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Jari Aalto writes:\n>> Additionaly, you must know about the ^ notation. That is the only way\n>> refer to the second parent HEAD^2, for example.\n>\n> If \"must\" is a requirement, I have to regret that there has yet to have\n> been a situation where I would ahve a need to refer to \"second parent\".\n>\n> I guess most of the basic features can be used without it.\n\nIt doesn't matter. There needs to be a better reason than \"Jari doesn't\nlike it.\"\n\n-Miles\n\n-- \nSomebody has to do something, and it's just incredibly pathetic that it\nhas to be us. -- Jerry Garcia\n"},{"id":"157104","messageId":"87bp54s770.fsf@picasso.cante.net","threadId":"25893","inReplyTo":"buo39qg8zrf.fsf@dhlpc061.dev.necel.com","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T12:14:11Z","receivedAt":"2010-12-02T12:14:11Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"2010-12-02 08:17 Miles Bader :\n> Jari Aalto writes:\n>\n>>> Additionaly, you must know about the ^ notation. That is the only way\n>>> refer to the second parent HEAD^2, for example.\n>>\n>> If \"must\" is a requirement, I have to regret that there has yet to have\n>> been a situation where I would ahve a need to refer to \"second parent\".\n>>\n>> I guess most of the basic features can be used without it.\n>\n> It doesn't matter. There needs to be a better reason than \"Jari doesn't\n> like it.\"\n\nThis has nothing to do with liking. It how infomation is read. When\ninformation is consistent, it lessens cognitive load.\n\nIn the \"fine print\" git-rev-parse(1) there can be the gory details.\n\nmost of the commenters probably are already experts and therefor wear\n\"expert glasses on\". It's not necessarily the same for starters.\nCertainly not when you try to teach 100 people. One form is much better\nin that situation than variations. You only do it at the end:\n\n \"[After finishing 6 week training] Btw, if you need more details\n look at....\"\n\nExperts can later pick anything they want.\n\nJari\n"},{"id":"157110","messageId":"1291294266.20062.10.camel@drew-northup.unet.maine.edu","threadId":"25893","inReplyTo":"87bp54s770.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-12-02T12:51:06Z","receivedAt":"2010-12-02T12:51:06Z","isPatch":true,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Thu, 2010-12-02 at 14:14 +0200, Jari Aalto wrote:\n> 2010-12-02 08:17 Miles Bader :\n> > Jari Aalto writes:\n> >\n> >>> Additionaly, you must know about the ^ notation. That is the only way\n> >>> refer to the second parent HEAD^2, for example.\n> >>\n> >> If \"must\" is a requirement, I have to regret that there has yet to have\n> >> been a situation where I would ahve a need to refer to \"second parent\".\n> >>\n> >> I guess most of the basic features can be used without it.\n> >\n> > It doesn't matter. There needs to be a better reason than \"Jari doesn't\n> > like it.\"\n> \n> This has nothing to do with liking. It how infomation is read. When\n> information is consistent, it lessens cognitive load.\n> \n> In the \"fine print\" git-rev-parse(1) there can be the gory details.\n> \n> most of the commenters probably are already experts and therefor wear\n> \"expert glasses on\". It's not necessarily the same for starters.\n> Certainly not when you try to teach 100 people. One form is much better\n> in that situation than variations. You only do it at the end:\n> \n> \"[After finishing 6 week training] Btw, if you need more details\n> look at....\"\n> \n> Experts can later pick anything they want.\n> \n> Jari\n\nI have worked in instructional settings, as the instructor. I can say\nflat out that this is an incomplete view of the learning patterns of\npeople being newly exposed to a concept or a technology. Besides, many\npeople who consult manpages often think of themselves as experts (and\nmay think better of the idea after consulting the documentation).\n\nThe reality is that learning is not nearly as proscribed and rote a\nprocess as you are making it out to be. Rote memorization is good for\nlearning multiplications tables, alphabets, and the approximate values\nof e and pi. It is not particularly suited for learning grammars and\nsyntaxes--which is why language and algebra are typically not taught\nthat way. Programming and using computers benefits greatly from\npresenting multiple varied examples--even to the supposed experts who\nprobably don't know it all either.\n\nLeave the odd examples in the manpages--people depend on them being\nthere.\n\n-- \n-Drew Northup N1XIM\n AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"157112","messageId":"87mxoos4a8.fsf@catnip.gol.com","threadId":"25893","inReplyTo":"87bp54s770.fsf@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2010-12-02T13:17:03Z","receivedAt":"2010-12-02T13:17:03Z","isPatch":true,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Jari Aalto writes:\n>> It doesn't matter. There needs to be a better reason than \"Jari doesn't\n>> like it.\"\n>\n> This has nothing to do with liking. It how infomation is read. When\n> information is consistent, it lessens cognitive load.\n\nNo, it has to do with your trying to impose your personal tastes.\n\n^ (and ^^, etc) is a simpler and easier concept to deal with, and\nsufficient for the vast majority of tasks -- beyond 1 or 2 levels,\nit's typically easier to just use an absolute reference cut-and-pasted\nfrom git log output than it is to count commits and get the right\nvalue to use with ~ (and from experience, unless you're careful, it's\nvery easy to get counts for ~ wrong). So it's ~ that's the \"expert\nnotation\", not ^.\n\n[How do I know? Because I've _been_ a git beginner, and spent a long\ntime trying to learn git.]\n\n-Miles\n\n-- \nDiscriminate, v.i. To note the particulars in which one person or thing is,\nif possible, more objectionable than another.\n"},{"id":"157113","messageId":"20101202132053.GF6537@picasso.cante.net","threadId":"25893","inReplyTo":"87mxoos4a8.fsf@catnip.gol.com","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"jari","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-02T13:20:53Z","receivedAt":"2010-12-02T13:20:53Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"| ^ (and ^^, etc) is a simpler and easier concept to deal with, and\n| ... very easy to get counts for ~ wrong). So it's ~ that's the\n| \"expert notation\", not ^.\n\nNot that it matters, but have you happende to notice that all git\noutputs use\n\n commit~N\n\nnotation. Not the\n\n commit^\n\nJari\n"},{"id":"157124","messageId":"m262vcqdb9.fsf@igel.home","threadId":"25893","inReplyTo":"20101202132053.GF6537@picasso.cante.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-12-02T17:44:58Z","receivedAt":"2010-12-02T17:44:58Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"jari writes:\n\n> Not that it matters, but have you happende to notice that all git\n> outputs use\n>\n> commit~N\n>\n> notation. Not the\n>\n> commit^\n\nDid you try \"git show-branch -a\" recently?\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"157130","messageId":"7veia0rrew.fsf@alter.siamese.dyndns.org","threadId":"25893","inReplyTo":"m262vcqdb9.fsf@igel.home","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-02T17:55:03Z","receivedAt":"2010-12-02T17:55:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Schwab writes:\n\n> jari writes:\n>\n>> Not that it matters, but have you happende to notice that all git\n>> outputs use\n>>\n>> commit~N\n>>\n>> notation. Not the\n>>\n>> commit^\n>\n> Did you try \"git show-branch -a\" recently?\n\nPerhaps we need to also fix \"git name-rev master^\" which currently does\nnot try to reduce \"master~1\" to \"master^\".\n"},{"id":"157139","messageId":"20101202184617.GA20225@sigill.intra.peff.net","threadId":"25893","inReplyTo":"7veia0rrew.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-12-02T18:46:17Z","receivedAt":"2010-12-02T18:46:17Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Dec 02, 2010 at 09:55:03AM -0800, Junio C Hamano wrote:\n\n> Perhaps we need to also fix \"git name-rev master^\" which currently does\n> not try to reduce \"master~1\" to \"master^\".\n\nThis patch does it:\n\ndiff --git a/builtin/name-rev.c b/builtin/name-rev.c\nindex c946a82..417bae5 100644\n--- a/builtin/name-rev.c\n+++ b/builtin/name-rev.c\n@@ -142,8 +142,12 @@ static const char *get_rev_name(const struct object *o)\n \t\tint len = strlen(n->tip_name);\n \t\tif (len > 2 && !strcmp(n->tip_name + len - 2, \"^0\"))\n \t\t\tlen -= 2;\n-\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len, n->tip_name,\n-\t\t\t\tn->generation);\n+\t\tif (n->generation == 1)\n+\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s^\", len,\n+\t\t\t\t n->tip_name);\n+\t\telse\n+\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len,\n+\t\t\t\t n->tip_name, n->generation);\n \n \t\treturn buffer;\n \t}\n\nbut I am not sure the results are always more readable. I think \"foo^\"\nis perhaps nicer than \"foo~1\". But in more complex examples, I kind of\nthink the ~1 is easier to read. E.g.:\n\n # old\n $ git name-rev 9904fadf\n 9904fadf tags/v1.7.3-rc2~1^2~1\n\n # new\n $ git name-rev 9904fadf\n 9904fadf tags/v1.7.3-rc2~1^2^\n\nSomehow the visual appearance of \"^2^\" ends up being more confusing to\nme than ~1^2~1, I guess because in the latter there is a regular set of\nmodifier-number pairs.\n\nBut I admit that is just my subjective opinion.\n\n-Peff\n"},{"id":"157140","messageId":"7vvd3cqa44.fsf@alter.siamese.dyndns.org","threadId":"25893","inReplyTo":"20101202184617.GA20225@sigill.intra.peff.net","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-02T18:54:03Z","receivedAt":"2010-12-02T18:54:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Thu, Dec 02, 2010 at 09:55:03AM -0800, Junio C Hamano wrote:\n>\n>> Perhaps we need to also fix \"git name-rev master^\" which currently does\n>> not try to reduce \"master~1\" to \"master^\".\n>\n> This patch does it:\n>\n> diff --git a/builtin/name-rev.c b/builtin/name-rev.c\n> index c946a82..417bae5 100644\n> --- a/builtin/name-rev.c\n> +++ b/builtin/name-rev.c\n> @@ -142,8 +142,12 @@ static const char *get_rev_name(const struct object *o)\n> \t\tint len = strlen(n->tip_name);\n> \t\tif (len > 2 && !strcmp(n->tip_name + len - 2, \"^0\"))\n> \t\t\tlen -= 2;\n> -\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len, n->tip_name,\n> -\t\t\t\tn->generation);\n> +\t\tif (n->generation == 1)\n> +\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s^\", len,\n> +\t\t\t\t n->tip_name);\n> +\t\telse\n> +\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len,\n> +\t\t\t\t n->tip_name, n->generation);\n> \n> \t\treturn buffer;\n> \t}\n>\n> but I am not sure the results are always more readable. I think \"foo^\"\n> is perhaps nicer than \"foo~1\". But in more complex examples, I kind of\n> think the ~1 is easier to read. E.g.:\n>\n> # old\n> $ git name-rev 9904fadf\n> 9904fadf tags/v1.7.3-rc2~1^2~1\n>\n> # new\n> $ git name-rev 9904fadf\n> 9904fadf tags/v1.7.3-rc2~1^2^\n\nCurious. Why does the \"first take the first parent of rc2\" is left as-is,\nwhile \"then lastly take its parent\" does get shortened?\n\n> Somehow the visual appearance of \"^2^\" ends up being more confusing to\n> me than ~1^2~1, I guess because in the latter there is a regular set of\n> modifier-number pairs.\n>\n> But I admit that is just my subjective opinion.\n>\n> -Peff\n"},{"id":"157142","messageId":"20101202190553.GB20225@sigill.intra.peff.net","threadId":"25893","inReplyTo":"7vvd3cqa44.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-12-02T19:05:54Z","receivedAt":"2010-12-02T19:05:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Dec 02, 2010 at 10:54:03AM -0800, Junio C Hamano wrote:\n\n> > but I am not sure the results are always more readable. I think \"foo^\"\n> > is perhaps nicer than \"foo~1\". But in more complex examples, I kind of\n> > think the ~1 is easier to read. E.g.:\n> >\n> > # old\n> > $ git name-rev 9904fadf\n> > 9904fadf tags/v1.7.3-rc2~1^2~1\n> >\n> > # new\n> > $ git name-rev 9904fadf\n> > 9904fadf tags/v1.7.3-rc2~1^2^\n> \n> Curious. Why does the \"first take the first parent of rc2\" is left as-is,\n> while \"then lastly take its parent\" does get shortened?\n\nBecause my patch is crappy and I didn't spend more than 30 seconds\ntesting it? :)\n\nIt needs a similar change elsewhere, so the full patch should be:\n\ndiff --git a/builtin/name-rev.c b/builtin/name-rev.c\nindex c946a82..03d7bce 100644\n--- a/builtin/name-rev.c\n+++ b/builtin/name-rev.c\n@@ -64,9 +64,15 @@ copy_data:\n \n \t\t\tif (len > 2 && !strcmp(tip_name + len - 2, \"^0\"))\n \t\t\t\tlen -= 2;\n-\t\t\tif (generation > 0)\n-\t\t\t\tsprintf(new_name, \"%.*s~%d^%d\", len, tip_name,\n+\t\t\tif (generation > 0) {\n+\t\t\t\tint w = sprintf(new_name, \"%.*s\", len, tip_name);\n+\t\t\t\tif (generation == 1)\n+\t\t\t\t\tsprintf(new_name + w, \"^^%d\",\n+\t\t\t\t\t\tparent_number);\n+\t\t\t\telse\n+\t\t\t\t\tsprintf(new_name + w, \"~%d^%d\",\n \t\t\t\t\t\tgeneration, parent_number);\n+\t\t\t}\n \t\t\telse\n \t\t\t\tsprintf(new_name, \"%.*s^%d\", len, tip_name,\n \t\t\t\t\t\tparent_number);\n@@ -142,8 +148,12 @@ static const char *get_rev_name(const struct object *o)\n \t\tint len = strlen(n->tip_name);\n \t\tif (len > 2 && !strcmp(n->tip_name + len - 2, \"^0\"))\n \t\t\tlen -= 2;\n-\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len, n->tip_name,\n-\t\t\t\tn->generation);\n+\t\tif (n->generation == 1)\n+\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s^\", len,\n+\t\t\t\t n->tip_name);\n+\t\telse\n+\t\t\tsnprintf(buffer, sizeof(buffer), \"%.*s~%d\", len,\n+\t\t\t\t n->tip_name, n->generation);\n \n \t\treturn buffer;\n \t}\n\nHowever, IMHO that looks even worse:\n\n $ git name-rev 9904fadf\n 9904fadf tags/v1.7.3-rc2^^2^\n\n-Peff\n"}]}