把功能分支 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 捞,既麻烦又容易过期。

bash rebase 前后
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 掉了
>只在右侧(新序列)存在——新增的提交
text range-diff 输出示例
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 了一下,应该没改」有说服力得多。

💡 小技巧:输出默认带颜色,粘到 PR 评论或工单里会变成一堆转义符。加 --no-dual-color 让左右两侧使用同一套 diff 配色,纯文本粘贴更干净。

三个高频用法

1. force-push 之后给 reviewer 的变更说明

就是上面的场景。把 range-diff 的输出(或它的结论)贴进 PR,明确写出「只有第 2 条因冲突调整了一行,其余未变」。reviewer 只需要看那一条,不必重读整个 PR。

2. 对比两个功能分支的差异

两个人基于同一个 main 各做了一版实现,想知道提交层面差在哪:

bash 比较两条分支
git range-diff origin/main feature/impl-a feature/impl-b

它会尝试把两边描述同一件事的提交配对,再标出差异。注意这是按补丁相似度配对,不是按提交顺序,所以两边思路差得越远,配对结果越需要人判断。

3. cherry-pick 到 release 分支后核对

把 main 上的修复 cherry-pick 到 release/1.4,最怕漏一条或带进不该带的提交。可以直接比对两段序列:

bash 核对回合并结果
# 以 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 结束。删除命令:

bash 确认无误后清理
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 不可怕,说不清改了什么才可怕。