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

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

Eric Sunshine wrote:
> On Sat, Jun 12, 2021 at 8:44 PM Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
> > The original explanation didn't seem clear enough to some people.
> >
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> > @@ -299,22 +299,22 @@ empty range that is both reachable and unreachable from HEAD.
> > +For example, if you have a linear history like this:
> >
> > +    ---A---B---C---D---E---F
> >
> > +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. Instead the starting point A gets overriden by B,
> > +and the ending point of E by F, effectively becoming B..F, a single
> > +revision range.
> 
> s/overriden/overridden/
> 
> 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?

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?

 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?

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

-- 
Felipe Contreras