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

From: Junio C Hamano <[email-masked]>
Date: Sat, 28 Mar 2020 18:34:14 -0700

"Philippe Blain via GitGitGadget" <[email-masked]> writes:

> From: Philippe Blain <[email-masked]>
>
> `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.

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

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, and
I initially was hoping that the second hunk of this patch was such a
change, but it appears that it is not (it just adds the misleading
"you can have more than one" without making readers aware of what it
means to write "A..B C..D").

Thanks.