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

From: Jakub Narebski <jnareb@gmail.com>
Date: Feb 2, 2008, 13:37 UTC
Message-ID: <m3d4rf7a4r.fsf@localhost.localdomain>
In-Reply-To: <8x235xa8.fsf@blue.sea.net>

Jari Aalto <jari.aalto@cante.net> writes:

Show 15 quoted lines

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

I think that focusing on the fact that "HEAD^1" is peel-like operator,
selecting first parent of HEAD, That "HEAD^" is a shortcut for that,
and that "HEAD~3" is a shortcut for "HEAD^^^" similarly to how "3 * 2"
is a shortcut for "2 + 2 + 2" is better solution. "HEAD~1" and
"HEAD~2" are not shorter than original notation.

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

The documentation should cater to both advanced users and newcomers, unless it is specifically targeted towards newcomers like different intro documentation, or first part of Git User's Manual.

Show 12 quoted lines

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

IMHO the sequence: 
  "HEAD^1"     -> "HEAD^", 
  "HEAD^1^1^1" -> "HEAD^^^" -> "HEAD~3"
is the proper sequence to teach.

Especially that "rev^sth" is used also for other things, like "HEAD^{tree}", or "v1.3.0^{commit}" peeling operators, or even "master^0" used to force detach HEAD to 'master'.

Show 9 quoted lines

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

This is stupid example. Numbering revisions is possible only in centralized SCMs, or semi-centralized SCMs (with one repository given special, central position). You need an authority to assign sequential numbers to revisions.

Besides git uses the same notation, <rev1>..<rev2>, only it doesn't need '-r' option to select revision or revision range.

Show 7 quoted lines

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

It is also much less powerfull, as it can only follow first-parent line. In the presence of merges you usually use ^n more.

That said, I personally don't have strong preference whether to use "HEAD", "HEAD^", "HEAD^^", "HEAD~3" in examples, or "HEAD", "HEAD~1", "HEAD~2", "HEAD~3". It is a bit of "bikeshed" discussion.

-- 
Jakub Narebski

  In related news: there is really no question that bike sheds should
  be painted red. Really. (Johannes Schindelin)