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

On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:

Jari Aalto [off-list ref] writes:

quoted

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