Git 生成 Patch 文件 — 开发实践全指南

在 Git 开发中，patch（补丁）文件用于记录代码变更，方便跨仓库、跨分支或通过邮件进行代码共享与审查。根据不同的开发场景，生成 patch 的方式主要分为两大类：git diff（纯差异，无 commit 信息）和 git format-patch（含完整 commit 元数据）。下面按实践场景逐一说明。

一、核心概念：两种 Patch 的区别

特性 git diff 生成的 patch git format-patch 生成的 patch
是否包含 commit 信息 ❌ 仅代码差异 ✅ 包含作者、日期、message 等
应用后是否自动生成 commit ❌ 需手动 git add + git commit ✅ git am 后自动生成 commit
适用场景 临时修改、未提交的改动 正式的代码审查、跨仓库协作
文件后缀 通常 .diff 或 .patch 默认 .patch，文件名含编号和主题

二、场景一：未提交的本地修改（未 git add）

工作区有修改但尚未暂存，生成 patch：

# 所有未暂存的修改  
git diff > my-changes.patch  
  
# 仅某个文件的修改  
git diff src/main.java > main.patch

三、场景二：已暂存但未提交的修改（已 git add）

# 暂存区与 HEAD 的差异  
git diff --cached > staged-changes.patch  
# 或  
git diff --staged > staged-changes.patch

四、场景三：已提交的修改（推荐使用 git format-patch）

这是最常用的场景，每个 commit 生成一个独立的 .patch 文件，保留完整的提交信息。

1. 生成最近 N 次提交的 patch

# 最近 1 次  
git format-patch -1 HEAD  
  
# 最近 3 次  
git format-patch -3 HEAD

2. 生成单个指定 commit 的 patch

git format-patch -1 <commit-sha>

3. 生成某次提交之后的所有 patch（不包含该 commit）

git format-patch <commit-sha>

4. 生成两个 commit 之间的所有 patch（包含两端）

git format-patch <commit1>..<commit2>

5. 生成从根提交到指定提交的所有 patch

git format-patch --root <commit-sha>

6. 当前分支所有超前 master 的提交

git format-patch -M master

7. 将所有 patch 合并输出到一个文件

git format-patch <commit1>..<commit2> --stdout > all-commits.patch

五、场景四：指定文件生成 patch

只想导出某些文件的修改，而非整个 commit 的差异：

# 未提交的修改，仅指定文件  
git diff -- src/main.java src/utils.java > partial.patch  
  
# 已提交的修改，仅指定文件  
git format-patch -1 HEAD -- src/main.java

六、场景五：从 stash 生成 patch

# 查看 stash 列表  
git stash list  
  
# 从指定 stash 生成 patch  
git stash show -p stash@{0} > stash-changes.patch

七、如何应用 Patch

1. 使用 git apply（适用于 git diff 生成的 patch）

# 检查 patch 是否能成功应用  
git apply --check my-changes.patch  
  
# 查看 patch 的统计信息  
git apply --stat my-changes.patch  
  
# 应用 patch（不会自动 commit）  
git apply my-changes.patch

2. 使用 git am（适用于 git format-patch 生成的 patch）

# 应用单个 patch（自动生成 commit，保留原始提交信息）  
git am 0001-fix-bug.patch  
  
# 批量应用目录下所有 patch  
git am *.patch  
  
# 遇到冲突时自动三路合并  
git am --3way 0001-fix-bug.patch  
  
# 忽略空白冲突  
git am --ignore-space-change *.patch

八、开发实践建议

场景 推荐命令 理由
临时分享未提交的改动 git diff > patch 快速、轻量
代码审查（Code Review） git format-patch -1 保留完整上下文
跨仓库移植功能 git format-patch <commit1>..<commit2> 批量、可追溯
通过邮件发送补丁 git format-patch --stdout > patch 合并为单文件
只想分享部分文件 git diff -- <file> 精确控制范围
从 stash 恢复改动 git stash show -p 灵活提取

最佳实践总结：

  • 日常协作优先使用 git format-patch + git am，因为能保留 commit 信息，方便追溯。
  • 临时/快速分享使用 git diff + git apply，轻量无负担。
  • 应用 patch 前务必先执行 git apply --check 或 git am --3way，避免冲突导致代码损坏。
  • 生成的 patch 文件建议纳入 .gitignore 或单独管理，不要混入源码目录。
posted @ 2026-07-26 11:38  LoftyAmbition  阅读(68)  评论(0)    收藏  举报