把功能分支 rebase 到最新 main、解决两处冲突、git push --force-with-lease,一切看起来都很正常。可 reviewer 打开 PR 只看到一串全新的提交哈希,第一句话往往是:「你 force-push 之后到底改了什么?我上次 review 过的代码还在吗?」
这种时候不用逐条解释,也不用让他重新读一遍全部 diff。Git 2.19 起提供了一个专门回答这个问题的命令:git range-diff。它对比的不是两个文件,而是两段提交序列——哪些提交原样保留、哪条因为解决冲突被改动、哪条被丢弃、哪条是新增的,一次列清楚。
range-diff、diff、log 各回答什么问题
| 命令 | 回答的问题 | 看的是 |
|---|---|---|
git diff A B | 两个状态之间,文件内容差在哪 | 最终文件树 |
git log A..B | 这段范围里有哪些提交 | 提交列表 |
git range-diff | 两段提交序列逐条对应后,哪条变了、变在哪 | 提交序列 + 每条补丁 |
简单说:diff 关心结果,log 关心有没有,range-diff 关心「同一个提交在改写前后是否还是同一件事」。
实战:先留后路,再 rebase
关键动作是在 rebase 之前留一个引用。很多人 rebase 完才想起来要对比,此时旧提交只能靠 reflog 捞,既麻烦又容易过期。
git fetch origin
# 1) 留一个安全引用(名字随意,建议带日期)
git branch backup/pre-rebase
# 2) 正常 rebase,解决冲突
git rebase origin/main
# 3) 跑测试,确认功能没坏
php vendor/bin/phpunit
# 4) 逐条对比 rebase 前后
git range-diff origin/main backup/pre-rebase HEAD
最后一条命令的三个参数分别是:共同基线、旧序列的末端、新序列的末端。也就是把 origin/main..backup/pre-rebase 和 origin/main..HEAD 两段提交序列放在一起比对。
读懂输出:四个符号
| 符号 | 含义 |
|---|---|
= | 这条提交在两侧完全一致(补丁与提交信息都没变) |
! | 这条提交被修改过,下面会给出具体 diff |
< | 只在左侧(旧序列)存在,新序列里没有——通常是被 drop 或 squash 掉了 |
> | 只在右侧(新序列)存在——新增的提交 |
1: a1b2c3d = 1: f7e8d9c feat: 订单金额改为按分计算
2: b2c3d4e ! 2: a8f9e0d fix: 优惠券叠加时重复扣减
@@ -42,6 +42,7 @@ class OrderTotal
- $total = $total - $discount;
+ $total = max(0, $total - $discount);
3: c3d4e5f < -: ------- chore: 临时打印调试日志
-: ------- > 3: b9a0f1e test: 补充优惠券叠加用例
这段输出可以直接翻译成给 reviewer 的话:第 1 条原样未动;第 2 条在解决冲突时改了一行,把可能为负的金额兜底为 0;第 3 条临时调试提交已删除;另外补了一条测试。总共四条,一目了然,比「我 rebase 了一下,应该没改」有说服力得多。
--no-dual-color 让左右两侧使用同一套 diff 配色,纯文本粘贴更干净。三个高频用法
1. force-push 之后给 reviewer 的变更说明
就是上面的场景。把 range-diff 的输出(或它的结论)贴进 PR,明确写出「只有第 2 条因冲突调整了一行,其余未变」。reviewer 只需要看那一条,不必重读整个 PR。
2. 对比两个功能分支的差异
两个人基于同一个 main 各做了一版实现,想知道提交层面差在哪:
git range-diff origin/main feature/impl-a feature/impl-b
它会尝试把两边描述同一件事的提交配对,再标出差异。注意这是按补丁相似度配对,不是按提交顺序,所以两边思路差得越远,配对结果越需要人判断。
3. cherry-pick 到 release 分支后核对
把 main 上的修复 cherry-pick 到 release/1.4,最怕漏一条或带进不该带的提交。可以直接比对两段序列:
# 以 v1.4.0 为基线,对比 main 与 release/1.4 的提交序列
git range-diff v1.4.0 main release/1.4
正常情况应该看到 release 分支上每条修复都能在 main 侧找到对应项;如果出现大量 <,说明有提交只在 main 上、没有回合。
4. interactive rebase 整理历史后,确认内容没丢
用 rebase -i 做了 squash/fixup/reword,担心把某段改动压没了。同样先留 backup 分支,整理完再 range-diff:被 squash 的提交会以 < 出现,合并后的新提交以 > 出现,中间的 diff 能看出内容是否完整保留。这是比「数一下行数」可靠得多的检查方式。
五个注意点
1. 它按补丁相似度配对,不是按哈希或顺序
改名、大段重写、把一个提交拆成两个,都可能让配对结果看起来「错位」。看到意外的 < / > 组合时,先确认是不是提交被拆分或合并,而不是直接认定代码丢了。
2. 默认不展示合并提交
range-diff 关注的是普通提交的补丁序列,merge 提交通常不会出现在结果里。用 merge 而不是 rebase 同步主干时,别指望它替你检查合并结果。
3. 提交信息的变化也会标成 !
只改了 commit message、代码一字未动,同样会显示 !,但下面的 diff 是空的。这种情况在 reword 之后很常见。
4. 需要 Git 2.19 及以上
老版本会直接报 git: 'range-diff' is not a git command。用 git --version 确认;公司内网长期不升级的 Git,可能要改用在临时目录装新版本。
5. 它证明「补丁没变」,不证明「代码没问题」
range-diff 全绿只说明 rebase 没有偷偷改动你的提交,不代表功能正确。测试该跑还得跑,两者是互补关系,不是替代关系。
安全网什么时候撤
backup/pre-rebase 这类分支不要长期堆着,但也不要 rebase 完立刻删。建议等三个条件都满足再清理:force-push 成功、CI 通过、review 结束。删除命令:
git branch -D backup/pre-rebase
# 如果还留了 tag
git tag -d backup/pre-rebase-20261117
backup/pre-rebase,并且远端没有别的同事还在引用它。分支删了还能靠 reflog 捞,但如果连同 reflog 一起过期,就真的找不回来了。总结
git range-diff 把「rebase 之后到底改了什么」从口头解释变成了可核对的输出:= 未变、! 改过、< 删掉、> 新增。对 reviewer,它把一次全量重读压缩成看几条差异;对自己,它是整理历史后的最后一道自检。配合 rebase 前留下的 backup 分支,force-push 就不再是一件需要靠记忆担保的事。
force-push 不可怕,说不清改了什么才可怕。