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

[Junio C Hamano <gitster@pobox.com>]

"J. Bruce Fields" <bfields@fieldses.org> writes:

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

It's not "it's too late" unless you are proposing to revamp git
and to remove support for nonlinear history.  With ^ and digits
you can name anything.  With ~ and digits you cannot.

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

Jari might be thinking that absolute newbies do not do any
merges themselves, but even then, people need to know $commit^2
as soon as they start to interact with a history that have any
merge.  And people won't stay newbies forever.

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

Yeah, I am pretty much for it.

HEAD~2 and upwards are very good usability enhancement compared
to "HEAD^^^(many uparrows...)".  The reason we accept HEAD~1 is
not because that is easier to type, nor easier to understand,
nor makes you more productive.  It is solely for consistency for
the consistency's sake.

In an introductory document, we could present things in this
order:

 1. "HEAD^" means the parent.  It's parent is "HEAD^^".

        Side note: You read the ^ operator from right to left.
        When you see "HEAD^^", you read the rightmost ^ as "the
        parent of", and tuck the remainder to form "the parent
        of HEAD^".

 2. You can have merges, so the above "_the_ parent" is a white
    lie.  The other branch that was merged is HEAD^2 (the second
    parent).

        Side note: this means "HEAD^" we introduced in 1. is
        "the first parent"; a natural consequence of this is
        that you could also say HEAD^1 if you really wanted to
        be explicit.

 3. As major parts of your history consists of a sequence of
    commits that have only single parent, you would often need
    to refer to ancestor that is Nth generation back following
    the first parent.  You can of course say "HEAD^^^^" to mean
    the first parent of the first parent of the first parent of
    the first parent of the HEAD, but that quickly becomes
    combersome.  Instead you can say HEAD~4.

        Side note: "HEAD^" we introduced in 1. is "the first
        generation ancestor in the first parent chain"; a
        natural consequence of this is that you could also say
        HEAD~1 if you really wanted to be explicit.

But that's for introductory document.  Once people get past to
the stage and understand what these two notation mean, we should
freely use the more convenient form in the reference part of the
documentation.