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

[Felipe Contreras <felipe.contreras@gmail.com>]

Eric Sunshine wrote:
> 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.

Yes, but the documentation is not for you, it's for the majority of
users, so it behooves to try to understand the reason to see if it
applies to the population in general.

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

At this point the _why_ has not been explained, merely that these two
things don't result in 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.

I wonder why that is the case. A..F is so simple it doesn't have to be
explained, Ruby even expands that obvious range.

  ---A---B---C---D---E---F
     ^                   ^
    from                 to

And B..E:

  ---A---B---C---D---E---F
         ^           ^
        from         to

In Ruby the range can be defined simply as: 'A'..'F'

  ["A", "B", "C", "D", "E", "F"]

Would 1..6 be easier to picture?

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

If I say Lucy is available from 1 to 6 p.m. and Michael from 2 to 5 p.m.
why would 2 p.m supersede 1 p.m.?

If we are trying to define a starting point, obviously the latest
starting point is the one that wins. No?

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

The text starts with *for example*. Therefore it's not something
general, it's an example.

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

Junio's explanation is inaccurate because it stated that this:

 Unless otherwise noted, all git commands that operate on a set of
 commits work on a single revision range.

Is the same as this:

 writing two "two-dot range notation" next to each does *not* specify
 two revision ranges for most commands.

But it is not the same.

Can you tell me why?

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

The text never mentioned any rule.

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

Keep reading.

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

Or maybe it's something that only applies to you.

Cheers.

-- 
Felipe Contreras