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

名称

git-am - 从邮箱中应用一系列补丁

概要

git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]
	 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
	 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
	 [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
	 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
	 [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
	 [--quoted-cr=<action>]
	 [--empty=(stop|drop|keep)]
	 [(<mbox> | <Maildir>)…​]
git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)

描述

将邮箱中的邮件拆分为提交日志消息、作者信息和补丁，并将它们应用到当前分支。可以将其视为在没有合并的线性历史分支上运行 git-format-patch[1] 的逆操作。

选项

(<mbox>|<Maildir>)…​

用于读取补丁的邮箱文件列表。如果不提供此参数，命令将从标准输入读取。如果提供了目录，它们将被视为 Maildir。

-s
--signoff

在提交消息中添加一个 Signed-off-by 追踪信息（参见 git-interpret-trailers[1]），使用您自己的提交者身份。有关更多信息，请参阅 git-commit[1] 中的 signoff 选项。

-k
--keep

将 -k 标志传递给 git-mailinfo[1]。

--keep-non-patch

将 -b 标志传递给 git-mailinfo[1]。

--keep-cr
--no-keep-cr

使用 --keep-cr 时，调用 git-mailsplit[1] 并带上相同的选项，以防止其去除行尾的 CR（回车符）。配置变量 am.keepcr 可用于指定默认行为。--no-keep-cr 可用于覆盖 am.keepcr。

-c
--scissors

移除剪刀线之前正文中的所有内容（参见 git-mailinfo[1]）。可以使用配置变量 mailinfo.scissors 默认启用此功能。

--no-scissors

忽略剪刀线（参见 git-mailinfo[1]）。

--quoted-cr=<action>

此标志将传递给 git-mailinfo[1]。

--empty=(drop|keep|stop)

如何处理缺少补丁的电子邮件

drop

忽略该电子邮件。

keep

创建一个空提交，并将电子邮件的内容作为提交日志。

stop

命令将失败并在当前的 am 会话中停止。这是默认行为。

-m
--message-id

将 -m 标志传递给 git-mailinfo[1]，以便将 Message-ID 头部添加到提交消息中。配置变量 am.messageid 可用于指定默认行为。

--no-message-id

不要将 Message-ID 头部添加到提交消息中。--no-message-id 可用于覆盖 am.messageid。

-q
--quiet

静默模式。仅打印错误消息。

-u
--utf8

将 -u 标志传递给 git-mailinfo[1]。从电子邮件获取的建议提交日志消息将被重新编码为 UTF-8 编码（如果项目首选编码不是 UTF-8，可以使用配置变量 i18n.commitEncoding 指定）。

这在以前版本的 git 中是可选的，但现在是默认行为。您可以使用 --no-utf8 来覆盖此设置。

--no-utf8

将 -n 标志传递给 git-mailinfo[1]。

-3
--3way
--no-3way

当补丁不能干净地应用时，如果补丁记录了它应该应用的 blob 的标识，并且我们在本地拥有这些 blob，则回退到 3-way 合并。--no-3way 可用于覆盖 am.threeWay 配置变量。有关更多信息，请参阅 git-config[1] 中的 am.threeWay。

--rerere-autoupdate
--no-rerere-autoupdate

在 rerere 机制对当前冲突重用已记录的解决方案以更新工作区中的文件后，允许它同时使用解决方案的结果更新索引。--no-rerere-autoupdate 是在将结果提交到索引之前，通过单独的 git-add[1] 仔细检查 git-rerere[1] 所做操作并捕获潜在错误合并的好方法。

--ignore-space-change
--ignore-whitespace
--whitespace=<action>
-C<n>
-p<n>
--directory=<dir>
--exclude=<path>
--include=<path>
--reject

这些标志被传递给应用补丁的 git-apply[1] 程序。

--whitespace 选项的有效 <action> 为：nowarn, warn, fix, error, 和 error-all。

--patch-format

默认情况下，命令会尝试自动检测补丁格式。此选项允许用户跳过自动检测并指定补丁应被解释为的格式。有效格式包括 mbox, mboxrd, stgit, stgit-series, 和 hg。

-i
--interactive

以交互方式运行。

--verify
-n
--no-verify

运行 pre-applypatch 和 applypatch-msg 钩子。这是默认设置。使用 -n 或 --no-verify 跳过这些钩子。另请参阅 githooks[5]。

请注意，post-applypatch 无法跳过。

--committer-date-is-author-date

默认情况下，该命令将电子邮件中的日期记录为提交作者日期，并将提交创建的时间用作提交者日期。此选项允许用户通过使用与作者日期相同的值来伪造提交者日期。

警告
 历史遍历机制假定提交具有非递减的提交时间戳。您应该考虑是否真的需要使用此选项。仅当您在比您正在应用的最旧补丁更旧（基于提交日期）的基准之上应用提交时，才应使用此选项来覆盖提交者日期。
--ignore-date

默认情况下，该命令将电子邮件中的日期记录为提交作者日期，并将提交创建的时间用作提交者日期。此选项允许用户通过使用与提交者日期相同的值来伪造作者日期。

--skip

跳过当前补丁。这仅在重新启动已中止的补丁应用过程时才有意义。

-S[<keyid>]
--gpg-sign[=<keyid>]
--no-gpg-sign

GPG 签名提交。*keyid* 参数是可选的，默认为提交者身份；如果指定，则必须将其紧贴选项，中间无空格。*--no-gpg-sign* 对于抵消 *commit.gpgSign* 配置变量和先前的 *--gpg-sign* 非常有用。

--continue
-r
--resolved

在补丁失败（例如尝试应用有冲突的补丁）后，用户已手动应用它，并且索引文件存储了应用的结果。使用从电子邮件中提取的作者身份和提交日志以及当前索引文件进行提交，并继续。

--resolvemsg=<msg>

当补丁失败时，在退出前会将 <msg> 打印到屏幕上。这将覆盖告知您使用 --continue 或 --skip 处理失败的标准消息。这仅供 git-rebase[1] 和 git-am[1] 内部使用。

--abort

恢复原始分支并中止补丁操作。将 am 操作涉及的文件内容恢复到 am 之前的状态。

--quit

中止补丁操作，但保持 HEAD 和索引不受影响。

--retry

尝试再次应用上一个冲突的补丁。这通常仅在向重试尝试传递额外选项（例如 --3way）时有用，否则您只会再次看到相同的失败。

--show-current-patch[=(diff|raw)]

显示 git-am[1] 因冲突而停止时的消息。如果指定了 raw，则显示电子邮件的原始内容；如果为 diff，则仅显示 diff 部分。默认为 raw。

--allow-empty

在对缺少补丁的输入电子邮件补丁失败后，创建一个内容为电子邮件消息的空提交。

讨论

提交作者姓名取自消息的“From: ”行，提交作者日期取自消息的“Date: ”行。“Subject: ”行在剥离常见前缀“[PATCH <anything>]”后用作提交标题。“Subject: ”行旨在用一行文字简洁地描述提交内容。

正文开头的“From: ”、“Date: ”和“Subject: ”行将覆盖从标头中获取的各自的提交作者姓名和标题值。

提交消息由取自“Subject: ”的标题、一个空行以及直到补丁开始前的消息正文组成。每行末尾的多余空白字符会自动剥离。

补丁应为内联，直接跟在消息后面。任何以下形式的行

  • 三个短横线和行尾，或者

  • 以 "diff -" 开头的行，或者

  • 以 "Index: " 开头的行

的行都被视为补丁的开始，并且提交日志信息会在第一次出现此类行之前终止。

这意味着提交消息的内容可能会无意中中断处理（请参阅下文的 注意事项 部分）。

最初调用 git-am[1] 时，您需要指定要处理的邮箱名称。在看到第一个无法应用的补丁时，它会中途中止。您可以通过以下两种方式之一进行恢复

  1. 通过使用 --skip 选项重新运行命令来跳过当前补丁。

  2. 在工作目录中手动解决冲突，并更新索引文件以使其达到补丁本应产生的状态。然后使用 --continue 选项运行命令。

在当前操作完成之前，该命令拒绝处理新的邮箱，因此如果您决定从头开始，请在运行带有邮箱名称的命令之前运行 git am --abort。

在应用任何补丁之前，ORIG_HEAD 会被设置为当前分支的末端。如果您在多个提交时遇到问题（例如在错误的分支上运行 git-am[1]，或者提交中的错误可以通过更改邮箱更容易地修复，如“From:”行中的错误），这非常有用。

注意事项

git-format-patch[1] 的输出在通过 git-am[1] 应用时可能会导致不同的提交消息。所应用的补丁也可能与生成的补丁不同，或者补丁应用可能会直接失败。有关语法规则，请参阅上面的 讨论 部分。

请注意，这对于提交信息中出现的未缩进 diff 尤其成问题；提交信息中的 diff 可能会与补丁部分一起被应用，或者补丁应用机制可能会因为补丁目标无法应用而绊倒。这例如可能是由 Markdown 代码块中的 diff 引起的。

解决此问题的办法是缩进 diff 或可能引起问题的其他文本。

如果您直接从邮箱应用补丁，这种保真度损失可能很容易察觉。然而，源自 Git 的更改可以批量应用，在这种情况下，这将很难察觉。这例如可以是一个使用补丁文件在来自上游仓库的提交之上应用更改的 Linux 发行版。这表明此行为不仅影响电子邮件工作流。

鉴于这些限制，人们可能会倾向于改用像 patch(1) 这样的通用实用程序。然而，patch(1) 不仅会查找未缩进的 diff（如 git-am[1]），还会尝试应用缩进的 diff。

钩子

此命令可以运行 applypatch-msg, pre-applypatch, 和 post-applypatch 钩子。有关更多信息，请参阅 githooks[5]。

请参阅 --verify/-n/--no-verify 选项。

配置

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

am.keepcr

如果为 true，git-am[1] 将为 mbox 格式的补丁调用带 --keep-cr 参数的 git-mailsplit[1]。在这种情况下，git-mailsplit[1] 不会从以 \r\n 结尾的行中删除 \r。可以通过在命令行上给出 --no-keep-cr 来覆盖。

am.threeWay

默认情况下，如果补丁不能干净地应用，git-am[1] 将失败。设置为 true 时，此设置告诉 git-am[1] 如果补丁记录了它应该应用的 blob 的标识，并且我们在本地拥有这些 blob，则回退到 3-way 合并（相当于从命令行给出 --3way 选项）。默认为 false。

am.messageId

在使用 git-am[1] 时，根据电子邮件头部添加一个 Message-ID 追踪信息到提交（参见 git-interpret-trailers[1]）。另请参阅 --message-id 和 --no-message-id 选项。

另请参阅

git-apply[1], git-format-patch[1]。

GIT

Git[1] 套件的一部分