git-reset.txt: Use uniform HEAD~N notation in all examples
PATCH 1/1 git-reset.txt: Use uniform HEAD~N notation in all examples
The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in examples. This may be xconfusing to new users. The "counting" notation HEAD~N likely to be grasped more easily because it allow successive numbering 1, 2, 3 etc.
--- Documentation/git-reset.txt | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-)
Documentation/git-reset.txt +3 -3
@@ -55,7 +55,7 @@ Undo a commit and redo:: + ------------ $ git commit ... -$ git reset --soft HEAD^ <1> +$ git reset --soft HEAD~1 <1> $ edit <2> $ git commit -a -c ORIG_HEAD <3> ------------
@@ -77,7 +77,7 @@ $ git commit ... $ git reset --hard HEAD~3 <1> ------------ + -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad and you do not want to ever see them again. Do *not* do this if you have already given these commits to somebody else.
@@ -162,7 +162,7 @@ $ git checkout master $ fix fix fix $ git commit ;# commit with real log $ git checkout feature -$ git reset --soft HEAD^ ;# go back to WIP state <2> +$ git reset --soft HEAD~1 ;# go back to WIP state <2> $ git reset <3> ------------ +
Signature · 6 lines
1.5.3.rc5 -- Welcome to FOSS revolution: we fix and modify until it shines
Quoted 4 lines · Jari Aalto
The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in examples. This may be xconfusing to new users. The "counting" notation HEAD~N likely to be grasped more easily because it allow successive numbering 1, 2, 3 etc.
I am mildly negative on this change.
Referring to (rather, "having to refer to" to fix mistakes) the previous commit happens far more often than referring to an ancestor of an arbitrary generation away (i.e. HEAD~$n). I think it is a better idea to expose users early on that HEAD^ notation which is shorter to type.
Quoted 7 lines · Junio C Hamano
Quoted 4 lines · Jari Aalto
The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in examples. This may be xconfusing to new users. The "counting" notation HEAD~N likely to be grasped more easily because it allow successive numbering 1, 2, 3 etc.
Quoted 7 lines
I am mildly negative on this change.
Referring to (rather, "having to refer to" to fix mistakes) the previous commit happens far more often than referring to an ancestor of an arbitrary generation away (i.e. HEAD~$n). I think it is a better idea to expose users early on that HEAD^ notation which is shorter to type.
If the page contains/combines many different ways of doing things, this creates confusion, especially if the distictions are not explained. And it would be unnecessary to explain the HEAD^ and HEAD~1 similarities in every page where these two get mixed.
PRICPLES:
1. The novice user is best served by making things simple and uniform.
2. Utilize concepts that may already be familar. E.g. other VCS/SCM tools have concept of counting back revisions with negative numbers: -1, -2, -3; so following this same idea in git manual pages would already rang associated bells.
Like:
HEAD, HEAD~1, HEAD~2
If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.
HEAD, HEAD^, HEAD~2
I'm sure when user progresses with his learning, the differences or similarities of the notations become no-op.
But manual pages are served for wide audience. They are most important to new users.
I hope we could strive for KISS is possible.
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 9 lines · Jari Aalto
Like:
HEAD, HEAD~1, HEAD~2If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.
HEAD, HEAD^, HEAD~2
I still would prefer to teach people HEAD^ earlier. If you _REALLY_ insist, I can live with spelling the HEAD~2 as HEAD^^ for consistency.
Wasn't with you that earlier I discussed that very basic things such as revision naming and range notation should be moved from rev-list documentation to more central place, and sructure the documentation in such a way that these should be read even before individual manual pages are consulted? If we follow that, then by the time people read these examples, they _ought_ to know that HEAD~1 is a longer-to-type way to say HEAD^ already.
Quoted 16 lines · Junio C Hamano
Quoted 9 lines · Jari Aalto
Like:
HEAD, HEAD~1, HEAD~2If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.
HEAD, HEAD^, HEAD~2I still would prefer to teach people HEAD^ earlier. If you _REALLY_ insist, I can live with spelling the HEAD~2 as HEAD^^ for consistency.
Quoted 7 lines
Wasn't with you that earlier I discussed that very basic things such as revision naming and range notation should be moved from rev-list documentation to more central place, and sructure the documentation in such a way that these should be read even before individual manual pages are consulted? If we follow that, then by the time people read these examples, they _ought_ to know that HEAD~1 is a longer-to-type way to say HEAD^ already.
Well I am a new user to git and I didn't find the mixed notation confusing at all. Perhaps this is because I read the tutorial first, then the git user manual which both explain this clearly.
In either case I think eliminating either notation from the man pages is a bad idea. I'm quite confident that in the worst case a user will think that if they want to refer to the parent they have to say HEAD^ and if they want to refer to the grandparent they have to say HEAD~2. Most won't even find that strange since HEAD^ just seems shorter. I also think many users will be smart enough to infer that if they wanted to they could say HEAD~3 or perhaps HEAD~1, though unless I saw it somewhere I might not have guessed HEAD^^.
Quoted 14 lines · Shawn Bohrer
Quoted 12 lines · Junio C Hamano
Quoted 9 lines · Jari Aalto
Like:
HEAD, HEAD~1, HEAD~2If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.
HEAD, HEAD^, HEAD~2
Quoted 7 lines
Quoted 3 lines
I still would prefer to teach people HEAD^ earlier. If you _REALLY_ insist, I can live with spelling the HEAD~2 as HEAD^^ for consistency.
Well I am a new user to git and I didn't find the mixed notation confusing at all. Perhaps this is because I read the tutorial first, then the git user manual which both explain this clearly.
Naturally one's learning path is naturally different. Did you come from other SCM/VCS before intorduced to git?
Quoted 2 lines
In either case I think eliminating either notation from the man pages is a bad idea.
That was not proposed. There a mnay pages that use and shoudl use the ^ notations. I was proposing that only (git-COMMAND) were dealt with.
After all, the ^ very differento to what other SCM/VCSs use.
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 1 line · Jari Aalto
After all, the ^ very differento to what other SCM/VCSs use.
It's something I _constantly_ wished other SCM/VCSs had, as it's far, far, more usable than the typical absolute rev numbers. It really should be introduced as early as possible.
-Miles
Signature · 1 line
Fast, small, soon; pick any 2.