简体中文 ▾ 主题 ▾ 最新版本 ▾ git-apply 最后更新于 2.47.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] 生成的或通过电子邮件接收的补丁创建提交。

选项

<补丁>…​

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

--stat

不应用补丁,而是输出输入的 diff 统计。关闭“应用”功能。

--numstat

类似于 --stat,但以十进制表示法显示添加和删除的行数以及不缩写的路径名,以便更便于机器读取。对于二进制文件,输出两个 - 而不是 0 0。关闭“应用”功能。

--summary

不应用补丁,而是输出从 Git diff 扩展头部获取的信息的精简摘要,例如创建、重命名和模式更改。关闭“应用”功能。

--check

不应用补丁,而是检查补丁是否适用于当前工作树和/或索引文件,并检测错误。关闭“应用”功能。

--index

将补丁同时应用到索引和工作树(如果 --check 生效,则仅检查它是否能干净地应用到两者)。请注意,--index 要求相关路径的索引条目和工作树副本完全相同(它们的内容和元数据,如文件模式,必须匹配),如果它们不相同,即使补丁在独立情况下可以干净地应用到索引和工作树,也会引发错误。

--cached

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

--intent-to-add

仅将补丁应用到工作树时,将新文件标记为稍后添加到索引(参见 git-add[1] 中的 --intent-to-add 选项)。除非在 Git 仓库中运行且未指定 --index,否则此选项将被忽略。请注意,--index 可能会被其他选项(如 --cached--3way)隐含。

-3
--3way

如果补丁记录了它应该应用于的 blob 的标识,并且我们本地有这些 blob,则尝试三方合并,可能会在工作树中的文件中留下冲突标记供用户解决。除非使用了 --cached 选项,否则此选项隐含 --index 选项,并且与 --reject 选项不兼容。当与 --cached 选项一起使用时,所有冲突都保留在缓存的更高阶段。

--ours
--theirs
--union

不在文件中保留冲突,而是解决冲突,偏向我们(或他们或两者)的行。需要 --3way。

--build-fake-ancestor=<文件>

较新的 *git diff* 输出为每个 blob 嵌入了 *索引信息*,以帮助识别补丁所应用的原始版本。如果给定此标志,并且如果 blob 的原始版本在本地可用,则会构建一个包含这些 blob 的临时索引。

当遇到纯模式更改(没有索引信息)时,信息将从当前索引中读取。

-R
--reverse

反向应用补丁。

--reject

为确保原子性,当某些代码块不适用时,*git apply* 默认会使整个补丁失败,并且不触及工作树。此选项使其应用补丁中适用的部分,并将被拒绝的代码块保留在相应的 *.rej 文件中。

-z

当给定 --numstat 时,不混淆路径名,而是使用以 NUL 字符终止的机器可读格式。

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

-p<n>

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

-C<n>

确保在每次更改前后至少有 <n> 行周围上下文匹配。如果周围上下文行数少于 <n>,则所有行都必须匹配。默认情况下,不会忽略任何上下文。

--unidiff-zero

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

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

--apply

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

--no-add

应用补丁时,忽略补丁所做的添加。这可以用于通过首先对两个文件运行 *diff*,然后使用此选项应用结果来提取两个文件之间的公共部分,这将应用删除部分而非添加部分。

--allow-binary-replacement
--binary

历史上,未经用户明确许可,我们不允许应用二进制补丁,此标志是为此目的而设。目前,我们始终允许应用二进制补丁,因此此标志是空操作。

--exclude=<路径模式>

不将更改应用于匹配给定路径模式的文件。这在导入补丁集时很有用,当您想排除某些文件或目录时。

--include=<路径模式>

将更改应用于匹配给定路径模式的文件。这在导入补丁集时很有用,当您想包含某些文件或目录时。

当使用 --exclude--include 模式时,它们将按照在命令行中出现的顺序进行检查,并且第一个匹配项决定是否使用针对每个路径的补丁。如果命令行上没有包含模式,则默认使用不匹配任何包含/排除模式的路径的补丁;如果存在任何包含模式,则忽略该补丁。

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

应用补丁时,如果需要,忽略上下文行中空白符的更改。上下文行将保留其空白符,并且无论 --whitespace 选项的值如何,它们都不会进行空白符修复。但是,新行仍将被修复。

--whitespace=<操作>

应用补丁时,检测存在空白符错误的新行或修改行。哪些被认为是空白符错误由 core.whitespace 配置控制。默认情况下,行尾空白符(包括仅由空白符组成的行)以及行初始缩进中紧跟制表符的空格字符被视为空白符错误。

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

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

  • nowarn 关闭尾随空白符警告。

  • warn 为少数此类错误输出警告,但原样应用补丁(默认)。

  • fix 为少数此类错误输出警告,并在修复后应用补丁(strip 是同义词 — 该工具过去只将尾随空白符视为错误,修复涉及 *删除* 它们,但现代 Git 做了更多)。

  • error 为少数此类错误输出警告,并拒绝应用补丁。

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

--inaccurate-eof

在某些情况下,某些版本的 *diff* 未能正确检测文件末尾缺失的新行。因此,由这些 *diff* 程序创建的补丁未能正确记录不完整的行。此选项通过解决此错误来支持应用此类补丁。

-v
--verbose

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

-q
--quiet

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

--recount

不信任代码块头部中的行数,而是通过检查补丁来推断它们(例如,在编辑补丁后未适当调整代码块头部)。

--directory=<根目录>

将 <根目录> 前置到所有文件名。如果也传递了 "-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

Git[1] 套件的一部分

scroll-to-top