Re: [PATCH] doc: revisions: improve single range explanation

[Eric Sunshine <sunshine@sunshineco.com>]

On Sun, Jun 13, 2021 at 12:26 AM Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> Eric Sunshine wrote:
> > For what it's worth, as a person who is far from expert at revision
> > ranges, I had to read this revised text five or six times and think
> > about it quite a bit to understand what it is saying,
>
> Can you explain why?

Probably not to a degree which will satisfy you. And I'm not being
flippant by saying that. I mean only that it is more than a little
difficult to explain why one thing "clicks" easily in the brain while
something else doesn't. I can only relate (to some extent) what I
experienced while reading your revised text.

> This is the context: commands don't generally take two ranges:
>
>  1. Unless otherwise noted, all git commands that operate on a set of
>     commits work on a single revision range.
>
>  2. Doing A..F will retrieve 5 commits, and doing B..E will retrieve 3
>     commits, but doing A..F B..E will not retrieve two revision ranges
>     totalling 8 commits.
>
> At this point what isn't clear? Isn't it clear that `A..F B..E` aren't
> two revision ranges?

The documentation stating explicitly that `A..F B..E` is not two
ranges is fine. What was difficult to understand was your explanation
of _why_ those are not two ranges. In contrast, I had no difficulty
understanding Junio's explanation of why that is not two ranges.

>  3. Instead the starting point A gets overridden by B, and the ending
>     point of E by F, effectively becoming B..F, a single revision range.
>
> What isn't clear about that? A gets superseded by B because it's higher
> in the graph. And if you do `git log D E F` it's clear that doing
> `git log F` will get you the same thing, isn't it?

One of the reasons I had to re-read your text so many times was
because it was difficult to build a mental model of what you were
saying, and to follow along with all the "this replaces that" and
"this other thing replaces that other thing". While doing so, I
repeatedly had to glance back at the original `A..F B..E` to make sure
the mental model I was building was correct or still made sense. The
word "overridden" didn't help because I couldn't tell if, by
"overridden", you meant that something got replaced by something else
or if something was merely ignored. (Or maybe those are the same thing
in this case, but how will a newcomer -- who is trying to learn this
from scratch -- know which it is?)

However, an even bigger problem I experienced while reading your
revised text is that it felt like it was trying to express some rule
which the reader should internalize ("replace this with that, and
replace this other thing too") with no proper explanation of _why_ the
rule works that way. Worse, the rule (whatever it is) never actually
materialized or solidified in a way which I could understand and thus
apply to in other situations. Junio's explanation, on the other hand,
was simple and to the point, and (for whatever reason) clicked easily
in my brain, such that I came away feeling that I could apply the
knowledge immediately to other situations. On the other hand, after
reading your proposed text, I did not feel as if I had gained any
knowledge, and even had I picked up the rule which seems to be in
there, I likely still wouldn't have understood _why_ that rule works
or is needed; it would just have been some black box.

> > Also, if this explanation is aimed at newcomers, then saying only
> > "doing A..F will retrieve 5 commits" without actually saying _which_
> > commits those are is perhaps not so helpful.
>
> It doesn't matter which specific commits are retrieved, the only thing
> that matters is that `X op Y` is not additive.

The very first question which popped into my head upon reading "Doing
A..F will retrieve 5 commits" was "which five commits?". Not being
told the answer by the text did not help me feel confident that I knew
the correct five commits. Had the text stated explicitly "the five
commits B, C, D, E, F", then there would be no question and no feeling
of uncertainty about it. So, whatever precision your above statement
might have, it is likely to be lost on the general newcomer who is
simply trying to learn about and understand Git revisions.