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 cann

Answer 1

Range diff becomes very useful right after resolving merge conflicts (after rebase, cherry-pick, etc.),
especially when you had multiple conflicting commits, and you want to make sure that you haven't accidentally broken something during the process.

Here is a scenario usually happens in case you are doing multiple commits in a branch.
Let's say we have a branch called "our", and our branch is behind the master branch:

m1-m2-m3-m4  <- "master" branch
  \
   o1-o2-o3  <- "our" current branch

Before rebasing we do a backup of our branch (just made a copy branch with a name "our_bkp")

git branch our_bkp

And now we initiate rebasing with the master

git rebase master

And solve some merge conflicts on the commit "o1"...
Note: If the conflicting files on the "o1" were also used/changed in "o2" or "o3",
then we'll have to re-resolve the same merge conflicts on them as well.

Now, let's say, after an exhausting rebase process we have something like this:

             _<- branch "master"
            /
 m1-m2-m3-m4-o1'-o2'-o3'  <- branch "our" (after rebase)
  \
   o1-o2-o3   <- branch "our_bkp"
   

Since there were many merge conflicts, it's not clearly visible whether we've missed something or not.

And this is where the range-diff shines.

To make sure that we haven't missed any change or accidentally damaged anything, we can simply compare our commits from the old version of the branch with the newer version:

git range-diff our_bkp~3..our_bkp our~3..our

or

git range-diff o1..o3 o1'..o3'

If the diffs are only related to the conflicting parts, then we are good, and haven't changed anything other than them.
But if we see some other unexpected diffs, then we or git did something wrong, and we'll need to fix them.

Notes

• Both of the range-diff commands above are doing exactly the same thing.
• By saying o1..o3 I mean the numbers of those commits, e.g.: 0277a5883d132bebdb34e35ee228f4382dd2bb7..e415aee3fa53a213dc53ca6a7944301066b72f24
• The ~3 in our_bkp~3 says git to take the commit that was 3 commits before the last one on our_bkp branch. Replace the number with the amount of the commits you had on your branch and ofcourse don't forget to replace the branch name our_bkp with you'r backup branch's name.
• You can consider the range-diff as doing a diff of two diff-s. This way it'll be easier to remember and understand what it's doing.