git-am 教程

一句话理解

git am 会把邮件补丁（mbox/patch 文件）按顺序应用成提交，而不是只改工作区文件。

什么时候适合用

• 接收邮件补丁序列
• 需要保留原作者提交信息
• 在非平台化协作流程中导入变更

基本流程

git am 0001-fix.patch
# 或
git am *.patch

如果中途冲突：

git am --continue
git am --skip
git am --abort

为什么它不同于 git apply

• git apply：只应用文件差异
• git am：应用差异并创建提交（含作者/主题等邮件元信息）

稳定使用建议

1. 应用前先在临时分支执行
2. 先检查基线是否匹配补丁预期
3. 冲突时优先保留可回退点，不要连续盲目 --skip

!先确认补丁基线再 am

基线漂移会让补丁序列在中途大量冲突，处理成本远高于先同步一次历史。

常见误区

误区 1：把 am 当作“任何补丁都能自动吃下”

git am 把邮件格式的补丁应用到当前分支并生成新提交，同时保留原始作者信息和提交元数据。理解它时，要把它放在"补丁如何从外部正式进入本地历史"这个环节中来看。

上下文不匹配时仍会失败，需要人工判断。

误区 2：冲突后直接 abort 丢弃全部进度

• 把外部贡献者或邮件列表发来的补丁序列正式应用到本地分支。
• 在补丁工作流中，用 git am 把收到的 .patch 文件转化为真正的提交记录。
• 当需要保留提交者身份和完整提交说明时，用 git am 而不是手工复制改动。

如果前几封已成功应用，先评估是否值得继续。

误区 3：跳过补丁不留记录

输入

邮件格式补丁文件当前分支

→git am

结果

新提交（保留作者信息）前进的分支指针

am 和 apply 的分工很明确：am 生成提交，apply 只改工作区。

后续很难解释为什么提交序列缺了一段。

接下来建议继续看什么

• 补丁应用失败时，用 git am --abort 可以回退到应用前的状态，不会留下半成品提交。
• 执行 git am 前最好先用 git status 确认工作区干净，并用 --show-current-patch 预览当前补丁内容。
• 如果补丁的上下文和当前代码基线不匹配，应用会失败，此时需要先确认补丁是基于哪个版本生成的。
• 邮件编码、签名行和空白符格式都可能影响补丁解析，必要时可用 --ignore-whitespace 或 --3way 提高容错。

1. git-format-patch
2. git-send-email
3. recover after wrong cherry-pick