Pro Git 中文版

Appearance

git-am ​

从邮箱应用一系列补丁

概要 ​

bash
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 可用，则回退到三方合并。--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，则仅显示差异部分。默认为 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) 或通过更改邮箱更容易修复的提交中的错误），这很有用。

注意事项 ​

git-format-patch(1) 的输出在使用 git-am(1) 应用时可能导致不同的提交消息。应用的补丁也可能与生成的补丁不同，或者补丁应用可能完全失败。

任何具有以下形式的行：

  • 三个破折号和行尾，或
  • 以 "diff -" 开头的行，或
  • 以 "Index: " 开头的行

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

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

解决方案是缩进差异或其他可能导致问题的文本。

如果你直接从邮箱应用补丁，这种保真度的丧失可能很容易注意到。然而，源自 Git 的更改可能会被批量应用，在这种情况下这将更难注意到。例如，这可能是一个使用补丁文件在上游存储库的提交之上应用更改的 Linux 发行版。这表明这种行为不仅影响电子邮件工作流程。

鉴于这些限制，人们可能会倾向于使用像 patch(1) 这样的通用工具。然而，patch(1) 不仅会查找未缩进的差异（像 git-am(1) 一样），还会尝试应用缩进的差异。

钩子 ​

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

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

配置 ​

本节中此行以下的内容是从 git-config(1) 文档中选择性包含的。内容与其中的内容相同：

am.keepcr ​

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

am.threeWay ​

默认情况下，如果补丁无法干净地应用，git-am(1) 将失败。当设置为 true 时，此设置告诉 git-am(1) 如果补丁记录了它应该应用的 blob 的身份并且我们在本地有这些 blob 可用，则回退到三方合并（等同于从命令行给出 --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) 套件的一部分

基于 CC BY-NC-SA 3.0 许可发布

Pro Git 中文版