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

> On 13/06/21 07.44, Felipe Contreras wrote:
> > The original explanation didn't seem clear enough to some people.
> > 
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >   Documentation/revisions.txt | 22 +++++++++++-----------
> >   1 file changed, 11 insertions(+), 11 deletions(-)
> > 
> > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> > index f5f17b65a1..d8cf512686 100644
> > --- a/Documentation/revisions.txt
> > +++ b/Documentation/revisions.txt
> > @@ -299,22 +299,22 @@ empty range that is both reachable and unreachable from HEAD.
> >   
> >   Commands that are specifically designed to take two distinct ranges
> >   (e.g. "git range-diff R1 R2" to compare two ranges) do exist, but
> > -they are exceptions.  Unless otherwise noted, all "git" commands
> > +they are exceptions.  Unless otherwise noted, all git commands
> >   that operate on a set of commits work on a single revision range.
> > -In other words, writing two "two-dot range notation" next to each
> > -other, e.g.
> >   
> > -    $ git log A..B C..D
> > +For example, if you have a linear history like this:
> >   
> > -does *not* specify two revision ranges for most commands.  Instead
> > -it will name a single connected set of commits, i.e. those that are
> > -reachable from either B or D but are reachable from neither A or C.
> > -In a linear history like this:
> > +    ---A---B---C---D---E---F
> >   
> > -    ---A---B---o---o---C---D
> > +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.
> 
> AFAIK, A..F means all commits from A to F. But in case of branched 
> history like
> 
>      ---A---B---C---G---H---I <- main
>                 \
>                  ---D---E---F <- mybranch
> 
> the notation main..mybranch means all commits that are reachable from 
> mybranch but not from main, but the opposite (mybranch..main) means the 
> opposite!
> 
> So basically the right-hand side of two dot notation specifies from what 
> commit I want to select the range, and the left-hand side specifies the 
> commit which I don't want to reach.