format-patch 是什么
format-patch 把提交导出为邮件格式的补丁文件（含作者、提交信息与差异），用于无平台协作的评审、跨网络传递或离线归档；接收方用 git am 应用，作者与提交信息完整还原。这是「邮件工作流」的核心工具，上游不接受直接推送的开源项目常用它提交代码；评审意见以邮件回复，补丁以新版本重发。
基本信息
| 用途 | 生成 .patch 文件序列（一个提交一个文件） |
|---|---|
| 语法 | git format-patch -o <目录> <范围> |
| 配套 | git am 应用；--cover-letter 生成说明信；-M -C 保留重命名信息 |
| 范围写法 | -1 HEAD 单提交；origin/main..feature 区间序列 |
| 输出命名 | 0001-xxx.patch 顺序编号，按提交顺序应用 |
典型使用场景
- 上游协作：给不接受 PR 的项目提交补丁序列。
- 跨网传递：没有共享平台时用补丁搬运提交。
- 离线评审：把改动打包给评审人逐条查看。
- 版本归档：把发布区间的提交序列留档。
- 教学讲评：把提交拆成补丁逐条讲解，便于复盘每一步。
- 备份兜底：无法推送时的导出通道。
常用示例
常用示例
git format-patch -o /tmp/patches -1 HEAD # 单个提交
git format-patch --cover-letter -o /tmp/patches origin/main..feature/login # 带说明信的序列
git format-patch -M -C -o out/ v1.2..v1.3 # 记录重命名与复制
git am /tmp/patches/*.patch # 接收方按序应用常用选项
| 选项 | 作用 | 备注 |
|---|---|---|
| -o | 指定输出目录 | 不存在会自动创建 |
| -1 | 只导一个提交 | 接在 HEAD 上 |
| --cover-letter | 生成说明信 | 便于写系列总述 |
| -M -C | 检测重命名与复制 | 补丁更小更准确 |
| --thread | 按邮件线程生成 | 便于邮件列表归档与讨论 |
生成的补丁可用 git am 完整还原作者与提交信息；应用失败时有三种处理：-3 尝试三方合并、--reject 保留拒绝清单、--abort 整体回退；应用前先确认工作区干净，避免半应用状态。