Re: [PATCH 3/3] range-diff(docs): explain how to specify commit ranges

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 28, 2021, 05:43 UTC
Message-ID: <xmqqim7hy5te.fsf@gitster.c.googlers.com>
In-Reply-To: <nycvar.QRO.7.76.6.2101270357480.57@tvgsbejvaqbjf.bet>

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Show 7 quoted lines

>> The above paragraph says A...B is turned into $(git merge-base A
>> B)..A and $(git merge-base A B)..B, but I wonder if we should be
>> rewriting it into A..B and B..A instead; that would make it
>> unnecessary to explain what should happen when there are more than
>> one merge bases.
>
> You know what? I lied.

I knew.  So we need an update to the patch.

Show 11 quoted lines

>> >> Does this merely resemble?  Isn't it exactly what a symmetric range is?
>> >
>> > No, it is not exactly what a symmetric range is because `range-diff`
>> > treats both arms of the symmetric range independently, as two distinct
>> > non-symmetric ranges.
>>
>> This however is an end-user documentation, isn't it?
>
> Yes, and the end user is talking about _two_ commit ranges in the context
> of `git range-diff`, and about _one_ commit range in the context of `git
> log`.

You are forgetting that "log A...B" shows only one half of what a symmetric range means, and hides which side each commit belongs to.

"git log --left-right A...B" shows what a symmetric range really is; there are two sides, left and right, and "git range-diff A...B" is a natural way to compare these two ranges.

I've been quite happy with the way how "git range-diff @{-1}..." shows the comparison of two sides of the symmetric range, given by "git log --oneline --left-right @{-1}..."