{"thread":{"id":"11820","subject":"[PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","startedAt":"2008-02-02T01:41:01Z","lastAt":"2008-02-04T22:33:50Z","messageCount":16,"participants":["Jari Aalto","Johannes Schindelin","Junio C Hamano","Mike Hommey","Jakub Narebski","J. Bruce Fields","Robin Rosenberg","Dmitry Potapov"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"67061","messageId":"3asc6spe.fsf@blue.sea.net","threadId":"11820","inReplyTo":null,"subject":"[PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T01:41:01Z","receivedAt":"2008-02-02T01:41:01Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"The examples in the documentation refer to multiple ~N commits. To\nKeep the exampels unified with the same syntax, use ~N in all examples.\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 a4e0a77..0566956 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -58,7 +58,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@@ -80,7 +80,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@@ -165,7 +165,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.4-rc5.GIT-dirty\n\n\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67069","messageId":"alpine.LSU.1.00.0802020235480.7372@racer.site","threadId":"11820","inReplyTo":"3asc6spe.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2008-02-02T02:37:44Z","receivedAt":"2008-02-02T02:37:44Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 2 Feb 2008, Jari Aalto wrote:\n\n> The examples in the documentation refer to multiple ~N commits. To Keep \n> the exampels unified with the same syntax, use ~N in all examples.\n\nAFAIR it was already shot down. Personally, I think it is not expecting \ntoo much of people to have the ambiguity between ~1 and ^1. Even worse, \nif you hide the ^-syntax from new users, they will be puzzled how to \naccess the different parents of merge commits.\n\nCiao,\nDscho\n"},{"id":"67071","messageId":"7v7iho6p2m.fsf@gitster.siamese.dyndns.org","threadId":"11820","inReplyTo":"3asc6spe.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-02-02T02:59:29Z","receivedAt":"2008-02-02T02:59:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> The examples in the documentation refer to multiple ~N commits. To\n> Keep the exampels unified with the same syntax, use ~N in all examples.\n>\n> Signed-off-by: Jari Aalto \n\n> -$ git reset --soft HEAD^ <1>\n> +$ git reset --soft HEAD~1 <1>\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> -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n\nI personally think this is a regression, not an improvement.\n\nPeople need to refer to the HEAD^ (one commit ago) much more\noften than HEAD~N for larger values of N. And we should give\nthem exposure to HEAD^ and HEAD^^; both are faster and easier to\ntype and read than HEAD~1 and HEAD~2.\n\nEspecially about HEAD~1, nobody sane would type that. It is\nthere only for consistency.\n\nOtherwise, twisted people would complain \"I can say HEAD~4\ninstead of HEAD^^^^ and it helps brevity; but it is inconsistent\nthat I cannot say HEAD~1 instead of HEAD^\".\n"},{"id":"67089","messageId":"20080202084406.GA15305@glandium.org","threadId":"11820","inReplyTo":"7v7iho6p2m.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2008-02-02T08:44:06Z","receivedAt":"2008-02-02T08:44:06Z","isPatch":true,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"On Fri, Feb 01, 2008 at 06:59:29PM -0800, Junio C Hamano wrote:\n> Jari Aalto writes:\n> \n> > The examples in the documentation refer to multiple ~N commits. To\n> > Keep the exampels unified with the same syntax, use ~N in all examples.\n> >\n> > Signed-off-by: Jari Aalto \n> \n> > -$ git reset --soft HEAD^ <1>\n> > +$ git reset --soft HEAD~1 <1>\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> > -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n> > +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n> \n> I personally think this is a regression, not an improvement.\n> \n> People need to refer to the HEAD^ (one commit ago) much more\n> often than HEAD~N for larger values of N. And we should give\n> them exposure to HEAD^ and HEAD^^; both are faster and easier to\n> type and read than HEAD~1 and HEAD~2.\n> \n> Especially about HEAD~1, nobody sane would type that. It is\n> there only for consistency.\n> \n> Otherwise, twisted people would complain \"I can say HEAD~4\n> instead of HEAD^^^^ and it helps brevity; but it is inconsistent\n> that I cannot say HEAD~1 instead of HEAD^\".\n\nI wonder if it wouldn't make sense to have ^ described with ^1 ^2, and\nadd the possibility to also have ~, which would have the same meaning by\nside effect, described with ~1 ~2, etc.\n\nThe problem with ^ being described with ~1 ~2 is that it makes things\nharder to understand than they actually are. The real problem being that\n^ sounds like having different meanings depending whether it's followed\nby a number or not.\n\nMike\n"},{"id":"67132","messageId":"8x235xa8.fsf@blue.sea.net","threadId":"11820","inReplyTo":"20080202084406.GA15305@glandium.org","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T12:59:43Z","receivedAt":"2008-02-02T12:59:43Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Sat 2008-02-02 Mike Hommey gmane.comp.version-control.git\n* Message-Id: 20080202084406.GA15305@glandium.org\n>> \n>> > -$ git reset --soft HEAD^ <1>\n>> > +$ git reset --soft HEAD~1 <1>\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>> > -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n>> > +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n\n>> People need to refer to the HEAD^ (one commit ago) much more\n>> often than HEAD~N for larger values of N. \n\nI use HEAD~1 always, because I think the consistency in learning the\nmost important factor.\n\nIt does not matter what advanced users use. The documentation should\nprimarily focus the newcomers.\n\nThe first question a newbie asks, if manual pages mixes syntaxes:\n\n What the heck \"^\" ?. I just saw HEAD~N, is the other one somehow\n special?\n\nAll the other examples refer to\n\n HEAD~N\n\nThose used to git may prefer ^, but it does not follow that others\nnecessarily do so and that that should be the \"proper learning path\".\nPeople usually migrate to git from other VCSs, which have very\nconsistent UI - There are no alternatives\n\n -r1:10 Subversion\n -r1..19 Bzr\n ...etc\n\nIt's unfortunate is the focus is given to comments like \"easier type\",\nwhen the context is the manual pages.\n\n>> Especially about HEAD~1, nobody sane would type that.\n\nYou consider all such users insane? It actually helps to select onlyt\none sytax, and HEAD~N is much more readable without further explanations,\n(becasue people are already used to knowing, from other VCSs, what a\nHEAD or TIP is). It's not all that different from prefering the\n\"--quiet\" over \"-q\" e.g. e.g. in shell scripts.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67133","messageId":"m3d4rf7a4r.fsf@localhost.localdomain","threadId":"11820","inReplyTo":"8x235xa8.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T13:37:04Z","receivedAt":"2008-02-02T13:37:04Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto writes:\n\n> * Sat 2008-02-02 Mike Hommey gmane.comp.version-control.git\n> * Message-Id: 20080202084406.GA15305@glandium.org\n>>> \n>>>> -$ git reset --soft HEAD^ <1>\n>>>> +$ git reset --soft HEAD~1 <1>\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>>>> -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n>>>> +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n> \n>>> People need to refer to the HEAD^ (one commit ago) much more\n>>> often than HEAD~N for larger values of N. \n> \n> I use HEAD~1 always, because I think the consistency in learning the\n> most important factor.\n\nI think that focusing on the fact that \"HEAD^1\" is peel-like operator,\nselecting first parent of HEAD, That \"HEAD^\" is a shortcut for that,\nand that \"HEAD~3\" is a shortcut for \"HEAD^^^\" similarly to how \"3 * 2\"\nis a shortcut for \"2 + 2 + 2\" is better solution. \"HEAD~1\" and\n\"HEAD~2\" are not shorter than original notation.\n \n> It does not matter what advanced users use. The documentation should\n> primarily focus the newcomers.\n\nThe documentation should cater to both advanced users and newcomers,\nunless it is specifically targeted towards newcomers like different\nintro documentation, or first part of Git User's Manual.\n\n> The first question a newbie asks, if manual pages mixes syntaxes:\n> \n> What the heck \"^\" ?. I just saw HEAD~N, is the other one somehow\n> special?\n> \n> All the other examples refer to\n> \n> HEAD~N\n> \n> Those used to git may prefer ^, but it does not follow that others\n> necessarily do so and that that should be the \"proper learning\n> path\".\n\nIMHO the sequence: \n \"HEAD^1\" -> \"HEAD^\", \n \"HEAD^1^1^1\" -> \"HEAD^^^\" -> \"HEAD~3\"\nis the proper sequence to teach.\n\nEspecially that \"rev^sth\" is used also for other things, like\n\"HEAD^{tree}\", or \"v1.3.0^{commit}\" peeling operators, or even\n\"master^0\" used to force detach HEAD to 'master'.\n\n> People usually migrate to git from other VCSs, which have very\n> consistent UI - There are no alternatives\n> \n> -r1:10 Subversion\n> -r1..19 Bzr\n> ...etc\n> \n> It's unfortunate is the focus is given to comments like \"easier type\",\n> when the context is the manual pages.\n\nThis is stupid example. Numbering revisions is possible only in\ncentralized SCMs, or semi-centralized SCMs (with one repository given\nspecial, central position). You need an authority to assign sequential\nnumbers to revisions.\n\nBesides git uses the same notation, .., only it doesn't\nneed '-r' option to select revision or revision range.\n\n>>> Especially about HEAD~1, nobody sane would type that.\n> \n> You consider all such users insane? It actually helps to select onlyt\n> one sytax, and HEAD~N is much more readable without further explanations,\n> (becasue people are already used to knowing, from other VCSs, what a\n> HEAD or TIP is). It's not all that different from prefering the\n> \"--quiet\" over \"-q\" e.g. e.g. in shell scripts.\n\nIt is also much less powerfull, as it can only follow first-parent\nline. In the presence of merges you usually use ^n more.\n\n\nThat said, I personally don't have strong preference whether to use\n\"HEAD\", \"HEAD^\", \"HEAD^^\", \"HEAD~3\" in examples, or \"HEAD\", \"HEAD~1\",\n\"HEAD~2\", \"HEAD~3\". It is a bit of \"bikeshed\" discussion.\n\n-- \nJakub Narebski\n\n In related news: there is really no question that bike sheds should\n be painted red. Really. (Johannes Schindelin)\n"},{"id":"67146","messageId":"20080202161813.GA19797@fieldses.org","threadId":"11820","inReplyTo":"8x235xa8.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2008-02-02T16:18:13Z","receivedAt":"2008-02-02T16:18:13Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:\n> * Sat 2008-02-02 Mike Hommey gmane.comp.version-control.git\n> * Message-Id: 20080202084406.GA15305@glandium.org\n> >> \n> >> > -$ git reset --soft HEAD^ <1>\n> >> > +$ git reset --soft HEAD~1 <1>\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> >> > -$ git reset --soft HEAD^ ;# go back to WIP state <2>\n> >> > +$ git reset --soft HEAD~1 ;# go back to WIP state <2>\n> \n> >> People need to refer to the HEAD^ (one commit ago) much more\n> >> often than HEAD~N for larger values of N. \n> \n> I use HEAD~1 always, because I think the consistency in learning the\n> most important factor.\n> \n> It does not matter what advanced users use. The documentation should\n> primarily focus the newcomers.\n\nThat could have been an argument for disallowing the HEAD^ syntax\nentirely, but it's too late for that.\n\nEven if we eradicated all mention of ^ from the in-tree documentation,\nit would still show up in lots of out-of-tree documentation and\nexamples. So we have to introduce it to newbies. Fortunately, it isn't\nthat hard.\n\nOne way we can help them is by continuing to mix the two in examples, so\nlet's continue with the current mixture.\n\n--b.\n"},{"id":"67157","messageId":"abmj3ysj.fsf@blue.sea.net","threadId":"11820","inReplyTo":"m3d4rf7a4r.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T20:10:04Z","receivedAt":"2008-02-02T20:10:04Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Sat 2008-02-02 Jakub Narebski \n* Message-Id: m3d4rf7a4r.fsf@localhost.localdomain\n> Jari Aalto writes:\n>> I use HEAD~1 always, because I think the consistency in learning the\n>> most important factor.\n>\n> \"HEAD~1\" and \"HEAD~2\" are not shorter than original notation.\n\nI'm afreaid that \"optiomization\" is seen a virtua in the manual pages.\nI certainly do not wish to use \"shorter\", if it would mean \"less readable\"\n\nIt's certianly true that the cognitive burder to see foreign construct\nis higer than, when you can associate a thing to familiar one.\n\nHere, he familiarity from other CVSs is term HEAD or TIP, which follows\nthat\n\n HEAD~1\n\nin context of other similar ones (HEAD~2, HEAD~2 ...) is self evident\nwithout further explanations.\n\n> The documentation should cater to both advanced users and newcomers,\n\nThe advanced user's don't matter. People will become advanced over time,\nwith their own learning paths.\n\nThe documentation should prefer the most readable format. There can\nalways be separate geek manaual if needed.\n\n> IMHO the sequence: \n> \"HEAD^1\" -> \"HEAD^\", \n> \"HEAD^1^1^1\" -> \"HEAD^^^\" -> \"HEAD~3\"\n> is the proper sequence to teach.\n\nOnly from GIT perspective, if you've gwon with git. For every other\ndesigner used to the CVSs, it's the RCS/CVS/SVN temrinology and\nconcept of HEAD. Only then comes the other issues.\n\nWe don't expect to grasp the \"decentralization\", without first being\nfamiliar with older systems, so the more natural progression is:\n\n HEAD~1 -> HEAD^1 > HEAD^\n HEAD~2 -> ...\n\n> Especially that \"rev^sth\" is used also for other things, like\n> \"HEAD^{tree}\", or \"v1.3.0^{commit}\" peeling operators, or even\n> \"master^0\" used to force detach HEAD to 'master'.\n\nOnly very small grou of persons will ever need very advanced features. I\ndon't even understand what those mean and haven't have any ose for\nthose. The \"get previous version\", \"get N version backward in diff\" are\nthe 99% daily bread.\n\n>> People usually migrate to git from other VCSs, which have very\n>> consistent UI - There are no alternatives\n>> \n>> -r1:10 Subversion\n>> -r1..19 Bzr\n>> ...etc\n>> \n>> It's unfortunate is the focus is given to comments like \"easier type\",\n>> when the context is the manual pages.\n>\n> This is stupid example.\n\nIt's perfect example. The key was \"consistent UI\", which git does not\nyet have, nor does the documentation. The version numers were not my\npoint.\n\nYou really want to count this:\n\n HEAD^^^^^^^^^^^^\n\nHow many revisions again that was? That tells something about the UI.\n\n> It is also much less powerfull, as it can only follow first-parent\n> line. In the presence of merges you usually use ^n more.\n\nEverything is powerfull in git. There is no doubt about it, but there is\ndifference how \"to serve the audience\". If Git wishes, and I sincerely\nhope, that the focus is not \"advanced users\" per se.\n\n> That said, I personally don't have strong preference whether to use\n> \"HEAD\", \"HEAD^\", \"HEAD^^\", \"HEAD~3\" in examples, or \"HEAD\", \"HEAD~1\",\n> \"HEAD~2\", \"HEAD~3\". It is a bit of \"bikeshed\" discussion.\n\nI feel that this is very essence of the the path. What, if any, is the\nstrategy to develop the documentation towards. What kind of\nconversations, exmaples and notations are used to convey the content in\nuniform way to the reader.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67158","messageId":"63x73yjr.fsf@blue.sea.net","threadId":"11820","inReplyTo":"20080202161813.GA19797@fieldses.org","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T20:15:20Z","receivedAt":"2008-02-02T20:15:20Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Sat 2008-02-02 J. Bruce Fields \n* Message-Id: 20080202161813.GA19797@fieldses.org\n> On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:\n>> I use HEAD~1 always, because I think the consistency in learning the\n>> most important factor.\n>> \n>> It does not matter what advanced users use. The documentation should\n>> primarily focus the newcomers.\n>\n> That could have been an argument for disallowing the HEAD^ syntax\n> entirely, but it's too late for that.\n>\n> Even if we eradicated all mention of ^ from the in-tree documentation,\n> it would still show up in lots of out-of-tree documentation and\n> examples. So we have to introduce it to newbies. Fortunately, it isn't\n> that hard.\n>\n> One way we can help them is by continuing to mix the two in examples, so\n> let's continue with the current mixture.\n\n\nYeah let's continue as usual. And every time you need to explain the\ndifference, when you could just teach one. The is no doubt that\n\n HEAD~N\n\nis superior to\n\n HEAD^^^^^^^^^^^^^^^^^^^^^^^\n\nCount that. Optimizing keystrokes is hardly ever a brilliant idea from\nlearning perspective.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67162","messageId":"7vk5ln11vg.fsf@gitster.siamese.dyndns.org","threadId":"11820","inReplyTo":"20080202161813.GA19797@fieldses.org","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-02-02T21:31:47Z","receivedAt":"2008-02-02T21:31:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"J. Bruce Fields\" writes:\n\n>> It does not matter what advanced users use. The documentation should\n>> primarily focus the newcomers.\n>\n> That could have been an argument for disallowing the HEAD^ syntax\n> entirely, but it's too late for that.\n\nIt's not \"it's too late\" unless you are proposing to revamp git\nand to remove support for nonlinear history. With ^ and digits\nyou can name anything. With ~ and digits you cannot.\n\n> Even if we eradicated all mention of ^ from the in-tree documentation,\n> it would still show up in lots of out-of-tree documentation and\n> examples. So we have to introduce it to newbies. Fortunately, it isn't\n> that hard.\n\nJari might be thinking that absolute newbies do not do any\nmerges themselves, but even then, people need to know $commit^2\nas soon as they start to interact with a history that have any\nmerge. And people won't stay newbies forever.\n\n> One way we can help them is by continuing to mix the two in examples, so\n> let's continue with the current mixture.\n\nYeah, I am pretty much for it.\n\nHEAD~2 and upwards are very good usability enhancement compared\nto \"HEAD^^^(many uparrows...)\". The reason we accept HEAD~1 is\nnot because that is easier to type, nor easier to understand,\nnor makes you more productive. It is solely for consistency for\nthe consistency's sake.\n\nIn an introductory document, we could present things in this\norder:\n\n 1. \"HEAD^\" means the parent. It's parent is \"HEAD^^\".\n\n Side note: You read the ^ operator from right to left.\n When you see \"HEAD^^\", you read the rightmost ^ as \"the\n parent of\", and tuck the remainder to form \"the parent\n of HEAD^\".\n\n 2. You can have merges, so the above \"_the_ parent\" is a white\n lie. The other branch that was merged is HEAD^2 (the second\n parent).\n\n Side note: this means \"HEAD^\" we introduced in 1. is\n \"the first parent\"; a natural consequence of this is\n that you could also say HEAD^1 if you really wanted to\n be explicit.\n\n 3. As major parts of your history consists of a sequence of\n commits that have only single parent, you would often need\n to refer to ancestor that is Nth generation back following\n the first parent. You can of course say \"HEAD^^^^\" to mean\n the first parent of the first parent of the first parent of\n the first parent of the HEAD, but that quickly becomes\n combersome. Instead you can say HEAD~4.\n\n Side note: \"HEAD^\" we introduced in 1. is \"the first\n generation ancestor in the first parent chain\"; a\n natural consequence of this is that you could also say\n HEAD~1 if you really wanted to be explicit.\n\nBut that's for introductory document. Once people get past to\nthe stage and understand what these two notation mean, we should\nfreely use the more convenient form in the reference part of the\ndocumentation.\n"},{"id":"67163","messageId":"200802022339.47835.robin.rosenberg.lists@dewire.com","threadId":"11820","inReplyTo":"63x73yjr.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Robin Rosenberg","fromEmail":"robin.rosenberg.lists@dewire.com","sentAt":"2008-02-02T22:39:46Z","receivedAt":"2008-02-02T22:39:46Z","isPatch":true,"sender":{"key":"robin.rosenberg@dewire.com","avatar":"https://avatars.githubusercontent.com/u/46357?v=4"},"body":"lördagen den 2 februari 2008 skrev Jari Aalto:\n> Yeah let's continue as usual. And every time you need to explain the\n> difference, when you could just teach one. The is no doubt that\n> \n> HEAD~N\n> \n> is superior to\n> \n> HEAD^^^^^^^^^^^^^^^^^^^^^^^\n> \n> Count that. Optimizing keystrokes is hardly ever a brilliant idea from\n> learning perspective.\n\nYou generally do not type HEAD~largeN, defining large as 3 or more. It's \ntypically one or maybe two ^'s only. When the target is farther away you \nrefer to the SHA-1 (or abbreviated form) tag or branch name instead, just to \nmake sure you point to the right commit. 'HEAD~N' is useful for scripting and \ntesting git itself, it's an advanced feature.\n\nUI's that have only one way of accomplishing every task suck. Google this\nterm \"the case against user interface consistency\" for reasons why, in case\nyou haven't seen them for yourself.\n\n-- robin\n"},{"id":"67172","messageId":"alpine.LSU.1.00.0802030204400.7372@racer.site","threadId":"11820","inReplyTo":"abmj3ysj.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2008-02-03T02:07:04Z","receivedAt":"2008-02-03T02:07:04Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\n[don't cut the Cc' list. It is rude. _Especially_ if you cull the one \nyou are responding to. Or do you like people looking the other way when \nthey talk to you?]\n\nOn Sat, 2 Feb 2008, Jari Aalto wrote:\n\n> * Sat 2008-02-02 Jakub Narebski \n> * Message-Id: m3d4rf7a4r.fsf@localhost.localdomain\n> > Jari Aalto writes:\n> >> I use HEAD~1 always, because I think the consistency in learning the\n> >> most important factor.\n> >\n> > \"HEAD~1\" and \"HEAD~2\" are not shorter than original notation.\n> \n> I'm afreaid that \"optiomization\" is seen a virtua in the manual pages. I \n> certainly do not wish to use \"shorter\", if it would mean \"less readable\"\n\nIMO this is not just a matter of \"shorter\" or \"longer\". People familiar \nwith Git use both forms. So if you want to be able to receive help from \nGit experts, you better understand both forms.\n\nThat's why Git newbies have to learn about _both_ syntaxes right away. \nKeeping them dumb serves _noone_.\n\nCiao,\nDscho\n"},{"id":"67253","messageId":"20080203193024.GV29522@dpotapov.dyndns.org","threadId":"11820","inReplyTo":"8x235xa8.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Dmitry Potapov","fromEmail":"dpotapov@gmail.com","sentAt":"2008-02-03T19:30:24Z","receivedAt":"2008-02-03T19:30:24Z","isPatch":true,"sender":{"key":"dpotapov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6568595?v=4"},"body":"On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:\n> \n> I use HEAD~1 always, because I think the consistency in learning the\n> most important factor.\n\nPeople may have different preferences and there is nothing wrong with\nthat. However, imposing a single style on everyone is *wrong*. What you\npropose is to hide a legitimate syntax on the ground that you do not use\nit, and I don't think that is a good enough reason.\n\n> It does not matter what advanced users use. The documentation should\n> primarily focus the newcomers.\n\nWrong... and wrong again. First, this documentation is intended for all\nusers. It is not \"SVN Crash Course\" or something like that intended for\nnewcomers. Second, there is nothing wrong with having more than one way\nto express the same thing, and newcomers should be aware of that even if\nthey prefer to use HEAD~1 all the time. If you don't tell them that,\nthey may be confused when encounter it later, and they will encounter it\nsooner or later, because many of us use this ^-syntax.\n\n> Those used to git may prefer ^, but it does not follow that others\n> necessarily do so and that that should be the \"proper learning path\".\n\nIt seems to me that your \"proper learning path\" is based solely on\nwhat you prefer, and not everyone shares your preferences here. In fact,\n^-syntax is very natural to specify the _previous_ commit. Have you\nnotice we usually say \"previous\", not \"one commit before\"?\n\n> People usually migrate to git from other VCSs, which have very\n> consistent UI - There are no alternatives\n> \n> -r1:10 Subversion\n> -r1..19 Bzr\n> ...etc\n\nFirst of all, this comparison is incorrect, because SVN uses fixed\nnumbers, which does not change over time. The true equivalent of that\nnumbers in Git is SHA-1. ~N-syntax is *alternative*, which is useful\nwhen you think in relative terms, and it is rarely used with for large\nN. Second, deficiency of other SCMs is not a good enough reason for Git\nto impose the same restriction on its users.\n\nBesides, I don't know about Bzr, but SVN CLI is insane. If you need to\ndo something simple, like compare your working directory with some tag,\nyou end up typing:\n\n $ svn diff --old=A_VERY_LONG_URL/tags/tagname --new=.\n\nwith Git you can do that as simple as\n\n $ git diff tagname\n\nBefore SVN 1.4, there was no option to show the change made by some\nrevision, so you had to type: svn diff -r PREV_REV:REV. One would think\nthat after they added '-c' in SVN 1.4, no one needs to do that manually,\nbut this option does not work in one of most common case:\n\n $ svn diff -c HEAD\n svn: Non-numeric change argument given to -c\n\nso you need to figure out what is the number of the HEAD manually, and\nonly then you can use 'svn diff -c'.\n\nWith git, you can do that easily:\n $ git show\n\n\nAlso, using 'svn switch' to switch between branches is slow and painful\nas hell. First, you have to type A_VERY_LONG_URL and if you happen to\nforgot to check in some changes, you end up with completely mess in your\nworking directory. 'git checkout' has much more consistent behavior, and\nit does not destroy your work...\n\n\nSo, IMNSHO, recent versions of Git is way easier to use than SVN even\nin those cases where SVN provides similar functionality...\n\n\n\nDmitry\n"},{"id":"67280","messageId":"bq6x38lc.fsf@blue.sea.net","threadId":"11820","inReplyTo":"20080203193024.GV29522@dpotapov.dyndns.org","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-03T23:48:15Z","receivedAt":"2008-02-03T23:48:15Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Sun 2008-02-03 Dmitry Potapov \n* Message-Id: 20080203193024.GV29522@dpotapov.dyndns.org\n> ^-syntax is very natural to specify the _previous_ commit. Have you\n> notice we usually say \"previous\", not \"one commit before\"?\n\nOnly if you're grown with git. Everywhere else the concept of HEAD or\nTIP is more natural, thus progression:\n\n HEAD, HEAD~1, HEAD~2\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67292","messageId":"m3hcgp5zvs.fsf@localhost.localdomain","threadId":"11820","inReplyTo":"bq6x38lc.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-04T00:28:16Z","receivedAt":"2008-02-04T00:28:16Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto writes:\n\n> * Sun 2008-02-03 Dmitry Potapov \n> * Message-Id: 20080203193024.GV29522@dpotapov.dyndns.org\n>>\n>> ^-syntax is very natural to specify the _previous_ commit. Have you\n>> notice we usually say \"previous\", not \"one commit before\"?\n\nAnd you usually say \"yesterday\", \"the day before\" and not \"1 day ago\",\n\"2 days ago\".\n\n^ means (first) parent of commit-ish , or 'previous' commit.\n~N means Nth parent in first-parent line of commit-ish ; as\nyou can see full explanation is decidely longer.\n\n> Only if you're grown with git. Everywhere else the concept of HEAD or\n> TIP is more natural, thus progression:\n> \n> HEAD, HEAD~1, HEAD~2\n\nThe fact that other SCMs are poorer in expressive power doesn't mean\nthat we have to bend backwards and follow (well, not braindamaged,\njust poor) other SCM limitations / conventions. Git is git is git :-)\n\nSo \"everywhere else\" doesn't matter any... unless in \"SCM rosetta\" or\nsomething like that chapter in Git User's Manual.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67441","messageId":"20080204223350.GA30368@dpotapov.dyndns.org","threadId":"11820","inReplyTo":"bq6x38lc.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)","fromName":"Dmitry Potapov","fromEmail":"dpotapov@gmail.com","sentAt":"2008-02-04T22:33:50Z","receivedAt":"2008-02-04T22:33:50Z","isPatch":true,"sender":{"key":"dpotapov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6568595?v=4"},"body":"On Mon, Feb 04, 2008 at 01:48:15AM +0200, Jari Aalto wrote:\n> * Sun 2008-02-03 Dmitry Potapov \n> * Message-Id: 20080203193024.GV29522@dpotapov.dyndns.org\n> > ^-syntax is very natural to specify the _previous_ commit. Have you\n> > notice we usually say \"previous\", not \"one commit before\"?\n> \n> Only if you're grown with git.\n\nHmm... I always thought that the word \"previous\" existed well before Git...\n\n> Everywhere else the concept of HEAD or\n> TIP is more natural,\n\nHow so?\n\n> thus progression:\n> \n> HEAD, HEAD~1, HEAD~2\n\nNon sequitur.\n\n\n\nDmitry\n"}]}