From: Felipe Contreras Date: Sun, 13 Jun 2021 04:25:56 GMT Subject: Re: [PATCH] doc: revisions: improve single range explanation Message-ID: <60c588d452750_3d86c2085c@natae.notmuch> In-Reply-To: Eric Sunshine wrote: > On Sat, Jun 12, 2021 at 8:44 PM Felipe Contreras > wrote: > > The original explanation didn't seem clear enough to some people. > > > > Signed-off-by: Felipe Contreras > > --- > > 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