Git rebase --rebase-merges 怎样保留分支拓扑

当一个功能分支里还合入了另一个相关分支，普通 git rebase 默认会忽略 merge commit，把历史重新排成一条直线。如果你需要迁移到更新的 main，同时保留“先完成基础分支、再合入上层分支”的拓扑，就应该使用 git rebase -i --rebase-merges main。官方文档地址：https://git-scm.com/docs/git-rebase

第 1 步：先确认提交图和变基范围

先在当前功能分支查看提交图。这个主题的关键不是“提交有多少条”，而是要确认哪些提交属于当前变基范围、哪些提交是合并点，以及新的基线究竟是哪个分支。工作区有未提交改动时，先保存或暂存，避免把无关文件带进改写过程。

# 查看所有分支的提交图，确认 merge commit 和分支指向
git log --oneline --decorate --graph --all -12

# 检查工作区，避免未提交改动干扰 rebase
git status --short

# 确认当前所在分支，后续命令默认改写它
git branch --show-current

例如当前分支是 report-button，历史中先合入了 refactor-button，随后又在顶层形成一次 merge。只要新基线是 main，就可以把“迁移到 main”与“保留这两个分支的关系”作为同一个操作目标。

第 2 步：用 --rebase-merges 打开交互式变基

在当前分支运行下面的命令。-i 让 Git 打开 todo 列表，--rebase-merges 告诉 Git 不要默认丢弃合并提交，而是尝试按原有分支结构重建它们。

# 以 main 为新的上游，并保留变基范围内的分支拓扑
git rebase -i --rebase-merges main

# -r 是 --rebase-merges 的简写；二选一，不要重复写同一选项
# git rebase -i -r main

打开 todo 后，除了常见的 pick，还可能看到 label、reset 和 merge。可以把它们理解为一张“重新搭建提交图”的说明：label 给某个位置命名，reset 把后续提交切回某个命名位置，merge 重新创建合并点。不要为了让列表更短而随意删除这些关系行。

官方文档说明，--rebase-merges 重建的是合并提交和分支结构，原来的提交 ID 不会原样保留。重放过程中，原来在 merge commit 里手工解决的冲突也可能需要重新处理。

第 3 步：选择 cousin 模式并处理冲突

不带参数时，--rebase-merges 使用 no-rebase-cousins。这会让没有直接继承 main 的 cousin 提交尽量保留原来的分支点。如果你的目标是让这类分支也全部落到新上游上，可以显式指定 rebase-cousins，但这会改变更多祖先关系，应该先在本地分支上确认影响。

# 默认保留 cousin 分支原来的分支点，适合只更新直接子孙链
git rebase -i --rebase-merges=no-rebase-cousins main

# 需要让 cousin 提交也迁移到 main 时再显式选择该模式
git rebase -i --rebase-merges=rebase-cousins main

如果某个合并点发生冲突，先按文件内容解决，再把解决结果加入暂存区并继续。不能接受当前改写时，直接中止回到变基开始前的分支状态。

# 解决冲突后，标记已经处理好的文件
git add path/to/file

# 继续重放剩余提交和合并点
git rebase --continue

# 如果发现基线或拓扑选择不对，放弃本次变基
git rebase --abort

这里不要把 --rebase-merges 当成“自动复用所有历史决策”。它只能重建提交关系；合并时的人工选择、不同策略或后来变化的文件内容，都可能要求你再次判断。

第 4 步：用提交图和差异确认拓扑仍然成立

变基完成后不要只看命令是否返回成功。重新打开历史图，确认基础分支与上层分支仍然能被读出来，再检查工作区和关键文件差异。因为提交被重放过，新的提交 ID 与旧历史不同是正常现象。

# 查看新的提交图，确认 merge commit 和分支层次仍在
git log --oneline --decorate --graph --all -12

# 确认没有停在未完成的 rebase 状态，也没有未提交文件
git status

# 按关键文件复查新历史前后的内容差异
git diff main...HEAD -- path/to/file

理想状态是：当前分支指向新历史；合并点被重新创建；分支图仍能表达基础分支与上层分支的关系；git status 显示工作区干净。若当前分支已经推送并被他人使用，提交 ID 改变后不要直接强推，先按团队的远程分支规则沟通。

常见问题

普通 rebase 为什么会把 merge commit 去掉？

普通 rebase 面向的是线性的提交序列，默认会从 todo 中排除 merge commit，再把可重放的提交串成一条直线。需要保留分支结构时，才用 --rebase-merges。

--rebase-merges 会保留原来的合并提交 SHA 吗？

不会保证保留。rebase 会把提交重放到新的祖先上，合并提交也会重新创建，所以应核对内容和拓扑，不要把旧 SHA 当成验收条件。

什么时候不应该使用 rebase-merges？

如果分支已经是多人共享的公共历史，或你只需要线性化自己的本地提交，就不要为了“图看起来完整”而改写共享分支。先确认协作边界，再决定是否在本地重建拓扑。

把流程固定为“看清提交图 → 使用 --rebase-merges → 选择 cousin 模式 → 处理并复查”，就能在更新基线的同时保留有意义的分支关系；真正需要谨慎的是改写范围、冲突决策和共享分支边界。