git format-patch 是 Git 官方推荐的标准补丁生成命令，它将提交转为含完整元信息（作者、时间、标题、描述）的 mbox 邮件格式补丁文件，而 git diff 仅输出无上下文的裸文本差异。
什么是 git format-patch，它和 diff 有什么本质区别
直接用 git diff 生成的补丁不带提交元信息（作者、时间、标题、描述），在非 Git 环境里应用时容易丢失上下文，也难以追溯变更来源。git format-patch 才是 Git 官方推荐的标准补丁生成方式——它把每次提交转成一个独立的 mbox 风格邮件文件，含完整 commit header 和 diff 内容，可被 git am 或通用邮件工具识别。
关键差异在于：前者是“裸 diff”，后者是“可签名、可合并、可审计”的补丁包。
-
git diff HEAD~1→ 输出纯文本差异，无 author/email/subject -
git format-patch -1 HEAD→ 输出类似0001-fix-typo-in-readme.patch的文件，开头有From:、Subject:、Date: - 补丁中
--- a/...和+++ b/...行保留原始路径，避免patch -p1时路径错位
生成单个或多个标准补丁的常用命令组合
最常踩的坑是没指定范围或忽略空格/重命名处理，导致补丁在目标环境无法干净打上。
- 生成最近一次提交的补丁：
git format-patch -1 HEAD - 生成从某次提交之后的所有补丁（不含该提交）：
git format-patch abc1234（abc1234 是 SHA，补丁覆盖 abc1234^..HEAD） - 生成某次合并前的单个补丁（跳过 merge 提交）：
git format-patch --no-merges -1 HEAD - 强制统一换行符并忽略空白变化（防 Windows/Linux 混用）：
git format-patch --ignore-space-change -1 HEAD - 补丁中包含二进制文件？加
--binary，否则git am会拒绝
注意：format-patch 默认使用当前分支的 upstream（如 origin/main）作为起点，若本地未设置 tracking 分支，会报错 “fatal: no upstream configured”。先运行 git branch --set-upstream-to=origin/main 再执行。
在非 Git 环境中安全应用补丁的三种方式
所谓“非受控环境”，指没有 Git 仓库、或只有部分文件、甚至只有 tar 包解压后的目录。这时不能依赖 git am，但仍有可靠路径。
仅从仓库的暂存文件生成 Git 提交消息。当用户要求 Codex 根据暂存更改、缓存差异、Git 索引或已通过 `git add` 添加的文件来编写、起草、创建或建议提交消息时使用；切勿代表用户执行提交操作。
- 用
patch -p1 ：必须确保补丁头（From/Subject/Date）之后紧跟空行，且--- a/路径与当前目录结构匹配；常见失败是can't find file to patch，此时检查-p参数是否对齐（通常 -p1 去掉a/前缀） - 手动提取 diff 部分再打：
sed -n '/^diff --git/,/^diff --git/{/^diff --git/{x;/./p;x;};x;}' 0001-xxx.patch | patch -p1（跳过邮件头，只取 diff 块） - 若目标环境有 Python，可用
git apply的轻量替代：下载 apply.py，运行python apply.py -p1 0001-xxx.patch，它比系统patch更懂 Git 路径语义
重要提醒：补丁中若有 submodule 变更、.gitattributes 修改、或 symlink 操作，patch 工具默认不处理，这些内容会被静默跳过。
为什么 git am 在非 Git 环境里会失败，以及怎么绕过
git am 不是“打补丁”工具，而是“还原邮件式提交”的工具——它强依赖当前目录是 Git 仓库、且有完整的 .git 目录、能写 reflog、能校验 GPG 签名。一旦缺失，立刻报 fatal: not a git repository 或 error: unable to index file。
- 不要试图在非 Git 目录里硬跑
git am，哪怕你临时git init也不行：缺少原始 commit tree，am会拒绝非 fast-forward 合并 - 如果必须保留 author/committer 信息，可在目标机器建一个空仓库：
git init && git add . && git commit --allow-empty -m "baseline"，再git am，但需确认所有文件状态 clean - 更稳妥的做法是：用
git format-patch --no-signature去掉签名块，再配合patch -p1，放弃 commit 元数据，专注代码变更本身
真正容易被忽略的是时区和行尾：补丁中 Date: 字段含时区（如 +0800），某些老旧 git am 版本（Date: 即可继续。
