{"thread":{"id":"9726","subject":"[PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","startedAt":"2007-08-31T17:47:11Z","lastAt":"2007-09-03T02:03:54Z","messageCount":7,"participants":["Jari Aalto","Junio C Hamano","Shawn Bohrer","Miles Bader"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"52063","messageId":"tzqfsijk.fsf@cante.net","threadId":"9726","inReplyTo":null,"subject":"[PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-08-31T17:47:11Z","receivedAt":"2007-08-31T17:47:11Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in\nexamples. This may be xconfusing to new users. The \"counting\" notation\nHEAD~N likely to be grasped more easily because it allow successive\nnumbering 1, 2, 3 etc.\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 15e3aca..c42cd26 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -55,7 +55,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@@ -77,7 +77,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.\n \n@@ -162,7 +162,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.5.3.rc5\n\n\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"52065","messageId":"7vy7frzfzg.fsf@gitster.siamese.dyndns.org","threadId":"9726","inReplyTo":"tzqfsijk.fsf@cante.net","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-31T19:00:35Z","receivedAt":"2007-08-31T19:00:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in\n> examples. This may be xconfusing to new users. The \"counting\" notation\n> HEAD~N likely to be grasped more easily because it allow successive\n> numbering 1, 2, 3 etc.\n\nI am mildly negative on this change.\n\nReferring to (rather, \"having to refer to\" to fix mistakes) the\nprevious commit happens far more often than referring to an\nancestor of an arbitrary generation away (i.e. HEAD~$n). I\nthink it is a better idea to expose users early on that HEAD^\nnotation which is shorter to type.\n"},{"id":"52130","messageId":"hcmesrse.fsf@cante.net","threadId":"9726","inReplyTo":"7vy7frzfzg.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-09-01T08:39:45Z","receivedAt":"2007-09-01T08:39:45Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n> Jari Aalto writes:\n>\n>> The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in\n>> examples. This may be xconfusing to new users. The \"counting\" notation\n>> HEAD~N likely to be grasped more easily because it allow successive\n>> numbering 1, 2, 3 etc.\n>\n> I am mildly negative on this change.\n>\n> Referring to (rather, \"having to refer to\" to fix mistakes) the\n> previous commit happens far more often than referring to an\n> ancestor of an arbitrary generation away (i.e. HEAD~$n). I\n> think it is a better idea to expose users early on that HEAD^\n> notation which is shorter to type.\n\nIf the page contains/combines many different ways of doing things,\nthis creates confusion, especially if the distictions are not explained.\nAnd it would be unnecessary to explain the HEAD^ and HEAD~1 similarities\nin every page where these two get mixed.\n\nPRICPLES:\n\n1. The novice user is best served by making things simple and uniform.\n\n2. Utilize concepts that may already be familar. E.g. other VCS/SCM tools\n have concept of counting back revisions with negative numbers: -1,\n -2, -3; so following this same idea in git manual pages would \n already rang associated bells.\n\nLike:\n\n HEAD, HEAD~1, HEAD~2\n\nIf the syntax is changed in the middle (as it was in manual page),\nthat interrupts the kognitive flow of reading.\n\n HEAD, HEAD^, HEAD~2\n\nI'm sure when user progresses with his learning, the differences or\nsimilarities of the notations become no-op.\n\nBut manual pages are served for wide audience. They are most\nimportant to new users.\n\nI hope we could strive for KISS is possible.\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"52136","messageId":"7vabs6u3jt.fsf@gitster.siamese.dyndns.org","threadId":"9726","inReplyTo":"hcmesrse.fsf@cante.net","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-09-01T09:40:22Z","receivedAt":"2007-09-01T09:40:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> Like:\n>\n> HEAD, HEAD~1, HEAD~2\n>\n> If the syntax is changed in the middle (as it was in manual page),\n> that interrupts the kognitive flow of reading.\n>\n> HEAD, HEAD^, HEAD~2\n>\n\nI still would prefer to teach people HEAD^ earlier. If you _REALLY_\ninsist, I can live with spelling the HEAD~2 as HEAD^^ for\nconsistency.\n\nWasn't with you that earlier I discussed that very basic things\nsuch as revision naming and range notation should be moved from\nrev-list documentation to more central place, and sructure the\ndocumentation in such a way that these should be read even\nbefore individual manual pages are consulted? If we follow\nthat, then by the time people read these examples, they _ought_\nto know that HEAD~1 is a longer-to-type way to say HEAD^ already.\n"},{"id":"52147","messageId":"20070901150153.GD7422@mediacenter.austin.rr.com","threadId":"9726","inReplyTo":"7vabs6u3jt.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Shawn Bohrer","fromEmail":"shawn.bohrer@gmail.com","sentAt":"2007-09-01T15:01:53Z","receivedAt":"2007-09-01T15:01:53Z","isPatch":true,"sender":{"key":"shawn.bohrer@gmail.com","avatar":"https://gravatar.com/avatar/6eb093ef7d276306d18366254e0c95ff6a5db58231ac7e82fe78c2800aaae1b6?d=mp&s=160"},"body":"On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:\n> Jari Aalto writes:\n> \n> > Like:\n> >\n> > HEAD, HEAD~1, HEAD~2\n> >\n> > If the syntax is changed in the middle (as it was in manual page),\n> > that interrupts the kognitive flow of reading.\n> >\n> > HEAD, HEAD^, HEAD~2\n> >\n> \n> I still would prefer to teach people HEAD^ earlier. If you _REALLY_\n> insist, I can live with spelling the HEAD~2 as HEAD^^ for\n> consistency.\n> \n> Wasn't with you that earlier I discussed that very basic things\n> such as revision naming and range notation should be moved from\n> rev-list documentation to more central place, and sructure the\n> documentation in such a way that these should be read even\n> before individual manual pages are consulted? If we follow\n> that, then by the time people read these examples, they _ought_\n> to know that HEAD~1 is a longer-to-type way to say HEAD^ already.\n\nWell I am a new user to git and I didn't find the mixed notation\nconfusing at all. Perhaps this is because I read the tutorial first,\nthen the git user manual which both explain this clearly.\n\nIn either case I think eliminating either notation from the man pages is\na bad idea. I'm quite confident that in the worst case a user will\nthink that if they want to refer to the parent they have to say HEAD^\nand if they want to refer to the grandparent they have to say HEAD~2.\nMost won't even find that strange since HEAD^ just seems shorter. I\nalso think many users will be smart enough to infer that if they wanted\nto they could say HEAD~3 or perhaps HEAD~1, though unless I saw it\nsomewhere I might not have guessed HEAD^^.\n"},{"id":"52152","messageId":"veauqfu0.fsf@cante.net","threadId":"9726","inReplyTo":"20070901150153.GD7422@mediacenter.austin.rr.com","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-09-01T20:40:55Z","receivedAt":"2007-09-01T20:40:55Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Shawn Bohrer writes:\n\n> On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:\n>\n>> Jari Aalto writes:\n>> \n>> > Like:\n>> >\n>> > HEAD, HEAD~1, HEAD~2\n>> >\n>> > If the syntax is changed in the middle (as it was in manual page),\n>> > that interrupts the kognitive flow of reading.\n>> >\n>> > HEAD, HEAD^, HEAD~2\n>> >\n>> \n>> I still would prefer to teach people HEAD^ earlier. If you _REALLY_\n>> insist, I can live with spelling the HEAD~2 as HEAD^^ for\n>> consistency.\n>\n> Well I am a new user to git and I didn't find the mixed notation\n> confusing at all. Perhaps this is because I read the tutorial first,\n> then the git user manual which both explain this clearly.\n\nNaturally one's learning path is naturally different. Did you come\nfrom other SCM/VCS before intorduced to git?\n\n> In either case I think eliminating either notation from the man pages is\n> a bad idea.\n\nThat was not proposed. There a mnay pages that use and shoudl use the\n^ notations. I was proposing that only (git-COMMAND) were dealt with.\n\nAfter all, the ^ very differento to what other SCM/VCSs use.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"52295","messageId":"buolkbofqt1.fsf@dhapc248.dev.necel.com","threadId":"9726","inReplyTo":"veauqfu0.fsf@cante.net","subject":"Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples","fromName":"Miles Bader","fromEmail":"miles.bader@necel.com","sentAt":"2007-09-03T02:03:54Z","receivedAt":"2007-09-03T02:03:54Z","isPatch":true,"sender":{"key":"miles.bader@necel.com","avatar":"https://gravatar.com/avatar/be062d4050eb88e04229cbdb60f803e1bd647923a015996c2439e76f23e336a7?d=mp&s=160"},"body":"Jari Aalto writes:\n> After all, the ^ very differento to what other SCM/VCSs use.\n\nIt's something I _constantly_ wished other SCM/VCSs had, as it's far,\nfar, more usable than the typical absolute rev numbers. It really\nshould be introduced as early as possible.\n\n-Miles\n\n-- \nFast, small, soon; pick any 2.\n"}]}