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

["J. Bruce Fields" <bfields@fieldses.org>]

On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:
> * Sat 2008-02-02 Mike Hommey <mh@glandium.org> gmane.comp.version-control.git
> * Message-Id: 20080202084406.GA15305@glandium.org
> >> 
> >> > -$ 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.

That could have been an argument for disallowing the HEAD^ syntax
entirely, but it's too late for that.

Even if we eradicated all mention of ^ from the in-tree documentation,
it would still show up in lots of out-of-tree documentation and
examples.  So we have to introduce it to newbies.  Fortunately, it isn't
that hard.

One way we can help them is by continuing to mix the two in examples, so
let's continue with the current mixture.

--b.