Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)

From: Jari Aalto <jari.aalto@cante.net>
Date: Feb 2, 2008, 12:59 UTC
Message-ID: <8x235xa8.fsf@blue.sea.net>
In-Reply-To: <20080202084406.GA15305@glandium.org>

* Sat 2008-02-02 Mike Hommey <mh@glandium.org> gmane.comp.version-control.git
* Message-Id: 20080202084406.GA15305@glandium.org

Show 7 quoted lines

>> 
>> > -$ git reset --soft HEAD^      <1>
>> > +$ git reset --soft HEAD~1     <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
>> > -$ git reset --soft HEAD^ ;# go back to WIP state  <2>
>> > +$ git reset --soft HEAD~1 ;# go back to WIP state <2>

>> People need to refer to the HEAD^ (one commit ago) much more
>> often than HEAD~N for larger values of N.

I use HEAD~1 always, because I think the consistency in learning the most important factor.

It does not matter what advanced users use. The documentation should primarily focus the newcomers.

The first question a newbie asks, if manual pages mixes syntaxes:

    What the heck "^" ?. I just saw HEAD~N, is the other one somehow
    special?

All the other examples refer to

    HEAD~N

Those used to git may prefer ^, but it does not follow that others necessarily do so and that that should be the "proper learning path". People usually migrate to git from other VCSs, which have very consistent UI - There are no alternatives

    -r1:10      Subversion
    -r1..19     Bzr
    ...etc

It's unfortunate is the focus is given to comments like "easier type", when the context is the manual pages.

>> Especially about HEAD~1, nobody sane would type that.

You consider all such users insane? It actually helps to select onlyt one sytax, and HEAD~N is much more readable without further explanations, (becasue people are already used to knowing, from other VCSs, what a HEAD or TIP is). It's not all that different from prefering the "--quiet" over "-q" e.g. e.g. in shell scripts.

Jari

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