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

From: Elijah Newren <newren@gmail.com>
Date: Jun 13, 2021, 07:02 UTC
Message-ID: <CABPp-BE4r=Nhw2sJS++7Eh1K5rpyWgg+f8vDTf92JBayt1B_cA@mail.gmail.com>
In-Reply-To: <60c588d452750_3d86c2085c@natae.notmuch>

On Sat, Jun 12, 2021 at 9:25 PM Felipe Contreras <felipe.contreras@gmail.com> wrote:

Show 27 quoted lines

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

I tend to agree with Eric. I think the example you chose is likely to be misinterpreted and your wording magnifies it. A..F B..E simplifies to B..F which is *almost* the union of A..F and B..E, it's only missing A. Off-by-one errors are easy to miss. You make it more likely that they'll miss it, because there are only 6 commits total in the union, and you are trying to explain why listing A..F B..E while not be 8 commits, which readers can easily respond with, "Well, of course it's not 8 commits. There's only 6. When you do the union operation, of course the duplicates go away", and miss the actual point that A got excluded.

Junio's wording and example just seemed better to me here.

Show 29 quoted lines

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