[PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[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.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-reset.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 15e3aca..c42cd26 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -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>
 ------------
 +
-- 
1.5.3.rc5



-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> 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.

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> 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.

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.

-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> 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 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.

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Shawn Bohrer]

On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:
> Jari Aalto <jari.aalto@cante.net> writes:
> 
> > 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 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.

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^^.

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Jari Aalto]

Shawn Bohrer <shawn.bohrer@gmail.com> writes:

> On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:
>
>> Jari Aalto <jari.aalto@cante.net> writes:
>> 
>> > 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 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?

> 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

-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

[Miles Bader]

Jari Aalto <jari.aalto@cante.net> writes:
> 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

-- 
Fast, small, soon; pick any 2.