把已推送的多个开发提交安全合并成一个｜Git 技巧

功能的开发往往不是一次到位：先是铺基础设施、然后修依赖、再调日志、最后补一个更完善的替代实现，前前后后有好几条提交。这些提交逻辑上属于同一件事，但历史却被切碎了。更头疼的是它们已经推送到远程，于是「合并提交」从一次本地整理，变成了一次涉及历史改写的操作。

这篇文章记录的是：如何把若干条已推送到远程的开发提交安全地 squash 成一条，全程不丢代码、出问题能回退。并结合一次真实操作，讲清楚会踩到的坑——尤其是 Windows 上 PowerShell 的几个隐藏陷阱。

先看清要合并的历史

动手前先在仓库里看两样东西：提交的分叉结构和哪些已经推送。

git log --graph --oneline -10 dev   # 看分叉 / merge 结构
git log --oneline -5 origin/dev     # 确认哪些已推送

实际场景里常出现这种结构：功能开发时从同一个基点 BASE 分叉成两条线并行推进，最后用一条 Merge remote-tracking branch 把它们兜回来，形成：

Merge remote-tracking branch 'origin/dev' into dev   ← 合并点
  feat(automation): 全局持久浏览器 profile 取代 Redis storageState 会话
    优化 task 日志步骤
    依赖问题
    feat: 新增无头浏览器自动化任务基础设施
  Merge remote-tracking branch 'origin/dev'          ← 祖先合并点

目标是把它压成一条干净的功能提交。关键是别用 rebase -i：一旦历史里夹着 merge 提交，rebase 会把它当普通提交重放，很容易制造麻烦。用 git commit-tree 直接构造一个「树内容等于合并结果、父指回基线」的扁平提交，更干净也更好控制。

五步：合并已推送提交

下面的命令以「把 A、B、C 三条提交压成一条，父提交记为 BASE、合并结果记为 TOP」为例。

第 1 步 确定边界

TOP 是所有要合并的提交里最顶端那个（历史里最靠前、最终含全部改动的那个）；BASE 是它们共同的分叉点（合并后的父提交）。

第 2 步 读出 TOP 的真实 tree

这一步决定了合并后的内容，一定要拿到正确的 tree 哈希。

git cat-file -p TOP | Select-Object -First 1

输出第一行 tree xxxx... 里的哈希就是它。不要用 git rev-parse 'TOP^{tree}'——在 PowerShell 里 ^{tree} 会被误解析，写出错误的索引（见下文「坑一」），拿到的可能是别的提交的树，造成丢改动。

第 3 步 做本地备份

把原始 TOP 记到一个备份分支，出任何问题都能一键回来：

git branch backup/squash TOP

第 4 步 合成扁平提交并校验

# 1) 从第 2 步 cat-file 输出里拿到 TOP 的 tree 哈希
$tree = '<第2步拿到的tree哈希>'
$parent = git rev-parse BASE

# 2) 写提交消息：用无 BOM 的 UTF-8，避免消息开头混入不可见字符（见坑二）
[System.IO.File]::WriteAllText(
    "commitmsg.txt",
    "feat(xxx): 完整功能说明`n`n- 子项1`n- 子项2`n",
    (New-Object System.Text.UTF8Encoding($false))
)

# 3) 合成新提交
$new = git commit-tree $tree -p $parent -F "commitmsg.txt"
Remove-Item commitmsg.txt

# 4) 关键校验：新提交与原 TOP 的树必须完全一致，输出为空才算是无损
git diff --stat $new TOP

git diff $new TOP 一旦有输出，说明两棵树的差异没被保留（通常是 tree 选错了），立刻停下回到第 2 步核对，千万不要继续。

第 5 步 reset + force push + 清理

git reset --hard $new           # 本地 dev 切到新提交
git push --force origin dev     # 覆盖远程
git branch -D backup/squash     # 确认远程 OK 后再删备份分支

--force 覆盖远程这里要特别警觉：改写已推送历史后无法普通 push，必须 force；而 force 会让别处克隆、CI 缓存对 dev 的旧引用与新历史分叉。 只有你是唯一克隆点时安全，有协作者先沟通。

三个真踩过的坑

坑一：PowerShell 把 ^{tree} 转义坏了

构造提交时我写了 git rev-parse 'TOP^{tree}'。PowerShell 的转义符是反引号，但在这个位置 ^ 的处理很刁：写作 TOP^^{tree} 会被解析成「TOP 的父的父」，拿到的树根本不是目标，导致合成的提交少了一整个功能模块的改动。幸好校验那一步 git diff $new TOP 立刻暴露了树不一致，在 reset 之前就发现并重做，没有污染仓库。

经验：树哈希这类关键索引，一律用 git cat-file -p <提交> 直接读，不要依赖 ^{tree} 的简写。

坑二：Out-File 给提交消息加了 BOM

Windows 下 Out-File -Encoding utf8 会在文件开头悄悄加一个 BOM，写入提交消息后它变成正文前一个不可见的乱码字符。改用 [System.IO.File]::WriteAllText(path, text, (New-Object System.Text.UTF8Encoding($false))) 写无 BOM 文件就能绕开。

坑三：-m 和 -p 混在一行容易缠住

大段含换行的消息用 git commit -m 内联，在 PowerShell 里解析容易出错。规范做法是把消息先写进文件，用 git commit-tree ... -F file 读入，干净且不易踩到引号转义。

线性历史？有更省的办法

如果你要合并的几条提交是简单的先后线性、中间没有 merge，用 reset --soft 就能轻量完成：

git reset --soft BASE      # 回退但保留所有改动在暂存区，工作区文件不丢
git commit -m "合并后的消息"
git push --force origin dev

reset --soft 不碰工作区文件，--hard 才会丢东西。线性历史优先用 soft；只有中间夹着 merge 的分叉历史，才需要走上面的 commit-tree 五步法。

结论

把已推送的提交 squash 成一条，本质是一次受控的历史改写。要点就三个：用 commit-tree 构造扁平提交而非 rebase -i、用 git diff $new TOP 校验树无损、改写前先建备份分支。 而 Windows + PowerShell 环境下，「读 tree 的简写会被转义」「Out-File 加 BOM」「消息内联易窜」是三件最容易踩、也最隐蔽的坑。线性历史用 reset --soft 更省，分叉历史走五步法，都能放心复用。