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

[Shawn Bohrer <shawn.bohrer@gmail.com>]

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