Git rebase实战：整理提交历史，提升代码评审效率

1. 为什么你的提交历史需要在代码评审前“改头换面”

做代码评审的时候，很多人只盯着 diff 看，却忽略了一件同样重要的事：提交历史本身。一个功能分支开发了三天，提交记录可能是这样子的——“wip”、“fix”、“update2”、“final”，运气差点还能看到“真的最终版”和“别提交这个”。说实话，这种历史推到远端之后，别说同事看不懂，过两周你自己回来看都得愣一下：这到底改了个啥？

Git 的 rebase 就是专门用来解决这类问题的。它的核心能力在于，你可以在推送之前，把一堆乱糟糟的提交整理成一条清晰、有逻辑、每个提交都只做一件事的历史线。代码评审的人顺着提交历史读下来，就像看一篇结构分明的文章，而不是满地涂鸦的草稿纸。

这篇文章不打算讲 rebase 的全部底层原理，那是 Git 官方文档干的事。我按自己做项目的实际经验，把 rebase 拆成几个最常见的用法场景——合并提交、修改提交信息、调整提交顺序、处理冲突、以及最重要的“什么时候千万别用”的边界判断。每个场景都会给可复现的操作步骤和我在实战中踩过的坑，你可以直接照抄，省得自己再去试错。

2. rebase 和 merge 的本质区别：别再把历史“焊死”了

2.1 merge 留下的“缝合痕迹”到底好不好

团队里一旦养成随手 merge 的习惯，提交历史就会慢慢变成一张蜘蛛网。每个 feature 分支开发完，往主干一 merge，自动生成一个 merge commit，多次并行开发之后，主干上的提交历史会出现大量分叉和汇合点。功能多了之后，你想理清“这个修复到底先合进哪个分支”，就得顺着网线去找。

这样说吧，merge 的特点是好心办坏事：它很安全，因为它完整保留了“真实发生过什么”，但代价是历史太密、太杂，人眼根本读不动。代码评审的时候，评审者如果还要在分叉图里来回跳，体验非常差。

2.2 rebase 的本质是“重演”，不是“合并”

rebase 的底层逻辑其实很简单：把当前分支上的一串提交，逐个“摘下来”，变成补丁一样的东西，再按顺序应用到你指定的目标分支的最新提交之后。

打个生活化的比方，merge 是几个人各写一段话，最后贴到一张纸上，保留每个人的字迹；rebase 是让同一个人把所有内容重新誊写一遍，誊写之后从头到尾看过去，整整齐齐，像是一个人连续写出来的。所以 rebase 之后，你的分支历史会变成一条直线，干净利落。

这个“重演”过程里有几个特点值得注意：

• 提交的 hash 值会变。因为提交的父节点变了，所以哪怕是同样的改动内容，提交 ID 也和之前完全不同。
• 不会产生额外的 merge commit。
• 目标分支不会发生任何改变。被“重写”的只是你当前所在的特性分支。

也就是说，rebase 本质上是在复制一次改动并换个时间点重新提交。这里的底层机制是 Git 的补丁应用机制：每个提交被转换成补丁，补丁依次应用到新基础上，如果某个补丁应用失败，Git 就会停下来让你处理冲突。

3. 第一次实操：用 git rebase 主干同步最新代码

3.1 为什么日常同步也要用 rebase 而不是 merge

开发过程中最常遇到的一个场景：你从主干拉了个功能分支，开发到一半，主干上别人推了几个新提交。这时候你的功能分支已经落后了，继续干活没问题，但等你提 PR 的时候，如果主干在你分支开发期间发生了较大变化，合并冲突的可能性会很高。

此时用 rebase 同步主干代码，不仅能保证功能分支始终基于最新的主干提交，还能让最终合并回主干时历史是一条直线。很多开源项目强制要求提交到主干前必须 rebase，理由就是这个——一条直线历史能最大程度减少合并冲突概率，也让日后的二分定位（git bisect）更方便。

3.2 实战：rebase 到最新主干的完整流程

假设当前你在 feature/login 分支上，主干是 main，同步命令如下：

bash复制# 先切到主干，拉最新代码
git checkout main
git pull origin main

# 切回自己的功能分支
git checkout feature/login

# 把功能分支的提交，重新应用到 main 的最新提交之后
git rebase main

执行 rebase 之后，如果没有任何冲突，你会看到类似输出：

bash复制Successfully rebased and updated refs/heads/feature/login.

这时再看一眼提交历史，你会发现 feature/login 的基点已经挪到了 main 的最新提交上，之前的所有提交记录还在，但 hash 全部变了。

如果中途有冲突，rebase 会停在你需要处理的那个提交那里，而不是让你一次面对所有问题。这是 rebase 和 merge 在冲突处理上一个很大的区别：

• merge 的冲突：一次性把两边的改动全部堆到你面前。
• rebase 的冲突：逐个提交处理，处理完一个，git rebase --continue 接着走下一个。

冲突处理的具体操作，我放在第四章单独展开。

3.3 同步代码时的两个关键参数：--onto 和 --rebase-merges

实际开发里，只同步到主干还不够，有时候需要把一个分支的一部分提交“搬”到另一个分支上，这时候 git rebase --onto 就派上用场了。

bash复制git rebase --onto <新基底分支> <原基底的起点提交> <要移动的分支>

我举个具体例子：你在 feature/a 分支上开发，其中前两个提交本应该属于 feature/b 分支，你不小心把它们一起提交了。现在要做的就是把 feature/a 的前两个提交搬走：

bash复制git rebase --onto feature/b feature/a~2 feature/a

这条命令的意思是：把 feature/a 分支上从 feature/a~2 到分支顶端的这部分提交，移动到 feature/b 分支的顶端之后。

还有一类情况，如果源分支历史里本身就包含 merge commit，直接 rebase 会把这些 merge commit 全部拍平成普通提交，导致丢失分叉信息。这时加参数 --rebase-merges 可以保留原来的 merge 结构：

bash复制git rebase --rebase-merges feature/base

这个参数我用得不多，因为绝大多数项目都偏好线性历史，但也得知道有这个东西，碰到特殊需求时能想起来。

4. 提交历史的“整容手术”：交互式 rebase 的六种玩法

4.1 进入交互式 rebase 的正确姿势

真正让 rebase 成为“历史整理利器”的是交互式模式。你把 -i 参数加上去，Git 会打开一个编辑器，让你逐条指定对每个提交做什么操作：

bash复制git rebase -i HEAD~5

这个命令代表：把最近 5 个提交列出来，进行交互式操作。你同时会看到每个提交对应的 hash 和提交信息，面板长这个样子：

bash复制pick 5d2f84a 添加用户注册页面
pick 9f1b3c8 wip：搞定注册表单
pick 3a7c9de 调整按钮样式
pick b8e2d55 修复表单校验问题
pick c1f09a4 整理代码风格

# Rebase 5d2f84a..c1f09a4 onto 5d2f84a (5 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
# x, exec <commit> = run command (the rest of the line) using shell
# d, drop <commit> = remove commit

面板里的注释信息非常关键，它列出了所有可用的命令。日常高频操作基本就是 pick、reword、squash、fixup、edit、drop 这六种。

4.2 把五个“碎提交”压成一个干净提交

最常见的整理需求，就是把一堆碎片化的提交压缩成一个完整的提交。上面那个例子里，五个提交其实都在做“用户注册”这一件事，就可以压成一条。

在编辑器里改成这样：

bash复制pick 5d2f84a 添加用户注册页面
fixup 9f1b3c8 wip：搞定注册表单
fixup 3a7c9de 调整按钮样式
fixup b8e2d55 修复表单校验问题
fixup c1f09a4 整理代码风格

保存退出，Git 会自动把所有 fixup 的提交合并进上方的 pick 提交里。用 fixup 而不是 squash 的好处是，它默认丢弃被合并提交的提交信息，直接用 pick 那一条的信息。这样最终历史里只留一条“添加用户注册页面”，干净利落。

如果希望保留两条提交，比如“添加用户注册页面”和“注册表单校验”，就用 squash 而不是 fixup，然后在弹出来的编辑器里修改合并后的提交信息：

bash复制pick 5d2f84a 添加用户注册页面
squash 9f1b3c8 wip：搞定注册表单
squash 3a7c9de 调整按钮样式
pick b8e2d55 修复表单校验问题
squash c1f09a4 整理代码风格

保存退出后，Git 会先处理前四个提交，弹出一个编辑页面让你统一前几个的提交信息；随后继续处理第五个，再弹一次编辑页面。这种方式适合需要保留两段语义逻辑的情况。

4.3 修改提交信息与调整提交顺序

如果只是改一条提交信息，最省事的办法是直接 git commit --amend，但它只能修改最新一条。想改历史里的某条提交信息，就得靠 reword 命令。

比如第二条提交“wip：搞定注册表单”，这种信息不专业，改成“实现注册表单前端校验”：

bash复制pick 5d2f84a 添加用户注册页面
reword 9f1b3c8 wip：搞定注册表单
pick 3a7c9de 调整按钮样式
pick b8e2d55 修复表单校验问题
pick c1f09a4 整理代码风格

保存退出后，Git 会停在第二条提交的位置，弹出一个编辑器让你输入新消息。填好保存，rebase 会继续自动应用后面的提交。

调整提交顺序的方式同样是在面板里调整行的先后顺序，但有一个核心原则必须记住：pick 提交的顺序就是最终历史里的顺序，调整行序之前最好先确认这些提交之间没有强依赖。举例来说，如果“修复表单校验问题”这个提交改的正是“实现注册表单前端校验”里写的代码，把第七行挪到第二行，大概率会因为上下文对不上而产生冲突，这也是碰运气，不推荐乱排。

4.4 拆分一个大提交：edit 命令的正确用法

和压缩相反，还有一种需求是把一个“大杂烩”提交拆成多个逻辑独立的提交。edit 命令就是为了这个场景准备的。

bash复制pick 5d2f84a 添加用户注册页面
edit b8e2d55 包含页面结构调整和接口对接
pick c1f09a4 整理代码风格

保存退出后，Git 会停在这个提交应用完成之后、下一个提交应用之前。此时你处于“已暂存改动的完成状态”，需要手动把暂存区分开：

bash复制# 先回退暂存，但保留工作区改动
git reset HEAD~

# 按逻辑分批添加并提交，比如先提交页面结构调整
git add src/pages/register
git commit -m "调整注册页面布局结构"

# 再提交接口对接相关文件
git add src/api/register.js
git commit -m "对接注册接口并处理错误码"

# 继续完成 rebase
git rebase --continue

这里有个注意点，用 git reset HEAD~ 时，如果没有参数 --soft，改动会回到工作区，区分度不高。推荐的做法是，在 edit 停住后，优先用 git add -p 按代码块的粒度分批暂存，会稳很多。

4.5 丢弃一个错误提交：drop 的使用边界

面板里把某行命令改成 drop，或者干脆删掉那行，都可以让这个提交消失。注意，drop 并不“删除”改动内容，它只是让这个提交不参与最终历史，改动本身可能还出现在后续某个提交里，也可能直接消失，取决于后续提交是否依赖它。

如果 drop 后发现丢错了，只要还没执行 git gc，你都可以通过 git reflog 找回。这个我放在最后的排查章节里讲。

5. 完整案例演示：把一团糟的历史整理到可评审状态

5.1 混乱现场：一个分支的“原始污染”历史

我现在手头有一个实际项目里的例子，feature/payment 分支，一共 7 个提交，我把它在整理前的状态列出来：

看下来不难发现，这份历史存在的问题是提交粒度极不均匀——有的提交是整块功能，有的提交只是“忘记导入了”这种补救动作，中间还混着调试日志的提交和清理日志的提交。评审的人看完能疯掉。

5.2 整理目标：从 7 条压缩到 3 条干净提交

我的整理思路是：把零散修补类提交并入对应的功能提交，把调试类提交清理掉，最终只保留三层逻辑——功能实现、错误处理、文档更新。

执行命令前，先确认当前分支状态是干净的，工作区没有未提交改动：

bash复制git status

确认没问题后，进入交互式 rebase：

bash复制git rebase -i HEAD~7

编辑器里把指令改成这样：

bash复制pick a1b2c3d feat: 添加支付页面结构
fixup a2b3c4d fix: 忘记导入支付组件
fixup a3b4c5d wip: 对接支付接口
fixup a4b5c6d debug: 打印支付参数
pick a5b6c7d fix: 处理回调错误
fixup a6b7c8d style: 删除调试日志
pick a7b8c9d docs: 更新支付说明

保存退出，Git 开始逐个应用。这个例子里运气不错，没有任何冲突，最终输出一条成功提示。

5.3 整理后的提交历史长什么样

再跑一遍 git log --oneline，看到的效果是：

bash复制8d2f3a4 docs: 更新支付说明
5f1a2b3 fix: 处理回调错误
4c9e8d7 feat: 添加支付页面结构及接口对接

三个提交，语义清晰，粒度均匀，每个提交都能独立看懂。评审的人按顺序看三个提交，就能完整理解整个功能的演变过程，完全不用跟混乱历史搏斗。

5.4 把整理结果安全推送：--force-with-lease 而不是 --force

到这里有一个非常关键的注意事项：如果你的功能分支之前已经 push 到远端，并且团队里有其他人也在用这个分支（哪怕只是拉下来看过代码），那么 rebase 重写历史之后，原来分叉的远端历史就不可能无痛合并了。此时你需要强制推送：

bash复制git push --force-with-lease origin feature/payment

为什么必须用 --force-with-lease 而不是裸的 --force？区别在于，--force 是“不管远端现在什么样，我就是要覆盖”；--force-with-lease 会先检查远端分支是否还是你上次拉取时的状态，如果远端已经有新的提交，它会拒绝推送并提醒你。这在多人协作的分支上能防止你把别人的提交“抹掉”。我的建议是，团队里如果还有人用这个分支，推之前打声招呼比任何参数都重要。

6. 冲突处理实录：rebase 中冲突的三种形态与处理法

6.1 第一类冲突：同一文件同一位置被修改

这是最常见的一种。两个分支都改了同一文件的同一行代码，Git 无法自动判断该保留哪边。rebase 停住后，你会看到类似提示：

bash复制CONFLICT (content): Merge conflict in src/components/PayButton.js
error: could not apply 4c9e8d7... feat: 添加支付页面结构及接口对接
hint: Resolve all conflicts manually, mark them as resolved with "git add", then run "git rebase --continue".

打开冲突文件，找到 <<<<<<< 和 >>>>>>> 标记：

bash复制<<<<<<< HEAD
const isPaid = order.status === 'PAID';
=======
const isPaid = order.payResult === 'SUCCESS';
>>>>>>> 4c9e8d7 (feat: 添加支付页面结构及接口对接)

这时需要判断：HEAD 代表的是 rebase 前的目标分支内容（也就是你 rebase 目标的最新状态），而 >>>>>>> 那一侧代表的是你正在应用的这个提交的改动。手动改成正确结果，删掉标记，然后：

bash复制git add src/components/PayButton.js
git rebase --continue

6.2 第二类冲突：文件被一方删除，另一方修改

这类冲突不体现在代码行上，而是体现在“文件是否还存在”的分歧上。比如目标分支删掉了某个旧工具文件，但你正在应用的提交里还改了它。Git 会提示：

bash复制CONFLICT (modify/delete): src/utils/oldHelper.js deleted in HEAD and modified in 4c9e8d7 (feat: ...)

处理方式取决于这个文件到底应不应该存在。如果确定是要删的，就执行 git rm；如果保留，就 git add 之后 continue：

bash复制git rm src/utils/oldHelper.js
git rebase --continue

6.3 第三类冲突：重复提交同一处改动

当你的分支上有一个提交，和 rebase 目标分支上的某个提交改的是同一处代码，但内容完全一致时，Git 可能报告“这个补丁已存在”而不知道如何处理。实践中这个场景常见于分支合并之后又 rebase，产生了重复操作。

这类冲突没有标准解法，我的经验是：

• 检查冲突处的实际差异，如果两边确实已经包含相同改动，直接选择保留目标分支版本即可。
• 用 git diff 对比两边差异，确认后手动修正并继续。

整个冲突处理的核心原则是：一次只处理一个，处理完 commit 标记后 continue，绝不要在 rebase 中途切分支跑别的任务。

7. 避坑指南：这些场景打死别用 rebase

7.1 别人也在用的共享分支

这个问题我再强调一次：rebase 会把提交历史结构整个重写一遍，提交的 hash 全变。如果这个分支除了你之外还有别的人在开发或拉取，你推一个 --force 上去，别人的本地分支立刻变成无头状态，拉取时匹配不上远端历史，轻则强制对齐，重则丢改动。

可以这么说：自己的功能分支上随便怎么 rebase，主干分支和已经多人拉取的集成分支上，绝对禁止 rebase。正确做法是，个人分支整理好之后，再通过 merge 的方式合到主干，这样主干历史没有重写，对团队是安全的。

7.2 冲突太多且频繁的时候

如果 rebase 一个分支时，几乎每个提交都冲突，这往往说明分支偏离目标基底太远。比如你从主干拉了分支，开发了三个月，主干已经前进了几百个提交，这时候强行 rebase 到最新主干，等于把三个月积累的改动重新逐个应用到新基座上，冲突概率极高，人也容易在反复处理冲突中改错代码。

遇到这种情况，我的经验是分两个步骤：先 rebase 到中间一个较近的基点，确认无冲突后，再 rebase 到更近的目标。如果中间步骤也有大量冲突，就应该考虑用 merge 替代 rebase，保留一次合并冲突的处理成本，而不是多次冲突反复支付。

7.3 rebase 和 ammend 滥用后的“历史洁癖”

还有一种心态值得提醒：不是所有的提交都值得整理。如果只是在本地做小实验、临时存个代码，强行做出“一条完美历史”反而浪费时间。rebase 的合理使用频率应该以“能提升代码评审效率”为边界，而不是以“历史必须完美”为准绳。

我在实际项目里发现一个很实用的习惯：开发过程中随便提交，甚至故意提交一些乱糟糟的 wip 都没问题，关键在于推送之前做一次整理。这个节奏让日常开发无压力，又保证了最终交付物的质量。

8. 常见故障排查：rebase 中断、丢失与错误纠结

8.1 rebase 中途退出后怎么“反悔”

有时候 rebase 处理到一半，改了太多冲突，突然发现方向不对想退回。别慌，rebase 中断时并没有“销毁”原分支的提交，你可以随时退回：

bash复制git rebase --abort

这个命令会把你完整恢复到开始 rebase 之前的状态，所有提交都在，所有改动都在。哪怕你已经处理了好几个冲突文件，只要没执行过 git rebase --continue，abort 都能安全回到起点。

8.2 push 被拒绝：远端历史已经分叉

执行 push 时候报错：

bash复制 ! [rejected]        feature/payment -> feature/payment (non-fast-forward)

这代表远端分支和本地分支的历史线对不上。如果确认本地是想推上去的最终版（且不影响其他人），用：

bash复制git pull origin feature/payment --rebase
git push --force-with-lease origin feature/payment

注意，先 pull 再推的前提是你希望把远端的新提交也纳入本地历史。

8.3 不想要的提交已经走远：reflog 救急法

丢失提交或 rebase 弄错之后的最后防线是 git reflog。reflog 记录了 HEAD 指针在过去一段时间内指向过哪些提交，即使 rebase 把历史重写了，reflog 里的旧提交记录依然保留一段时间（默认 90 天）。

bash复制git reflog

找到 rebase 之前的那条记录，比如 5d2f84a，然后：

bash复制git reset --hard 5d2f84a

就能回到那个时间点的分支状态。这个操作每天都有人靠它救命，不需要背参数，核心是理解“reflog 是 Git 自带的后悔药”。

8.4 冲突文件中残留的标记符号

处理多个冲突文件时，很容易漏掉一两个没改完的文件。git rebase --continue 会检查暂存区是否完整，如果遗漏会提示 you must edit all merge conflicts and then mark them as resolved。此时可以用搜索命令快速排查：

bash复制grep -rn "<<<<<<<" src/

找到所有冲突标记的位置，逐个解决完再 add、continue。

9. 我的日常 rebase 工作流参考

说完了所有技术细节，我把个人日常项目中的工作流整理出来，给还没找到自己节奏的人一个参考：

1. 主干保持只允许 rebase 合入，不允许直接 push 提交。
2. 新功能一律开分支开发，日常提交随便写，一气呵成。
3. 本地功能完成后，git rebase -i HEAD~N 整理提交，按功能粒度合并。
4. 推送到远端之前执行 git rebase origin/main 同步最新主干，冲突在此阶段消化。
5. 推送使用普通 push，如果有冲突再考虑 --force-with-lease。

这套流程跑了几年，提交历史基本一直维持着“说人话”的状态，代码评审效率比之前想怎么提怎么提的时代提升了不少。工具本身没有好坏，关键是搞清楚用它的边界。rebase 是一个好东西，知道什么情况下别用它，比知道怎么用它更重要。