git-format-patch 教程

一句话理解

git-format-patch 用于把提交导出成可发送的补丁文件。

什么时候适合用

• 当你需要把提交导出成可发送的补丁文件
• 当你想把这类操作做成稳定流程而不是手工重复
• 当你需要更准确地理解 Git 在这一步到底记录了什么

基本示例

git format-patch origin/main..HEAD

读这条命令时最该注意什么

补丁工作流最怕上下文不一致，所以应用前最好先确认基线、工作区状态和回退动作。

一个更稳的实践建议

在真正应用前先阅读补丁内容，并准备 abort、continue 或备用分支。

补充理解角度

• 处理补丁邮件或补丁文件
• 在仓库外部交换变更
• 保留提交边界而不是手工复制改动

这条命令在流程里解决什么问题

git format-patch 把指定范围内的提交导出为邮件格式的补丁文件，每条提交生成一个 .patch 文件。理解它时，要把它放在"补丁如何从本地历史导出到外部"这个环节中来看。

典型用例

• 把尚未共享的提交导出为补丁文件，通过邮件或其他方式发送给维护者。
• 用 --cover-letter 生成补丁序列的概述邮件，方便审阅者理解整组补丁的目的。
• 在补丁工作流中，作为 git am 的对应端：format-patch 负责导出，am 负责应用。

图例理解

输入

提交范围当前仓库历史

→git format-patch

结果

邮件格式补丁文件（.patch）可选的 cover letter

format-patch 和 am 是互补的：一个导出，一个应用，都使用邮件格式。

特殊情况与边界

• 生成补丁前应先清理提交粒度和提交说明，确保每条提交都能独立理解，否则邮件审阅和后续应用都会变得更乱。
• 补丁文件包含提交信息和 diff，但不包含构建产物或子模块内容。
• 如果生成补丁时遗漏了必要的前置提交，接收方应用时可能会遇到上下文缺失。
• 使用 --output-directory 或 -o 指定输出目录，避免补丁文件散落在工作区中。

延伸阅读

继续搭配 git status、git log、git show 一起看，通常更容易判断这条命令对历史、索引和工作区分别造成了什么影响。