Can somebody explain the usage of git range-diff?

Question

Git version 2.19 introduces git range-diff which is supposed to be used in order to compare two commit ranges. I have been reading the documentation, but I cannot get what is the purpose of this new features.

I checked the official Git documentation, and I have trouble understanding its syntax (omitting flags):

git range-diff ( <range1> <range2> | <rev1>...​<rev2> | <base> <rev1> <rev2> )

What is rev1 and rev2?

Could somebody explain when they are useful I mean each case?

Answer 1

I have not actually used them yet, but they are meant as an improvement over the old git cherry* flow for analysing / comparing some upstream or downstream change-set vs what you have now. To make the range-sets useful we want some set of "here are my commits" and "here are theirs", expressed as simply as possible.

A range1 range2 set would be written as, e.g.:

git range-diff theirs~5..theirs ours~4..ours

if you had, e.g.:

          T1--T2--T3--T4--T5   <-- theirs
         /
...--o--*   <-- base
         \
          O1--O2--O3--O4   <-- ours

where the O commits are "ours" and the T commits are "theirs".

Given this exact same configuration, however, we could also write:

git range-diff theirs...ours    # or ours...theirs

(note the three dots). (This is the syntax used with git rev-list --cherry-mark --left-right, for instance.)

Or, again given this same situation, we could write:

git range-diff base theirs ours   # or base ours theirs

Here base is the stop point for both theirs and ours, and avoids having to count back 5.

If the situation is more complicated—as in the graph:

          X1--T1--T2--T3   <-- theirs
         /
...--o--*   <-- base
         \
          Y1--Y2--O1--O2--O3--O4   <-- ours

neither the three-dot nor the base ours theirs kind of syntax quite works, so the two sets of ranges (theirs~3..theirs ours~4..ours) would be best.