Git Patch 生成与应用完整操作手册

本文档整理 Git 补丁（patch）全套操作，包含：生成差异补丁、应用补丁、冲突解决、常用场景命令，适配日常代码同步、跨分支/跨仓库代码迁移场景，命令可直接复制使用。

一、生成 diff.patch（本地变更导出）

适用于：将本地修改导出为补丁文件，用于同步代码、备份临时修改

1.1 生成【未提交的已有文件修改】补丁（最常用）

仅包含 Git 已追踪文件的修改，不包含新建未跟踪文件

bash 复制代码

git diff > diff.patch

1.2 生成【包含新建文件】完整补丁

需先暂存所有变更，再导出缓存区补丁，包含新增、修改文件

bash 复制代码

git add .
git diff --cached > diff.patch

1.3 生成【已提交 commit】标准补丁

适用于：已完成 commit，需要导出提交记录补丁（保留作者、提交信息、时间）

bash 复制代码

# 最近 1 次提交
git format-patch -1 HEAD

# 最近 N 次提交（示例：最近3次）
git format-patch -3 HEAD

# 指定两个 commit 之间的变更补丁
git diff commit1_hash commit2_hash > commit.diff.patch

二、应用 Patch 补丁（导入变更）

所有命令需在项目根目录执行，建议操作前保持工作区干净（无未提交修改）

2.1 预检查补丁（必做，避免报错）

仅检测是否可正常应用，不修改代码文件

bash 复制代码

git apply --check diff.patch

无输出 = 补丁正常可应用；有报错 = 存在冲突或文件不匹配

2.2 普通应用补丁（无提交记录）

适用于 git diff 生成的普通补丁，仅同步代码修改，不生成 commit

bash 复制代码

git apply diff.patch

2.3 规范应用补丁（保留提交信息）

仅适用于 git format-patch 生成的补丁，自动生成 commit、保留原作者信息

bash 复制代码

git am 0001-xxx.patch

三、补丁冲突/异常解决方案

3.1 部分应用补丁（冲突文件单独处理）

可正常适配的修改自动应用，冲突部分生成 .rej 拒绝文件，手动修复

bash 复制代码

git apply --reject diff.patch

3.2 三方合并强制适配补丁

自动适配代码位置偏移导致的轻微冲突（慎用，需手动核对代码）

bash 复制代码

git apply --3way diff.patch

3.3 终止/回退补丁应用

bash 复制代码

# 撤销 git apply 应用的修改
git apply -R diff.patch

# 终止 git am 补丁合并（卡住时使用）
git am --abort

四、核心命令速查表

场景	命令
导出未提交修改补丁	git diff > diff.patch
导出含新增文件补丁	git add . && git diff --cached > diff.patch
检查补丁可用性	git apply --check diff.patch
应用普通补丁	git apply diff.patch
应用带提交信息补丁	git am xxx.patch
回退补丁修改	git apply -R diff.patch

五、最佳实践建议

临时修改同步：优先使用git diff 生成补丁，轻便无冗余信息
正式提交同步：使用 git format-patch，完整保留提交日志
打补丁前务必执行 --check 校验，避免代码混乱
补丁应用失败优先用 --reject，不建议直接强制覆盖