简体中文 ▾ 主题 ▾ 最新版本 ▾ git-apply 最后更新于 2.51.0

名称

git-apply - 应用补丁到文件和/或索引

概要

git apply [--stat] [--numstat] [--summary] [--check]
	  [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]
	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
	  [--allow-binary-replacement | --binary] [--reject] [-z]
	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
	  [--ignore-space-change | --ignore-whitespace]
	  [--whitespace=(nowarn|warn|fix|error|error-all)]
	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
	  [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>…​]

描述

读取提供的 diff 输出（即“补丁”）并将其应用于文件。当在仓库的子目录中运行时，该目录之外的补丁路径将被忽略。使用 --index 选项时，补丁还会应用于索引；使用 --cached 选项时，补丁仅应用于索引。如果不使用这些选项，该命令仅将补丁应用于文件，且不要求它们在 Git 仓库中。

此命令仅应用补丁但不创建提交。使用 git-am[1] 从 git-format-patch[1] 生成的和/或通过电子邮件接收的补丁中创建提交。

选项

<patch>…​

从中读取补丁的文件。可以使用 - 从标准输入读取。

--stat

不应用补丁，而是输出输入内容的 diffstat。此选项会关闭“应用 (apply)”功能。

--numstat

类似于 --stat，但以十进制表示法显示添加和删除的行数，并显示不带缩写的路径名，使其对机器更友好。对于二进制文件，输出两个 - 而不是 0 0。此选项会关闭“应用 (apply)”功能。

--summary

不应用补丁，而是输出从 git diff 扩展头中获取的信息的简要摘要，例如创建、重命名和模式更改。此选项会关闭“应用 (apply)”功能。

--check

不应用补丁，而是检查补丁是否适用于当前工作树和/或索引文件，并检测错误。此选项会关闭“应用 (apply)”功能。

--index

将补丁同时应用于索引和工作树（或者如果 --check 生效，则仅检查它是否能干净地应用于两者）。请注意，--index 要求相关路径的索引条目和工作树副本必须完全一致（其内容和元数据如文件模式必须匹配），如果不一致，即使补丁能分别干净地应用于索引和工作树，也会报错。

--cached

仅将补丁应用于索引，而不触及工作树。如果 --check 生效，则仅检查它是否能干净地应用于索引条目。

-N
--intent-to-add

当仅将补丁应用于工作树时，将新文件标记为稍后添加到索引（参见 git-add[1] 中的 --intent-to-add 选项）。如果使用了 --index 或 --cached，则忽略此选项；在 Git 仓库之外此选项无效。请注意，--index 可能会被其他选项（如 --3way）隐式启用。

-3
--3way

如果补丁记录了它应该应用的 blob 的身份，且本地有这些 blob 可用，则尝试进行三路合并，可能会在工作树的文件中留下冲突标记供用户解决。除非使用了 --cached 选项，否则此选项隐含了 --index 选项，并且与 --reject 选项不兼容。当与 --cached 选项一起使用时，任何冲突都会留在缓存的更高层级中。

--ours
--theirs
--union

与其在文件中留下冲突，不如通过偏向我们（或他们，或双方）的行来解决冲突。需要 --3way。

--build-fake-ancestor=<file>

较新的 git diff 输出包含每个 blob 的 索引信息 (index information)，以帮助识别补丁适用的原始版本。当给出此标志且本地提供 blob 的原始版本时，将构建一个包含这些 blob 的临时索引。

当遇到纯模式更改（没有索引信息）时，信息将改为从当前索引中读取。

-R
--reverse

反向应用补丁。

--reject

为了原子性，默认情况下，如果某些数据块（hunks）无法应用，git apply 会使整个补丁失败且不触及工作树。此选项使其应用补丁中可应用的部分，并将被拒绝的数据块留在相应的 *.rej 文件中。

-z

当给出 --numstat 时，不要转换路径名，而是使用以 NUL 字符结尾的机器可读格式。

如果没有此选项，包含“不寻常”字符的路径名将按照配置变量 core.quotePath 的解释进行引用（参见 git-config[1]）。

-p<n>

从传统 diff 路径中移除 <n> 个前导路径组件（由斜杠分隔）。例如，使用 -p2 时，针对 a/dir/file 的补丁将直接应用于 file。默认值为 1。

-C<n>

确保每次更改前后至少有 <n> 行周围上下文匹配。当存在的上下文行数少于此数时，它们必须全部匹配。默认情况下，从不忽略任何上下文。

--unidiff-zero

默认情况下，git apply 期望所应用的补丁是至少具有一行上下文的统一 diff。这提供了良好的安全措施，但在应用使用 --unified=0 生成的 diff 时会失效。要绕过这些检查，请使用 --unidiff-zero。

注意，由于上述原因，不鼓励使用无上下文的补丁。

--apply

如果您使用了上述任何标记为“关闭 apply”的选项，git apply 将读取并输出请求的信息，而不会实际应用补丁。在这些标志之后给出此标志可以同时应用补丁。

--no-add

应用补丁时，忽略补丁所做的添加。这可以用于提取两个文件之间的公共部分：首先对它们运行 diff，然后使用此选项应用结果，这将应用删除部分但不应用添加部分。

--allow-binary-replacement
--binary

历史上，如果没有用户的明确许可，我们不允许应用二进制补丁，而这个标志就是许可方式。目前，我们始终允许应用二进制补丁，因此这是一个空操作。

--exclude=<path-pattern>

不要将更改应用于匹配给定路径模式的文件。这在导入补丁集时很有用，因为您可能希望排除某些文件或目录。

--include=<path-pattern>

将更改应用于匹配给定路径模式的文件。这在导入补丁集时很有用，因为您可能希望包含某些文件或目录。

当使用 --exclude 和 --include 模式时，将按它们在命令行中出现的顺序进行检查，第一个匹配项决定是否使用对应路径的补丁。如果命令行中没有 include 模式，默认使用不匹配任何 include/exclude 模式的路径补丁；如果存在任何 include 模式，则忽略不匹配的补丁。

--ignore-space-change
--ignore-whitespace

应用补丁时，如有必要，忽略上下文行中空白字符的变化。上下文行将保留其空白，且无论 --whitespace 选项的值如何，都不会进行空白修复。不过，新行仍会被修复。

--whitespace=<action>

应用补丁时，检测具有空白错误的新行或修改行。什么被视为空白错误由 core.whitespace 配置控制。默认情况下，行尾空白（包括完全由空白组成的行）以及在行初始缩进内紧跟在制表符后的空格字符被视为空白错误。

默认情况下，该命令输出警告消息但仍应用补丁。当 git-apply 用于统计而不应用补丁时，它默认为 nowarn。

您可以使用不同的 <action> 值来控制此行为：

  • nowarn 关闭行尾空白警告。

  • warn 对此类错误输出警告，但按原样应用补丁（默认）。

  • fix 对此类错误输出警告，并在修复后应用补丁（strip 是同义词 —— 以前该工具仅将行尾空白字符视为错误，修复方式是 剥离 (stripping) 它们，但现代 Git 能做更多）。

  • error 对此类错误输出警告，并拒绝应用补丁。

  • error-all 类似于 error 但显示所有错误。

--inaccurate-eof

在某些情况下，某些版本的 diff 无法正确检测文件末尾缺失的换行符。因此，此类 diff 程序创建的补丁无法正确记录不完整的行。此选项通过规避此错误来支持应用此类补丁。

-v
--verbose

向标准错误报告进度。默认情况下，仅打印关于当前正在应用的补丁的消息。此选项将导致报告额外信息。

-q
--quiet

抑制标准错误输出。将不打印关于补丁状态和进度的消息。

--recount

不信任数据块头中的行数，而是通过检查补丁来推断行数（例如在编辑补丁后没有相应调整数据块头）。

--directory=<root>

将 <root> 添加到所有文件名的开头。如果还传递了 "-p" 参数，则它在添加新根路径之前应用。

例如，一个涉及将 a/git-gui.sh 更新为 b/git-gui.sh 的补丁，可以通过运行 git apply --directory=modules/git-gui 应用到工作树中的文件 modules/git-gui/git-gui.sh。

--unsafe-paths

默认情况下，如果补丁影响工作区之外（无论是 Git 控制的工作树，还是当 "git apply" 用作 GNU patch 的替代品时的当前工作目录），它都会作为错误（或恶意操作）而被拒绝。

当 git apply 用作“更好的 GNU patch”时，用户可以传递 --unsafe-paths 选项来覆盖此安全检查。当使用 --index 或 --cached 时，此选项无效。

--allow-empty

对于不包含 diff 的补丁不返回错误。这包括空补丁和仅包含提交文本的补丁。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

apply.ignoreWhitespace

当设置为 change 时，告诉 git apply 忽略空白变化，方式与 --ignore-space-change 选项相同。当设置为：no, none, never, false 之一时，告诉 git apply 尊重所有空白差异。参见 git-apply[1]。

apply.whitespace

告诉 git apply 如何处理空白，方式与 --whitespace 选项相同。参见 git-apply[1]。

子模块

如果补丁包含对子模块的任何更改，则 git apply 按如下方式处理这些更改。

如果指定了 --index（显式或隐式），则子模块提交必须与索引完全匹配，补丁才能应用。如果任何子模块已检出，则这些检出将被完全忽略，即不要求它们是最新的或干净的，且它们不会被更新。

如果未指定 --index，则补丁中的子模块提交将被忽略，仅检查相应子目录是否存在，并在可能的情况下进行更新。

另请参阅

git-am[1].

GIT

Git[1] 套件的一部分