"J. Bruce Fields" <bfields@xxxxxxxxxxxx> 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.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
