English ▾ 主題 ▾ 最新版本 ▾ git-am 最後更新於 2.55.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[<key-id>]] [--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 merge）。--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[<key-id>]
--gpg-sign[=<key-id>]
--no-gpg-sign

對提交進行 GPG 簽署。<key-id> 是選用的，預設為提交者身分；如果指定，它必須緊接在選項後，中間不得有空格。--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]，或是提交中的錯誤透過修改信箱會更容易修正，例如 From: 行中的錯誤），這會很有用。

注意事項

git-format-patch[1] 的輸出在使用 git-am[1] 套用時可能會導致不同的提交訊息。所套用的修補檔也可能與產生的修補檔不同，或者修補檔套用可能會直接失敗。請參閱上述的 討論 區段以了解語法規則。

請注意，對於提交訊息中出現的未縮排 diff，這尤其成問題；提交訊息中的 diff 可能會連同補丁部分一起被套用，或者補丁套用機制可能會因為補丁目標不適用而絆倒。例如，這可能是由 Markdown 程式碼區塊中的 diff 引起的。

解決此問題的方法是縮排 diff 或其他可能導致問題的文字。

如果您直接從郵箱套用補丁，這種保真度的缺失可能很容易被注意到。然而，源自 Git 的變更可能會被大量套用，在這種情況下，這將很難被注意到。例如，一個 Linux 發行版可能會使用補丁檔案在上游儲存庫的提交之上套用變更。這說明了這種行為不僅影響電子郵件工作流程。

鑑於這些限制，人們可能會傾向於使用像 patch(1) 這樣的通用工具。然而，patch(1) 不僅會尋找未縮排的 diff（如同 git-am[1]），還會嘗試套用縮排的 diff。

HOOKS (鉤子)

此指令可以執行 applypatch-msg、pre-applypatch 和 post-applypatch 鉤子。更多資訊請參閱 githooks[5]。

請參閱 --verify / -n / --no-verify 選項。

組態設定 (CONFIGURATION)

本節中此行以下的內容是從 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，則退而求其次使用三路合併（等同於在指令列給予 --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] 套件的一部分