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

From: Shawn Bohrer <shawn.bohrer@gmail.com>
Date: Sep 1, 2007, 15:01 UTC
Message-ID: <20070901150153.GD7422@mediacenter.austin.rr.com>
In-Reply-To: <7vabs6u3jt.fsf@gitster.siamese.dyndns.org>

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

Show 23 quoted lines

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