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

[Jakub Narebski <jnareb@gmail.com>]

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

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

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

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

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