Why should you care about git range-diff?
When I first started my career, I was terrified of rebase-ing branches with long histories. After resolving conflicts, I’d usually break into a cold sweat. My biggest fear was accidentally deleting a colleague’s critical logic or making my own code vanish.
Typically, we use git diff to double-check after a rebase. However, this command shows a “forest” of changes, including the latest code from the main branch. It becomes very difficult to distinguish between the code you just edited and the code inherited from the base branch.
In my team of eight, after implementing a git range-diff check before a force push, the rate of logic errors caused by sloppy rebasing dropped by over 70%. The team also became much more confident when handling complex features.
Limitations of the old way
Imagine you are working on a feature while the main branch has gained 10 new commits. You perform a git rebase main and have to resolve conflicts. Now, a big question arises: “Are my commit contents still the same as they were before the rebase?”
- git diff: Only compares the final state (snapshot). The results are heavily cluttered by new code from main.
- git log: Shows history but doesn’t help you see the detailed differences between two versions of the same set of commits.
This is exactly where git range-diff shines. Instead of comparing files, it compares the patches of each individual commit against one another.
Checking your Git version
You don’t need to install any third-party tools. Git has included this feature since version 2.19 (released in 2018). Most modern development environments are well beyond this version.
Check your version with the following command:
git --versionIf your version is lower than 2.19, you should update immediately. Additionally, enable UI colors to make the results easier to read:
git config --global color.ui truePractical usage
The principle of this command is to compare two commit ranges. We will compare the “old” feature branch (before rebase) and the “new” feature branch (after rebase).
1. Always create a backup before rebasing
I always create a temporary branch or a tag to mark the old state. This only takes 2 seconds but can save you in dire situations.
# Mark the state before rebasing
git branch feature-backup
# Perform rebase
git rebase main
# Compare old and new versions
git range-diff main feature-backup featureThe above command tells Git: “Compare the changes from main to feature-backup with the changes from main to feature“.
2. Understanding the symbols
When the results appear on the screen, pay attention to the symbols at the beginning of the lines. They are the key to knowing if you’ve broken the code:
=: Commits are exactly the same. This is the ideal state.<: Commit only appears in the old range (perhaps you squashed commits).>: Commit only appears in the new range.!: Commit content has changed. This usually happens when you intervene while fixing conflicts.
For example, if I edit the auth.service.ts file and accidentally break the logic:
1: a1b2c3d = 1: e5f6g7h Add login logic
2: i9j0k1l ! 2: m3n4o5p Fix email validation error
@@ -10,5 +10,7 @@
- if (email === '')
+ if (!validateEmail(email))
++ console.log('Forgot to delete this line');
return false;The ! sign and the ++ line warn that I accidentally left a console.log statement. Without range-diff, this redundant line would have surely made its way into production.
3. Tips for when you forget to backup
If you’ve already rebased without creating a backup branch, use git reflog. This tool records every step you take in Git. You just need to find the hash of the commit right before the rebase command started.
git reflog
# Assuming the old hash found is abc1234
git range-diff main abc1234 featureOptimizing your workflow
To get the most out of range-diff, you can apply these two small tips:
View a summary of changes: If the commit range is too long and you don’t want to read every line of code, add the --summary flag. Git will only list the commits and their corresponding statuses.
Improve code review quality: When I review PRs for junior developers, I often ask them to keep the old hash if a complex rebase was involved. If the range-diff result returns all = signs, I can confidently approve it immediately without re-reading the entire logic.
A huge plus is that git range-diff is extremely smart. Even if you change the commit order using rebase -i, it still manages to find the corresponding commit pairs for comparison instead of throwing chaotic errors.
Conclusion: Think of git range-diff as a microscope. It helps you scrutinize every tiny change after “shaking up” history with a rebase. Don’t be afraid to rebase to keep your Git history clean; just remember to double-check with this command before performing a push --force-with-lease.
