Re: [PATCH] doc: log takes multiple revision ranges

[Philippe Blain <levraiphilippeblain@gmail.com>]

Hi Junio, 
> Le 28 mars 2020 à 21:34, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> 
>> `git log` accepts multiple revision ranges, but makes no mention of that
>> in its documentation. Currently readers have to go to the `git
>> rev-list` documentation to discover this useful feature.
> 
> I have a mixed feeling about this change.  Surely you can write
> 
> 	git log   v1.0..v2.0   v4.0..v5.0 -- Makefile
> 
> and you can explain that the command appears to take two "ranges",
> but I do not think we want to encourage it to those who do not
> understand what the above actually *means*.  
> 
> Specifially, it does *NOT* list commits between v1.0 and v2.0, or
> between v4.0 and v5.0, that touch the path Makefile.  In other
> words, you didn't really give two ranges with the syntax.  What the
> A..B notation means could be called a range, only when it appears
> alone.
> 
> And we have *no* intention of changing the semantics.

Of course, I understand.

> 
> "A..B" is a mere short-hand for ^A B, and it may appear to be a
> range, but "A..B C..D" does not make "two ranges".  It still merely
> is a short-hand for ^A B ^C D, and if C reaches A and B (in the
> above example, v4.0 is very likely to reach both v1.0 and v2.0), it
> means the same thing as "C..D", i.e. "git log v4.0..v5.0 -- Makefile".

Yes, you are right.

> 
> So I have a mildly strong opinion against the change to the synopsys
> and the short-help; it is a bad change that does not help users.  If
> there are not sufficient explanation on the equivalence between A..B
> and ^A B on "git log" documentation but there is one elsewhere, adding
> a reference to help users learn is very much appreciated, though,

So the 'git log' documentation states: 

    origin..HEAD specifies all the commits reachable from the current commit 
    (i.e. HEAD), but not from origin. For a complete list of ways to spell <revision range>, 
    see the Specifying Ranges section of gitrevisions[7].

What I wanted to achieve with this patch is to make readers aware that 
they can write e.g.

    git log branch1 branch2 branch3 branch4 --not master

to see commits on each of branch1-4, that are not on master, 
since this is not immediately obvious (at least to me)
in the 'git log' man page. Even following the link to gitrevisions[7], 
it is not explicitly mentioned in the "Specifying Ranges" section 
that a range denotes the set of all commits reachable by all given refs, 
minus the ones reachable by all given refs prefixed by '^' or '--not'.
However, this is really clear in the 'git rev-list' documentation, 
which uses  '<commit>...' in the synopsis
and clearly talks about the "set of commits" point of view:

    You can think of this as a set operation. Commits given on the command line form 
    a set of commits that are reachable from any of them, and then commits reachable 
    from any of the ones given with ^ in front are subtracted from that set. The remaining 
    commits are what comes out in the command’s output. Various other options and 
    paths parameters can be used to further limit the result.

Do you think it would be appropriate that this explanation could somehow also appear 
in the 'git log' (and maybe also 'gitrevisions') documentation ?

Thanks for the quick feedback,
Philippe.