---

Git Patch 应用指南：深入理解 git apply

在软件开发和协作中，代码变更的交换是日常工作。Git 提供多种方式来分享和整合代码，最常见的是通过推送/拉取到共享仓库。然而，在某些情况下，直接访问共享仓库可能不方便或不可能，例如：

• 向开源项目贡献，但没有直接提交权限。
• 在没有网络连接的环境下传输代码变更。
• 在不同步或独立的仓库之间迁移特定变更。
• 通过电子邮件或文件共享方式交换小型代码修改。

在这种场景下，patch 文件成为了一种轻量级且灵活的解决方案。Patch 文件本质上是一个包含了代码修改指令的文本文件，它描述了在源文件基础上需要进行哪些添加、删除或修改。Git 提供了强大的工具来生成和应用这些 Patch 文件，其中 git apply 就是用于应用 Patch 的核心命令之一。

本文将带你深入了解 git apply 命令，从 Patch 的概念、如何生成 Patch 文件，到如何使用 git apply 应用 Patch 的各种场景、常用选项、故障排除以及它与 git am 的区别。

第一章：理解 Patch 文件及其作用

1.1 什么是 Patch？

Patch（补丁）源于软件开发领域，最初是用来修复 Bug 的小段代码。在版本控制系统中，Patch 更广泛地指代一种描述代码变更的格式。最常见的 Patch 格式是 Unified Diff 格式，它清晰地显示了原始文件和修改后文件之间的差异。

一个典型的 Unified Diff Patch 文件包含：

• 文件头：标识 Patch 所针对的原始文件和新文件。
• 差异块（Hunk）：描述了文件中特定区域的修改。每个差异块以 @@ ... @@ 行开始，后面跟着以 - 开头的删除行、以 + 开头的添加行以及以空格开头的上下文行。

1.2 为什么使用 Patch？

• 离线协作： 无需共享仓库或网络连接，可以通过文件轻松传输变更。
• 精细控制： 可以生成针对特定提交、特定文件甚至特定行范围的 Patch。
• 权限限制： 向没有直接写权限的仓库贡献代码的常见方式。
• 代码审查： Patch 文件通常作为代码审查的输入，评审者可以逐行查看变更。
• 自动化脚本： 可以轻松地在脚本中生成和应用 Patch。

git apply 命令就是 Git 用来读取这些 Patch 文件并将其描述的变更应用到你的工作目录或暂存区（索引）中的工具。

第二章：生成 Patch 文件（git apply 的输入来源）

虽然本文重点是应用 Patch，但了解 Patch 是如何生成的对于理解 git apply 的工作原理至关重要。Git 提供了两种主要方式来生成 Patch 文件：

2.1 使用 git diff 生成简单的 Patch

git diff 命令可以比较两个提交、工作目录与暂存区、或者工作目录与 HEAD 等之间的差异。通过重定向输出，可以生成一个简单的 Patch 文件。

“`bash

生成工作目录与 HEAD 之间的差异 Patch

git diff > my_changes.patch

生成两个提交之间的差异 Patch

git diff commit1 commit2 > feature.patch

生成特定文件在两个提交之间的差异 Patch

git diff commit1 commit2 — path/to/file > file_change.patch
“`

使用 git diff 生成的 Patch 文件适用于简单的、非提交相关的差异。它的优点是简单直接，但缺点是生成的 Patch 文件不包含 Git 的提交元数据（如作者、提交信息、提交哈希），这使得在使用 git am（另一个应用 Patch 的命令）时无法重建原始提交。然而，git apply 可以很好地处理这种格式的 Patch。

2.2 使用 git format-patch 生成带提交元数据的 Patch

git format-patch 命令专门用于将 Git 提交转换为 Patch 文件。它生成的 Patch 文件遵循一种更丰富的格式，包含了提交的作者、提交者、提交日期、提交信息以及实际的代码差异。这种格式的 Patch 更适合通过电子邮件发送，并且可以被 git am 命令识别并用来重建提交历史。

“`bash

生成最近一次提交的 Patch

git format-patch -1 HEAD

生成从指定提交到当前 HEAD 的所有提交的 Patch

git format-patch

生成指定提交范围内的 Patch (不包含 start_commit，包含 end_commit)

git format-patch ..

生成最近 N 个提交的 Patch

git format-patch -N HEAD

将 Patch 文件输出到指定目录

git format-patch -o patches/ HEAD~3..HEAD
“`

git format-patch 生成的 Patch 文件通常以 NNNN-Subject.patch 的格式命名，其中 NNNN 是序号，Subject 是提交信息的主题行。

对于 git apply 而言，它既可以应用 git diff 生成的简单 Patch，也可以应用 git format-patch 生成的包含元数据的 Patch。但 git apply 默认情况下不会利用 Patch 中的提交元数据来创建新的提交。

第三章：使用 git apply 应用 Patch

现在我们来到了核心部分：如何使用 git apply 命令来应用 Patch 文件。

3.1 基本用法

git apply 的最基本用法是指定要应用的 Patch 文件路径：

bash
git apply /path/to/your.patch

执行此命令后，git apply 会读取 your.patch 文件中的差异描述，并尝试将这些变更应用到你当前工作目录中的文件。

重要： git apply 默认情况下只会修改你的 工作目录 中的文件，并将这些修改添加到 暂存区（索引）。它不会自动为你创建一个新的提交。这意味着应用 Patch 后，你需要使用 git status 查看变更，然后使用 git commit 手动创建提交。

3.2 常用选项详解

git apply 提供了丰富的选项来控制 Patch 的应用方式和行为。以下是一些最常用且重要的选项：

• --stat：显示 Patch 统计信息

  在实际应用 Patch 之前，使用 --stat 选项可以让你预览 Patch 将会修改哪些文件，以及每个文件的大致变更行数（添加、删除）。这对于在应用 Patch 前了解其影响范围非常有帮助。

  bash
git apply --stat your.patch

  输出示例：

  path/to/file_a.c | 10 +++++-----
path/to/file_b.h | 5 +++++
another/file.txt | 2 +-
3 files changed, 17 insertions(+), 7 deletions(-)

• --check：检查 Patch 是否可以干净地应用

  这是在使用 git apply 之前 强烈推荐使用的选项。--check 选项会模拟 Patch 应用过程，但不会实际修改任何文件。它会检查 Patch 是否与当前代码状态兼容，是否存在冲突等问题。如果 Patch 可以干净地应用，命令不会有输出（或者只输出一些成功信息），并返回退出码 0。如果存在问题（如冲突），它会报告错误。

  bash
git apply --check your.patch

  如果输出 error: patch failed: ... 或其他错误信息，说明 Patch 无法直接应用。如果没有错误输出，则表示 Patch 很有可能成功应用。

• --reject：处理冲突时生成拒绝文件

  当 Patch 文件中的某些差异块（hunk）无法干净地应用（即 Patch 尝试修改的代码行与当前文件的内容不匹配，发生冲突）时，默认情况下 git apply 会停止并报错。使用 --reject 选项可以改变这种行为：Git 会尽力应用 Patch 中可以应用的部分，并将无法应用的差异块写入到以 .rej 为后缀的拒绝文件（reject file）中。

  例如，如果 your.patch 尝试修改 file_a.c 并且发生冲突，使用 --reject 后，git apply 会在应用成功的部分后，生成一个 file_a.c.rej 文件，其中包含了未能应用的差异块。

  bash
git apply --reject your.patch

  应用后，你需要检查工作目录，找到所有 .rej 文件，并手动解决这些冲突。解决冲突的过程类似于 Git 合并冲突：查看原始文件、Patch 文件和 .rej 文件，手动编辑文件使其包含期望的最终状态，然后删除 .rej 文件。

• --directory <path>：在子目录中应用 Patch

  这个选项非常有用，特别是当你拿到的 Patch 文件是相对于一个项目根目录生成的，但你的当前工作目录是该项目的一个子目录，或者你需要将 Patch 应用到项目中的一个特定子目录时。--directory <path> 选项告诉 Git，Patch 文件中描述的所有文件路径都应该被解释为相对于 <path> 目录。

  假设你的项目结构是：

  my_project/
├── src/
│ ├── main.c
│ └── utils.c
└── docs/
└── README.md

  你有一个 patch 文件，它包含了对 src/main.c 的修改，并且 Patch 文件中的路径是 src/main.c。

  • 如果你在 my_project/ 目录下执行 git apply the.patch，Git 会直接找到 src/main.c 并应用。
  • 但如果你在 my_project/docs/ 目录下，直接执行 git apply the.patch 会失败，因为 Git 会查找 docs/src/main.c。
  • 这时，你可以在 my_project/docs/ 目录下执行 git apply --directory .. the.patch。--directory .. 告诉 Git 在应用 Patch 时，将所有路径视为相对于上一级目录 (..，即 my_project/)，这样 Git 就能找到 src/main.c 并正确应用 Patch。

  “`bash

  在项目根目录应用针对子目录的 Patch

  git apply –directory src/ feature.patch
  “`

  这个命令会将 feature.patch 中描述的对文件 file.c 的修改应用到 src/file.c，前提是 Patch 文件中的路径是 file.c。如果 Patch 文件中的路径是 src/file.c，而你想在项目根目录应用它，就不需要 --directory。

  理解关键： --directory <path> 是修改 Patch 文件中路径的解释方式，而不是改变 git apply 命令执行的当前目录。Patch 中的 a/path/to/file 在没有 --directory 时被解释为相对于当前目录的 a/path/to/file。有了 --directory subdir/，它就被解释为相对于 subdir/ 的 a/path/to/file，即 subdir/a/path/to/file。

• --ignore-whitespace / --whitespace=(nowarn|warn|fix|error|...)：忽略或处理空白符差异

  空白符（空格、制表符、行尾换行符等）问题是应用 Patch 时常见的麻烦来源。如果 Patch 和你的文件在空白符上有差异（即使代码内容相同），可能会导致 Patch 应用失败。

  • --ignore-whitespace: 让 Git 在比较和应用 Patch 时忽略空白符的差异。这可以帮助应用那些因为空白符不匹配而失败的 Patch。

  bash
git apply --ignore-whitespace your.patch

  • --whitespace=(...): 更精细地控制空白符处理。例如：
    • --whitespace=warn: 发现空白符问题时发出警告，但不阻止应用。
    • --whitespace=fix: 尝试自动修复空白符问题（如移除行尾空格）。
    • --whitespace=error: 如果发现空白符问题则报错并中止。

  选择哪个选项取决于你对空白符的严格程度以及 Patch 的具体问题。

• --reverse：反向应用 Patch（撤销修改）

  如果你想撤销之前应用的一个 Patch，可以使用 --reverse 选项。这会将 Patch 中描述的添加变为删除，删除变为添加。

  bash
git apply --reverse your.patch

  这相当于用 Patch 描述的旧状态替换当前文件的新状态。请谨慎使用此选项，确保 Patch 是你想要撤销的变更的精确逆过程。

• --3way：尝试三向合并应用 Patch

  当 Patch 无法干净地应用时，通常是因为 Patch 基于的代码版本与你当前的版本发生了分歧（即你的代码在这之后也被修改了）。--3way 选项指示 Git 尝试使用三向合并（three-way merge）策略来应用 Patch。这类似于 git merge 命令，需要找到一个共同的祖先版本。

  Git 会尝试找出 Patch 所基于的原始文件内容，然后将其与你的当前文件内容以及 Patch 中的新内容进行比较，尝试自动合并。如果存在冲突，Git 会在文件中标记冲突区域（类似于 git merge 冲突标记），你需要手动解决这些冲突。

  bash
git apply --3way your.patch

  使用 --3way 的前提是 Patch 文件必须是由 git format-patch 生成的，因为它需要 Patch 中包含的上下文信息来确定原始版本。如果 Patch 无法通过三向合并自动解决所有冲突，Git 会留下冲突标记，并可能同时使用 --reject 选项（即使你没有明确指定）。

• --cached / --index：仅将变更应用到暂存区 (Index)

  默认情况下，git apply 会修改工作目录和暂存区。使用 --cached 或 --index 选项，Patch 的变更将只被应用到暂存区，而不会修改你的工作目录文件。

  “`bash
  git apply –cached your.patch

  或

  git apply –index your.patch
  “`

  这意味着应用 Patch 后，git status 会显示文件在 “Changes to be committed” 区域，但工作目录中的文件内容可能与暂存区不同（如果你之前对这些文件有未暂存的修改）。这个选项在你希望将 Patch 的内容直接暂存起来，稍后一起提交或与工作目录的修改分阶段处理时很有用。

  注意： 当 Patch 是由 git format-patch 生成时，并且包含了模式（如文件权限）、复制/重命名信息等，--cached 选项会尝试尽可能地保留这些信息并应用到暂存区，使其更接近原始提交。

• --allow-empty：允许应用空的 Patch

  有些 Patch 文件可能描述了一个“空提交”（没有实际文件内容修改的提交，例如只修改了提交信息）。git apply 默认情况下可能会拒绝应用这种空的 Patch。使用 --allow-empty 选项可以强制应用它们，即使没有任何文件被修改。

  bash
git apply --allow-empty empty.patch

3.3 应用多个 Patch 文件

如果你有多个 Patch 文件需要按顺序应用，可以将它们的内容合并后传递给 git apply，或者使用脚本循环应用。

方法一：合并 Patch 文件内容（适用于简单的非 format-patch Patch 或按顺序合并）

bash
cat patch1.patch patch2.patch patch3.patch | git apply

这种方法适用于 Patch 之间没有复杂依赖关系，或者它们是简单的 git diff Patch。如果 Patch 之间有顺序依赖（后一个 Patch 基于前一个 Patch 的结果），这种方法可能不适用，因为 git apply 接收的是一个合并后的总差异。

方法二：按顺序循环应用（推荐用于 format-patch 生成的多个 Patch）

如果你有多个由 git format-patch 生成的、带有序号的 Patch 文件（例如 0001-fix.patch, 0002-feat.patch），它们通常代表了一系列的提交，应该按顺序应用。可以使用 shell 脚本来循环执行 git apply：

“`bash

假设 Patch 文件都在当前目录且按名称排序即是按顺序

for patch_file in *.patch; do
echo “Applying $patch_file…”
git apply “$patch_file” –check # 先检查
if [ $? -eq 0 ]; then
git apply “$patch_file”
if [ $? -ne 0 ]; then
echo “Error applying $patch_file. Aborting.”
exit 1
fi
else
echo “Patch $patch_file check failed. Aborting.”
exit 1
fi
done
“`

这段脚本首先对每个 Patch 进行 --check 检查，如果通过则实际应用。遇到任何错误都会停止。你可以根据需要添加 --reject, --3way 或其他选项。

重要提示： 如果你应用的是由 git format-patch 生成的多个 Patch，并且你希望它们被应用为一系列独立的提交，保留原始的作者信息和提交信息，那么你应该使用 git am 命令而不是 git apply。git am 专门用于处理 mbox 格式的 Patch 文件（format-patch 的默认输出格式），并会自动创建提交。我们将在后续章节对比 git apply 和 git am。

第四章：git apply 故障排除

应用 Patch 并非总是顺利，可能会遇到各种问题。了解如何诊断和解决这些问题是掌握 git apply 的关键。

4.1 常见错误信息及解决方法

• error: patch failed: <file>:<line>

  • 原因： 这是最常见的错误，表示 Patch 尝试修改的文件内容与你当前文件的内容不匹配，导致 Patch 的差异块无法应用到指定位置。这通常是由于：
    • 你当前的分支与 Patch 所基于的分支差异太大。
    • 在 Patch 生成后，目标文件被修改过。
    • 空白符或行尾换换符不匹配。
  • 解决方法：
    • 使用 --check 预检： 在应用前总是先用 git apply --check your.patch 检查是否能应用。
    • 使用 --stat 查看： 看看 Patch 到底修改了哪些文件，对照你的工作目录检查这些文件的状态。
    • 使用 --reject 手动解决冲突： 运行 git apply --reject your.patch。Git 会应用能成功的部分，留下 .rej 文件。然后手动编辑原始文件，将 .rej 文件中的修改内容整合进去，解决冲突，并删除 .rej 文件。
    • 使用 --3way 尝试三向合并： 如果 Patch 是由 git format-patch 生成的，尝试 git apply --3way your.patch。Git 会尝试像合并一样处理冲突，并在文件中标记冲突区域。你需要手动编辑文件解决冲突。
    • 检查空白符： 如果怀疑是空白符问题，尝试 git apply --ignore-whitespace your.patch 或 --whitespace=fix。
    • 确保基准正确： 确认你当前工作的分支或提交是 Patch 生成时所基于的正确版本附近。可能需要切换到或 rebase 到更接近 Patch 来源的位置。

• error: unrecognized input / error: invalid patch system

  • 原因： git apply 无法识别 Patch 文件的格式。可能是文件损坏，或者不是标准的 Unified Diff 或 Git Patch 格式。
  • 解决方法：
    • 检查文件内容： 用文本编辑器打开 Patch 文件，检查它是否看起来像一个正常的差异文件（包含 ---, +++, @@ ... @@, -, +, 等）。
    • 确认生成方式： 如果是你生成的 Patch，确认使用了 git diff 或 git format-patch。如果是别人提供的，询问其生成方式或重新获取 Patch 文件。
    • 文件编码问题： 确保文件编码正确，通常是 UTF-8 或 ASCII。

• Patch 应用成功但结果不符合预期

  • 原因：
    • 应用了错误的 Patch 文件。
    • Patch 文件本身有误。
    • Patch 是在与你当前环境不同的行尾换行符设置下生成的，即使应用成功也可能导致文件看起来不一样。
    • Patch 中包含了文件模式（可执行权限等）或重命名/复制操作，而你没有使用 --cached 或 --index 来保留这些信息（尽管 git apply 通常能处理这些，但在某些情况下可能导致意外）。
  • 解决方法：
    • 仔细检查 Patch 文件： 使用文本编辑器或 git apply --stat 再次确认 Patch 的内容。
    • 检查当前文件状态： 确保应用 Patch 前，你的工作目录和暂存区是干净的，或者你清楚知道其中包含哪些修改。
    • 检查行尾换行符： 检查你的 Git 配置 (git config core.autocrlf) 和 Patch 文件的行尾换行符是否一致。必要时可以调整配置或在应用前转换 Patch 文件。
    • 使用 --cached 应用： 如果 Patch 包含模式或重命名信息，尝试使用 git apply --cached 应用到暂存区，然后检查暂存区的状态 (git diff --cached)。

4.2 使用日志和状态进行调试

• git status： 应用 Patch 后立即运行 git status。它会告诉你哪些文件被修改、添加或删除，以及哪些文件因为冲突生成了 .rej 文件。
• git diff： 应用 Patch 后，使用 git diff 查看工作目录与暂存区之间的差异，或者使用 git diff HEAD 查看工作目录与最新提交之间的差异。这可以帮助你确认 Patch 的修改是否正确应用，以及是否存在未暂存的修改。如果使用了 --cached，则使用 git diff --cached 查看暂存区与 HEAD 的差异。
• 查看 .rej 文件： 如果使用了 --reject，仔细查看生成的 .rej 文件，它精确地告诉你哪些差异块未能应用，以及 Patch 期望的原始上下文和你的文件实际的上下文。这有助于理解冲突发生的原因。

第五章：git apply 与 git am 的区别与选择

git apply 和 git am 都可以用来应用 Patch 文件，但它们的设计目的和使用场景有所不同。理解它们的区别对于选择正确的工具至关重要。

• git apply:

  • 作用： 应用差异文件（Patch）到 工作目录 和 暂存区。
  • 输入： 可以处理简单的 git diff 格式的 Patch，也可以处理 git format-patch 格式的 Patch。
  • 输出： 修改工作目录和暂存区的文件。默认不创建提交。
  • 元数据： 默认忽略 Patch 文件中的提交元数据（作者、日期、提交信息）。使用 --cached/--index 时，会尽可能利用模式和重命名/复制信息应用到暂存区。
  • 冲突处理： 提供 --reject, --3way 等选项来处理冲突。
  • 适用场景： 应用简单的差异；在脚本中应用 Patch；将 Patch 内容应用到工作目录以便手动整合和提交；处理不包含完整提交元数据的 Patch。

• git am (Apply Mailbox):

  • 作用： 应用 Patch 文件（通常以 mbox 格式组织）并自动创建 Git 提交。
  • 输入： 主要设计用于处理 git format-patch 生成的 Patch 文件或符合 mbox 格式的 Patch 文件集合。它依赖于 Patch 文件中的提交元数据。
  • 输出： 在当前分支上创建新的提交（或一系列提交），每个 Patch 对应一个提交。
  • 元数据： 会 利用 Patch 文件中的提交元数据（作者、日期、提交信息）来创建提交。
  • 冲突处理： 如果遇到冲突，会停止应用过程，用户需要手动解决冲突，然后使用 git am --continue 或 git am --skip。
  • 适用场景： 应用通过电子邮件接收的 Patch 系列；将 git format-patch 生成的 Patch 应用为独立的提交，保留原始作者信息；进行 Patch 形式的代码贡献（如向邮件列表提交）。

总结：

• 如果你只是想把一个差异文件应用到你的代码中，修改工作目录和暂存区，然后自己决定如何提交，使用 git apply。
• 如果你接收到的是由 git format-patch 生成的一个或多个 Patch 文件，代表了一系列提交，并且你希望将这些 Patch 应用为独立的提交，保留原始的作者信息和提交历史，那么使用 git am。

在实际使用中，很多从开源社区下载的 Patch 都是由 git format-patch 生成的，因此 git am 可能是更常见的用于应用这些 Patch 的工具，因为它能更好地重建提交历史。但 git apply 在处理简单 diff、脚本化应用或只需要修改工作目录/暂存区时，仍然是一个非常强大和灵活的工具。

第六章：使用 git apply 的最佳实践

• 先检查，后应用： 在执行 git apply your.patch 之前，务必先执行 git apply --check your.patch。这可以让你提前发现并解决冲突，避免在应用过程中遇到问题。
• 保持工作目录干净： 在应用 Patch 之前，尽量确保你的工作目录和暂存区是干净的 (git status 显示 “nothing to commit, working tree clean”)。这样可以最大程度地减少 Patch 应用与你现有修改之间的冲突，并更容易确定 Patch 带来的具体变更。
• 使用 --stat 预览： 应用 Patch 前，使用 git apply --stat your.patch 快速了解 Patch 的大致内容和影响范围。
• 了解 Patch 来源： 清楚 Patch 是如何生成的（git diff 还是 git format-patch），这有助于你选择合适的应用策略（例如是否考虑使用 --3way 或 git am）。
• 处理冲突： 如果应用 Patch 时遇到冲突，不要慌。使用 --reject 获取 .rej 文件，然后仔细分析 .rej 文件、原始文件和 Patch 文件，手动编辑解决冲突。或者，如果 Patch 适合，尝试使用 --3way 进行合并。
• 考虑使用 --cached： 如果 Patch 包含文件模式、重命名或复制信息，或者你希望 Patch 的修改直接进入暂存区以便更方便地管理和提交，考虑使用 git apply --cached。
• 提交应用后的变更： 除非你有特定的理由不立即提交，应用 Patch 后，通常应该使用 git commit 将这些变更保存为新的提交。如果你使用了 git apply (而非 git am)，这个提交将使用你的作者信息和当前的提交时间。

结论

git apply 是 Git 工具箱中一个基础且功能强大的命令。它提供了一种灵活的方式来应用各种形式的 Patch 文件，无论是简单的差异还是由 git format-patch 生成的带元数据的 Patch。通过熟练掌握 git apply 的基本用法和常用选项，特别是 --check, --stat, --reject, --directory, --ignore-whitespace, --3way 和 --cached，你将能够有效地在各种场景下管理和整合代码变更。

理解 git apply 和 git am 之间的区别有助于你在不同的协作工作流中选择最合适的工具。尽管对于标准的代码贡献流程（如通过邮件列表），git am 可能是更推荐的选择，但 git apply 在脚本自动化、处理非标准 Patch、精细控制变更应用到工作目录或暂存区等方面，具有其独特的价值。

通过本文的详细指南，希望你已经对 git apply patch 有了全面而深入的理解，并能在日常开发中自信地运用它。记住实践是掌握任何 Git 命令的关键，多尝试不同的 Patch 和选项，你会越来越得心应手。

---