From 45133c589a970390bc10e4db4f7d9921dbaa0832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C5=91rinc?= Date: Mon, 23 Feb 2026 13:28:02 +0100 Subject: [PATCH] doc: clarify `git range-diff` add/delete output When `git range-diff` cannot match a commit between two versions of a branch, it shows the old commit as removed (`<`) and the new commit as added (`>`), and it does not show the patch contents. This output is easy to misread as "no code changes" because the diff for that commit is effectively empty. It really means the commits were considered unrelated and the new commit should be reviewed from scratch. This is analogous to rename detection in `git diff`: if similarity is too low, a rename shows up as delete+add. Example (exact SHAs from PR #34320): B=ff338fdb53a66ab40a36e1277e7371941fc89840; A=dd76338a57b9b1169ac27f7b783d6d0d4c6e38ab; git fetch upstream $B $A git range-diff 0ca4295f2e5f4443a1f8b3bae7cba0f6c054276f..$B 139aa4b27e4839291c83a04dcd1649c5595814ca..$A This produced output like: 1: 4b32181dbb < -: ---------- test: add `HaveInputs` call-path unit tests -: ---------- > 1: 277c57f0c5 test: add `HaveInputs` call-path unit tests Even though the subject matches, the first commit had no matching diff shown. That should be treated as "unmatched" rather than "unchanged". If you expected a match, try increasing the creation factor so `git range-diff` searches harder: git range-diff --creation-factor=95 --- doc/productivity.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/productivity.md b/doc/productivity.md index 4509e23cde1..c436811a0a8 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -191,7 +191,12 @@ Then a simple `git pr 12345` will fetch and check out that pr from upstream. ### Diff the diffs with `git range-diff` -It is very common for contributors to rebase their pull requests, or make changes to commits (perhaps in response to review) that are not at the head of their branch. This poses a problem for reviewers as when the contributor force pushes, the reviewer is no longer sure that his previous reviews of commits are still valid (as the commit hashes can now be different even though the diff is semantically the same). [git range-diff](https://git-scm.com/docs/git-range-diff) (Git >= 2.19) can help solve this problem by diffing the diffs. +It is very common for contributors to rebase their pull requests, or make changes to commits (perhaps in response to review) that are not at the head of their branch. This poses a problem for reviewers as when the contributor force pushes, the reviewer is no longer sure that their previous reviews of commits are still valid (as the commit hashes can now be different even though the diff is semantically the same). [git range-diff](https://git-scm.com/docs/git-range-diff) (Git >= 2.19) can help solve this problem by diffing the diffs. + +> [!NOTE] +> If `git range-diff` cannot match a commit in the old range to a commit in the new range, it will show it as "removed" (`<`) and "added" (`>`), without showing the patch contents. +> This does not mean there were no code changes. +> It means the commit was considered unrelated, and should be reviewed in full like a new commit. For example, to identify the differences between your previously reviewed diffs P1-5, and the new diffs P1-2,N3-4 as illustrated below: ``` @@ -207,6 +212,12 @@ You can do: git range-diff master previously-reviewed-head new-head ``` +If you expected `git range-diff` to match a commit, but it shows it as a deletion and an addition, try re-running with a higher creation factor: + +```sh +git range-diff --creation-factor=95 +``` + Note that `git range-diff` also works for rebases: ```