簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-format-patch 最後更新於 2.48.0

名稱

git-format-patch - 準備用於電子郵件提交的補丁

概要

git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
		   [--no-thread | --thread[=<style>]]
		   [(--attach|--inline)[=<boundary>] | --no-attach]
		   [-s | --signoff]
		   [--signature=<signature> | --no-signature]
		   [--signature-file=<file>]
		   [-n | --numbered | -N | --no-numbered]
		   [--start-number <n>] [--numbered-files]
		   [--in-reply-to=<message-id>] [--suffix=.<sfx>]
		   [--ignore-if-in-upstream] [--always]
		   [--cover-from-description=<mode>]
		   [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
		   [(--reroll-count|-v) <n>]
		   [--to=<email>] [--cc=<email>]
		   [--[no-]cover-letter] [--quiet]
		   [--[no-]encode-email-headers]
		   [--no-notes | --notes[=<ref>]]
		   [--interdiff=<previous>]
		   [--range-diff=<previous> [--creation-factor=<percent>]]
		   [--filename-max-length=<n>]
		   [--progress]
		   [<common-diff-options>]
		   [ <since> | <revision-range> ]

描述

將每個非合併提交及其“補丁”準備成每個提交一份“訊息”，格式化為類似於 UNIX 郵箱。此命令的輸出方便用於電子郵件提交或與 git am 一起使用。

命令生成的訊息由三部分組成

  • 一個簡短的元資料頭，以 From <commit> 開頭，帶有固定的 Mon Sep 17 00:00:00 2001 日期戳，以幫助“file(1)”等程式識別該檔案是此命令的輸出，以及記錄作者身份、作者日期和更改標題（取自提交日誌訊息的第一段）的欄位。

  • 提交日誌訊息的第二段和後續段落。

  • “補丁”，即提交與其父級之間的“diff -p --stat”輸出（參見 git-diff[1]）。

日誌訊息和補丁由一條三劃線分隔。

有兩種方法可以指定要操作的提交。

  1. 單個提交 指定要輸出當前分支尖端上不在 歷史中的提交。

  2. 通用 表示式（參見 gitrevisions[7] 中的“SPECIFYING REVISIONS”部分）表示指定範圍內的提交。

在單個 的情況下，第一條規則優先。要應用第二條規則，即格式化從歷史開始到 的所有內容，請使用 --root 選項：git format-patch --root <commit>。如果您只想格式化 本身，可以使用 git format-patch -1 <commit>。

預設情況下，每個輸出檔案從 1 開始按順序編號，並使用提交訊息的第一行（為檔名安全而處理）作為檔名。使用 --numbered-files 選項，輸出檔名將僅是數字，不附加提交的第一行。輸出檔案的名稱會列印到標準輸出，除非指定了 --stdout 選項。

如果指定了 -o，輸出檔案將在 <dir> 中建立。否則，它們將在當前工作目錄中建立。預設路徑可以使用 format.outputDirectory 配置選項設定。-o 選項優先於 format.outputDirectory。即使 format.outputDirectory 指向其他位置，也要將補丁儲存在當前工作目錄中，請使用 -o .。所有目錄元件都將被建立。

預設情況下，單個補丁的主題是 "[PATCH] "，後跟提交訊息中直到第一個空行（參見 git-commit[1] 的 DISCUSSION 部分）的行內容。

當輸出多個補丁時，主題字首將變為 "[PATCH n/m] "。要強制為單個補丁新增 1/1，請使用 -n。要從主題中省略補丁號，請使用 -N。

如果給定 --thread，git-format-patch 將生成 In-Reply-To 和 References 標頭，使第二封及後續補丁郵件顯示為對第一封郵件的回覆；這也會生成一個 Message-ID 標頭供引用。

選項

-p
--no-stat

生成純補丁，不包含任何差異統計。

-U<n>
--unified=<n>

生成帶有 <n> 行上下文的差異，而不是通常的三行。

--output=<file>

輸出到特定檔案而不是標準輸出。

--output-indicator-new=<char>
--output-indicator-old=<char>
--output-indicator-context=<char>

指定用於指示生成補丁中新行、舊行或上下文行的字元。通常它們分別是 +、- 和 ' '。

--indent-heuristic

啟用啟發式演算法，該演算法會移動差異塊邊界，使補丁更易於閱讀。這是預設設定。

--no-indent-heuristic

停用縮排啟發式演算法。

--minimal

花費額外時間以確保生成最小的差異。

--patience

使用“patience diff”演算法生成差異。

--histogram

使用“histogram diff”演算法生成差異。

--anchored=<text>

使用“anchored diff”演算法生成差異。

此選項可以多次指定。

如果一行在源和目標中都存在，只存在一次，並且以 <text> 開頭，則此演算法會嘗試阻止其在輸出中顯示為刪除或新增。它內部使用“patience diff”演算法。

--diff-algorithm=(patience|minimal|histogram|myers)

選擇一種差異演算法。變體如下：

default
myers

基本的貪婪差異演算法。目前，這是預設值。

minimal

花費額外時間以確保生成最小的差異。

patience

生成補丁時使用“patience diff”演算法。

histogram

此演算法擴充套件了 patience 演算法以“支援低出現率的常見元素”。

例如，如果您將 diff.algorithm 變數配置為非預設值，但希望使用預設值，則必須使用 --diff-algorithm=default 選項。

--stat[=<width>[,<name-width>[,<count>]]]

生成差異統計。預設情況下，檔名部分將使用盡可能多的空間，其餘部分用於圖形部分。最大寬度預設為終端寬度，如果未連線到終端則為 80 列，並且可以透過 <width> 覆蓋。檔名部分的寬度可以透過在逗號後給出另一個寬度 <name-width> 或設定 diff.statNameWidth=<name-width> 來限制。圖形部分的寬度可以透過使用 --stat-graph-width=<graph-width> 或設定 diff.statGraphWidth=<graph-width> 來限制。使用 --stat 或 --stat-graph-width 會影響所有生成統計圖的命令，而設定 diff.statNameWidth 或 diff.statGraphWidth 不會影響 git format-patch。透過給出第三個引數 <count>，可以將輸出限制為前 <count> 行，如果還有更多行，則後面是 ...。

這些引數也可以透過 --stat-width=<width>、--stat-name-width=<name-width> 和 --stat-count=<count> 單獨設定。

--compact-summary

輸出擴充套件頭資訊的精簡摘要，例如檔案建立或刪除（“new”或“gone”，可選 +l 表示符號連結）和模式更改（+x 或 -x 分別用於新增或刪除可執行位）在 diffstat 中。資訊放置在檔名部分和圖形部分之間。隱含 --stat。

--numstat

與 --stat 類似，但以十進位制表示法顯示新增和刪除的行數以及未縮寫的路徑名，使其更便於機器處理。對於二進位制檔案，輸出兩個 - 而不是顯示 0 0。

--shortstat

僅輸出 --stat 格式的最後一行，其中包含修改檔案的總數，以及新增和刪除的行數。

-X [<param>,...]
--dirstat[=<param>,...]

輸出每個子目錄的相對更改量分佈。--dirstat 的行為可以透過傳遞一個逗號分隔的引數列表來自定義。預設值由 diff.dirstat 配置變數控制（參見 git-config[1]）。以下引數可用：

changes

透過計算從源中刪除或新增到目標中的行數來計算 dirstat 數字。這忽略了檔案中純程式碼移動的數量。換句話說，重新排列檔案中的行不像其他更改那樣被計算。當未給出引數時，這是預設行為。

lines

透過執行常規的基於行的差異分析，並彙總已刪除/新增的行數來計算 dirstat 數字。（對於二進位制檔案，計算 64 位元組塊，因為二進位制檔案沒有自然的行概念）。這是一種比 changes 行為更昂貴的 --dirstat 行為，但它確實會將檔案中重新排列的行計算為與其他更改一樣多。結果輸出與您從其他 --*stat 選項獲得的輸出一致。

files

透過計算更改的檔案數量來計算 dirstat 數字。在 dirstat 分析中，每個更改的檔案都同等重要。這是計算成本最低的 --dirstat 行為，因為它根本不需要檢視檔案內容。

cumulative

子目錄中的更改也計入父目錄。請注意，使用 cumulative 時，報告的百分比總和可能超過 100%。預設（非累積）行為可以透過 noncumulative 引數指定。

<limit>

一個整數引數，指定一個截止百分比（預設為 3%）。對更改貢獻低於此百分比的目錄不會顯示在輸出中。

示例：以下將計算更改的檔案，同時忽略更改總量低於 10% 的目錄，並在父目錄中累積子目錄計數：--dirstat=files,10,cumulative。

--cumulative

--dirstat=cumulative 的同義詞。

--dirstat-by-file[=<param>,...]

--dirstat=files,<param>,... 的同義詞。

--summary

輸出擴充套件頭資訊的精簡摘要，例如建立、重新命名和模式更改。

--no-renames

關閉重新命名檢測，即使配置檔案預設開啟。

--[no-]rename-empty

是否使用空 blob 作為重新命名源。

--full-index

在生成補丁格式輸出時，不在“index”行上顯示前幾個字元，而是顯示完整的原影像和後圖像 blob 物件名稱。

--binary

除了 --full-index，還輸出一個二進位制差異，可以使用 git-apply 應用。

--abbrev[=<n>]

在 diff-raw 格式輸出和 diff-tree 標題行中，不顯示完整的 40 位元組十六進位制物件名稱，而是顯示最短的字首，該字首至少有 <n> 個十六進位制數字長，並且唯一引用該物件。在 diff-patch 輸出格式中，--full-index 具有更高的優先順序，即如果指定了 --full-index，無論 --abbrev 如何，都將顯示完整的 blob 名稱。非預設數字位數可以透過 --abbrev=<n> 指定。

-B[<n>][/<m>]
--break-rewrites[=[<n>][/<m>]]

將完整的重寫更改分解為刪除和建立對。這有兩個目的：

它影響了檔案完全重寫的更改方式，不是一系列刪除和插入與極少量的文字匹配行混合在一起作為上下文，而是先刪除所有舊內容，然後插入所有新內容，並且數字 <m> 控制 -B 選項的這一方面（預設為 60%）。-B/70% 指定原始檔案少於 30% 的內容應保留在結果中，Git 才將其視為完全重寫（即，否則生成的補丁將是刪除和插入與上下文行混合在一起的序列）。

與 -M 一起使用時，完全重寫的檔案也被視為重新命名源（通常 -M 只將消失的檔案視為重新命名源），數字 <n> 控制 -B 選項的這一方面（預設為 50%）。-B20% 指定與檔案大小的 20% 或更多相比有新增和刪除的更改，才有資格被視為重新命名到另一個檔案的可能源。

-M[<n>]
--find-renames[=<n>]

檢測重新命名。如果指定了 <n>，它是一個相似性指數的閾值（即與檔案大小相比的新增/刪除量）。例如，-M90% 意味著如果檔案超過 90% 未更改，Git 應該將刪除/新增對視為重新命名。如果沒有 % 符號，該數字應理解為小數，小數點位於其前。即，-M5 變為 0.5，因此與 -M50% 相同。類似地，-M05 與 -M5% 相同。要將檢測限制為精確重新命名，請使用 -M100%。預設相似性指數為 50%。

-C[<n>]
--find-copies[=<n>]

檢測複製和重新命名。另請參見 --find-copies-harder。如果指定了 <n>，其含義與 -M<n> 相同。

--find-copies-harder

出於效能原因，預設情況下，-C 選項僅當複製的原始檔案在同一變更集中被修改時才查詢複製。此標誌使命令檢查未修改的檔案作為複製源的候選。對於大型專案，這是一項非常昂貴的操作，因此請謹慎使用。給定多個 -C 選項具有相同的效果。

-D
--irreversible-delete

省略刪除的原始影像，即只打印標題，而不列印原始影像和 /dev/null 之間的差異。生成的補丁不適用於 patch 或 git apply；這僅適用於那些只想專注於審查更改後文本的人。此外，輸出顯然缺乏足夠的資訊來反向應用此類補丁，即使是手動，因此得名此選項。

與 -B 一起使用時，也會省略刪除/建立對的刪除部分中的原始影像。

-l<num>

-M 和 -C 選項涉及一些初步步驟，可以廉價地檢測重新命名/複製的子集，然後是一個詳盡的後備部分，將所有剩餘的未配對目標與所有相關源進行比較。（對於重新命名，只有剩餘的未配對源是相關的；對於複製，所有原始源都是相關的。）對於 N 個源和目標，這種詳盡的檢查是 O(N^2)。如果涉及的源/目標檔案數量超過指定數量，此選項會阻止重新命名/複製檢測的詳盡部分執行。預設為 diff.renameLimit。請注意，值 0 被視為無限制。

-O<orderfile>

控制檔案在輸出中出現的順序。這會覆蓋 diff.orderFile 配置變數（參見 git-config[1]）。要取消 diff.orderFile，請使用 -O/dev/null。

輸出順序由 <orderfile> 中 glob 模式的順序決定。所有路徑名與第一個模式匹配的檔案首先輸出，所有路徑名與第二個模式匹配（但不與第一個模式匹配）的檔案其次輸出，依此類推。所有路徑名不與任何模式匹配的檔案最後輸出，就像檔案末尾有一個隱式匹配所有模式一樣。如果多個路徑名具有相同的排名（它們匹配相同的模式但沒有更早的模式），則它們相對於彼此的輸出順序是正常順序。

<orderfile> 解析如下：

  • 空行被忽略，因此它們可以用作分隔符以提高可讀性。

  • 以井號（"#"）開頭的行被忽略，因此它們可以用作註釋。如果模式以井號開頭，請在模式開頭新增反斜槓（"\"）。

  • 其他每行包含一個模式。

模式的語法和語義與用於 fnmatch(3) 且不帶 FNM_PATHNAME 標誌的模式相同，除了如果刪除任意數量的最終路徑名元件與模式匹配，路徑名也匹配模式。例如，模式 "foo*bar" 匹配 "fooasdfbar" 和 "foo/bar/baz/asdf" 但不匹配 "foobarx"。

--skip-to=<file>
--rotate-to=<file>

從輸出中丟棄命名檔案 <file> 之前的檔案（即 跳過到），或將其移動到輸出的末尾（即 旋轉到）。這些選項主要用於 git difftool 命令，否則可能不太有用。

--relative[=<path>]
--no-relative

當從專案子目錄執行時，可以使用此選項排除目錄外的更改並顯示相對於該目錄的路徑名。當您不在子目錄中（例如，在裸倉庫中）時，可以透過提供 <path> 作為引數來命名輸出相對於哪個子目錄。--no-relative 可用於抵消 diff.relative 配置選項和之前的 --relative。

-a
--text

將所有檔案視為文字。

--ignore-cr-at-eol

進行比較時忽略行尾的回車符。

--ignore-space-at-eol

忽略行尾空格的更改。

-b
--ignore-space-change

忽略空格數量的變化。這會忽略行尾的空格，並將所有其他一個或多個空格序列視為等效。

-w
--ignore-all-space

比較行時忽略空格。即使一行有空格而另一行沒有，這也忽略了差異。

--ignore-blank-lines

忽略所有空行的更改。

-I<regex>
--ignore-matching-lines=<regex>

忽略所有行都匹配 <regex> 的更改。此選項可以多次指定。

--inter-hunk-context=<number>

在差異塊之間顯示上下文，最多達指定行數 <number>，從而合併彼此接近的塊。預設為 diff.interHunkContext，如果未設定配置選項則為 0。

-W
--function-context

顯示整個函式作為每次更改的上下文行。函式名稱的確定方式與 git diff 生成補丁塊頭的方式相同（參見 gitattributes[5] 中“Defining a custom hunk-header”）。

--ext-diff

允許執行外部差異輔助程式。如果您使用 gitattributes[5] 設定了外部差異驅動程式，則需要與 git-log[1] 等命令一起使用此選項。

--no-ext-diff

禁止外部差異驅動程式。

--textconv
--no-textconv

允許（或禁止）在比較二進位制檔案時執行外部文字轉換過濾器。有關詳細資訊，請參見 gitattributes[5]。由於 textconv 過濾器通常是單向轉換，因此生成的差異適合人工閱讀，但無法應用。因此，textconv 過濾器預設僅為 git-diff[1] 和 git-log[1] 啟用，而不為 git-format-patch[1] 或差異底層命令啟用。

--ignore-submodules[=(none|untracked|dirty|all)]

在生成差異時忽略對子模組的更改。all 是預設值。使用 none 將在子模組包含未跟蹤或已修改檔案或其 HEAD 與超專案中記錄的提交不同時將其視為已修改，並且可以覆蓋 git-config[1] 或 gitmodules[5] 中 ignore 選項的任何設定。當使用 untracked 時，如果子模組只包含未跟蹤內容，則不將其視為髒（但仍會掃描其已修改內容）。使用 dirty 會忽略子模組工作樹的所有更改，只顯示超專案中儲存的提交的更改（這是 1.7.0 之前的行為）。使用 all 會隱藏對子模組的所有更改。

--src-prefix=<prefix>

顯示給定的源字首 <prefix> 而不是 "a/"。

--dst-prefix=<prefix>

顯示給定的目標字首 <prefix> 而不是 "b/"。

--no-prefix

不顯示任何源或目標字首。

--default-prefix

使用預設的源和目標字首（"a/" 和 "b/"）。這會覆蓋 diff.noprefix、diff.srcPrefix、diff.dstPrefix 和 diff.mnemonicPrefix 等配置變數（參見 git-config[1]）。

--line-prefix=<prefix>

在每行輸出前面新增一個額外的 <prefix>。

--ita-invisible-in-index

預設情況下，透過 git add -N 新增的條目在 git diff 中顯示為現有的空檔案，在 git diff --cached 中顯示為新檔案。此選項使條目在 git diff 中顯示為新檔案，在 git diff --cached 中顯示為不存在。這兩個選項都是實驗性的，將來可能會被刪除。

有關這些通用選項的更詳細說明，另請參見 gitdiffcore[7]。

-<n>

從最頂層的 <n> 個提交準備補丁。

-o <dir>
--output-directory <dir>

使用 <dir> 儲存結果檔案，而不是當前工作目錄。

-n
--numbered

以 [PATCH n/m] 格式命名輸出，即使是單個補丁。

-N
--no-numbered

以 [PATCH] 格式命名輸出。

--start-number <n>

補丁編號從 <n> 開始，而不是從 1 開始。

--numbered-files

輸出檔名將是簡單的數字序列，不附加預設的提交訊息第一行。

-k
--keep-subject

不從提交日誌訊息的第一行中剝離/新增 [PATCH]。

-s
--signoff

使用您的提交者身份向提交訊息新增 Signed-off-by 尾部。有關更多資訊，請參閱 git-commit[1] 中的簽收選項。

--stdout

將所有提交以 mbox 格式列印到標準輸出，而不是為每個提交建立一個檔案。

--attach[=<boundary>]

建立 multipart/mixed 附件，其中第一部分是提交訊息，第二部分是補丁本身，帶有 Content-Disposition: attachment。

--no-attach

停用附件的建立，覆蓋配置設定。

--inline[=<boundary>]

建立 multipart/mixed 附件，其中第一部分是提交訊息，第二部分是補丁本身，帶有 Content-Disposition: inline。

--thread[=<style>]
--no-thread

控制新增 In-Reply-To 和 References 標頭，使第二封及後續郵件顯示為對第一封郵件的回覆。還控制生成用於引用的 Message-ID 標頭。

可選的 <style> 引數可以是 shallow 或 deep。shallow 執行緒將每封郵件作為對系列頭部的回覆，頭部從封面信、--in-reply-to 和第一封補丁郵件中選擇，按此順序。deep 執行緒使每封郵件作為對前一封郵件的回覆。

預設是 --no-thread，除非設定了 format.thread 配置。--thread 不帶引數等同於 --thread=shallow。

請注意，git send-email 的預設行為是自行進行郵件執行緒化。如果您希望 git format-patch 處理執行緒化，則需要確保 git send-email 的執行緒化被停用。

--in-reply-to=<message-id>

使第一封郵件（或所有郵件，如果使用 --no-thread）顯示為對給定 <message-id> 的回覆，從而避免中斷執行緒以提供新的補丁系列。

--ignore-if-in-upstream

不包含與 <until>..<since> 中提交匹配的補丁。這將檢查所有可從 <since> 訪問但不可從 <until> 訪問的補丁，並將其與正在生成的補丁進行比較，任何匹配的補丁都將被忽略。

--always

包含不引入任何更改的提交的補丁，預設情況下會省略這些補丁。

--cover-from-description=<mode>

控制封面信的哪些部分將使用分支描述自動填充。

如果 <mode> 是 message 或 default，則封面信主題將填充佔位符文字。封面信正文將填充分支描述。這是在未指定配置或命令列選項時的預設模式。

如果 <mode> 是 subject，則分支描述的第一段將填充封面信主題。描述的其餘部分將填充封面信正文。

如果 <mode> 是 auto，如果分支描述的第一段大於 100 位元組，則模式將是 message，否則將使用 subject。

如果 <mode> 是 none，則封面信主題和正文都將填充佔位符文字。

--description-file=<file>

使用 <file> 的內容而不是分支的描述來生成封面信。

--subject-prefix=<subject-prefix>

在主題行中，不使用標準的 [PATCH] 字首，而是使用 [<subject-prefix>]。這可用於命名補丁系列，並可與 --numbered 選項結合使用。

配置變數 format.subjectPrefix 也可用於配置應用於給定倉庫所有補丁的主題字首。這在接收多個倉庫補丁的郵件列表中通常很有用，可用於區分補丁（例如，值為 "PATCH my-project"）。

--filename-max-length=<n>

不使用標準的 64 位元組，而是將生成的輸出檔名截斷為大約 <n> 位元組（過短的值將靜默提高到合理長度）。預設為 format.filenameMaxLength 配置變數的值，如果未配置則為 64。

--rfc[=<rfc>]

在主題字首前面加上字串 <rfc>（預設為 "RFC"）。由於主題字首預設為 "PATCH"，您將預設得到 "RFC PATCH"。

RFC 表示“Request For Comments”（徵求意見稿）；當傳送實驗性補丁以供討論而非應用時使用此項。“--rfc=WIP”也可以用於表示補丁尚未完成（“WIP”代表“Work In Progress”）。

如果接收社群對於特定額外字串的約定是將其放在主題字首*之後*，則字串 <rfc> 可以以破折號（"-"）作為字首，以表示 <rfc> 字串的其餘部分應附加到主題字首之後，例如，--rfc='-(WIP) 結果為 "PATCH (WIP)"。

-v <n>
--reroll-count=<n>

將系列標記為該主題的第 <n> 次迭代。輸出檔名會預置 v<n>，主題字首（預設為 "PATCH"，但可透過 --subject-prefix 選項配置）會追加 ` v<n>`。例如，--reroll-count=4 可能會生成 v4-0001-add-makefile.patch 檔案，其中包含 "Subject: [PATCH v4 1/20] Add makefile"。<n> 不必是整數（例如，允許 "--reroll-count=4.4" 或 "--reroll-count=4rev2"），但使用此類 reroll-count 的缺點是，與先前版本的 range-diff/interdiff 不會準確說明新迭代與哪個版本進行比較。

--to=<email>

向電子郵件頭新增一個 To: 頭。這會新增到任何已配置的頭之外，並且可以使用多次。否定形式 --no-to 會丟棄到目前為止新增的所有 To: 頭（來自配置或命令列）。

--cc=<email>

向電子郵件頭新增一個 Cc: 頭。這會新增到任何已配置的頭之外，並且可以使用多次。否定形式 --no-cc 會丟棄到目前為止新增的所有 Cc: 頭（來自配置或命令列）。

--from
--from=<ident>

在每封提交郵件的 From: 頭中使用 ident。如果提交的作者身份與提供的 ident 不完全相同，則在訊息正文中放置一個帶有原始作者資訊的 From: 頭。如果沒有給出 ident，則使用提交者身份。

請注意，此選項僅在您實際傳送電子郵件並希望將自己標識為發件人，但保留原始作者時才有用（git am 會正確識別正文中的頭）。另請注意，git send-email 已經為您處理了此轉換，如果您將結果饋送給 git send-email，則不應使用此選項。

--[no-]force-in-body-from

透過 --from 選項指定電子郵件發件人後，預設情況下，如果發件人與作者不同，則會在提交日誌訊息的頂部新增一個正文中的“From:”，以標識提交的真實作者。使用此選項，即使發件人和作者具有相同的名稱和地址，也會新增正文中的“From:”，這可能有助於郵件列表軟體在處理發件人身份時出現問題。預設為 format.forceInBodyFrom 配置變數的值。

--add-header=<header>

向電子郵件頭新增任意頭。這會新增到任何已配置的頭之外，並且可以使用多次。例如，--add-header="Organization: git-foo"。否定形式 --no-add-header 會丟棄所有（To:、Cc: 和自定義）從配置或命令列新增的頭。

--[no-]cover-letter

除了補丁，還生成一個包含分支描述、短日誌和總體差異統計的封面信檔案。您可以在傳送之前在檔案中填寫描述。

--encode-email-headers
--no-encode-email-headers

使用“Q-編碼”（RFC 2047 中描述）對包含非 ASCII 字元的電子郵件頭進行編碼，而不是原樣輸出頭。預設為 format.encodeEmailHeaders 配置變數的值。

--interdiff=<previous>

作為審閱者輔助，在封面信中插入一個 interdiff，或者作為 1 補丁系列中單個補丁的註釋，顯示補丁系列上一版本與當前正在格式化的系列之間的差異。previous 是一個單一修訂版本，命名上一系列的尖端，它與正在格式化的系列共享一個共同基礎（例如 git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2）。

--range-diff=<previous>

作為審閱者輔助，在封面信中插入一個範圍差異（參見 git-range-diff[1]），或者作為 1 補丁系列中單個補丁的註釋，顯示補丁系列上一版本與當前正在格式化的系列之間的差異。previous 可以是一個單一修訂版本，命名上一系列的尖端，如果它與正在格式化的系列共享一個共同基礎（例如 git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2），或者是一個修訂範圍，如果這兩個版本的系列是分離的（例如 git format-patch --cover-letter --range-diff=feature/v1~3..feature/v1 -3 feature/v2）。

請注意，傳遞給命令的差異選項會影響 format-patch 主要產品的生成方式，並且它們不會傳遞給用於生成封面信材料的底層 range-diff 機制（將來可能會改變）。

--creation-factor=<percent>

與 --range-diff 一起使用，透過調整建立/刪除成本模糊因子來調整匹配前一個和當前補丁系列之間提交的啟發式演算法。有關詳細資訊，請參見 git-range-diff[1]。

預設為 999（git-range-diff[1] 使用 60），因為用例是顯示與同一主題的舊迭代的比較，工具應該在兩組補丁之間找到更多對應關係。

--notes[=<ref>]
--no-notes

在三劃線之後附加提交的註釋（參見 git-notes[1]）。

預期用途是在提交日誌訊息正文之外編寫支援性解釋，並將其包含在補丁提交中。雖然可以在 format-patch 執行後但在傳送之前簡單地編寫這些解釋，但將其作為 Git 註釋可以使它們在補丁系列版本之間保持不變（但請參閱 git-notes[1] 中關於 notes.rewrite 配置選項的討論，以使用此工作流）。

預設是 --no-notes，除非設定了 format.notes 配置。

--[no-]signature=<signature>

為生成的每條訊息添加簽名。根據 RFC 3676，簽名與正文透過一條帶有“-- ”的行分隔。如果省略簽名選項，簽名預設為 Git 版本號。

--signature-file=<file>

功能與 --signature 類似，但簽名從檔案中讀取。

--suffix=.<sfx>

不使用 .patch 作為生成檔名的字尾，而是使用指定的字尾。一個常見的替代方案是 --suffix=.txt。將其留空將刪除 .patch 字尾。

請注意，開頭的字元不必是點；例如，您可以使用 --suffix=-patch 來獲得 0001-description-of-my-change-patch。

-q
--quiet

不將生成的檔名列印到標準輸出。

--no-binary

不輸出二進位制檔案中更改的內容，而是顯示檔案已更改的通知。使用此選項生成的補丁無法正確應用，但它們對於程式碼審查仍然有用。

--zero-commit

在每個補丁的 From 頭中輸出一個全零雜湊，而不是提交的雜湊。

--[no-]base[=<commit>]

記錄基礎樹資訊以識別補丁系列適用的狀態。有關詳細資訊，請參見下面的 BASE TREE INFORMATION 部分。如果 <commit> 是 "auto"，則自動選擇一個基礎提交。--no-base 選項會覆蓋 format.useAutoBase 配置。

--root

將修訂引數視為 <revision-range>，即使它只是一個單獨的提交（通常會被視為 <since>）。請注意，指定範圍中包含的根提交總是被格式化為建立補丁，與此標誌無關。

--progress

生成補丁時在 stderr 上顯示進度報告。

配置

您可以指定要新增到每條訊息的額外郵件頭行、主題字首和檔案字尾的預設值、在輸出多個補丁時對補丁進行編號、新增“To:”或“Cc:”頭、配置附件、更改補丁輸出目錄以及使用配置變數對補丁進行簽收。

[format]
	headers = "Organization: git-foo\n"
	subjectPrefix = CHANGE
	suffix = .txt
	numbered = auto
	to = <email>
	cc = <email>
	attach [ = mime-boundary-string ]
	signOff = true
	outputDirectory = <directory>
	coverLetter = auto
	coverFromDescription = auto

討論

由 git format-patch 生成的補丁採用 UNIX 郵箱格式，帶有一個固定的“魔術”時間戳，表示該檔案是 format-patch 的輸出，而不是真實的郵箱，如下所示：

From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
From: Tony Luck <tony.luck@intel.com>
Date: Tue, 13 Jul 2010 11:42:54 -0700
Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

arch/arm config files were slimmed down using a python script
(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)

Do the same for ia64 so we can have sleek & trim looking
...

通常它會放在 MUA 的草稿資料夾中，編輯以新增及時評論，這些評論不應在三劃線後的變更日誌中，然後作為訊息傳送，在我們的例子中，訊息正文以“arch/arm config files were…​”開頭。在接收端，讀者可以將感興趣的補丁儲存到 UNIX 郵箱中，並使用 git-am[1] 應用它們。

當補丁是正在進行的討論的一部分時，由 git format-patch 生成的補丁可以進行調整，以利用 git am --scissors 功能。在您的討論回覆之後，有一行僅包含 "-- >8 --"（剪刀和穿孔線），然後是已刪除不必要頭欄位的補丁：

...
> So we should do such-and-such.

Makes sense to me.  How about this patch?

-- >8 --
Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet

arch/arm config files were slimmed down using a python script
...

以這種方式傳送補丁時，通常您正在傳送自己的補丁，因此除了 "From $SHA1 $magic_timestamp" 標記外，您應該從補丁檔案中省略 From: 和 Date: 行。補丁標題可能與補丁所屬討論的主題不同，因此您可能希望保留 Subject: 行，如上例所示。

檢查補丁損壞

許多郵件程式如果設定不當，會破壞空白。以下是兩種常見的損壞型別：

  • 沒有任何空白的空上下文行。

  • 開頭多了一個空白字元的非空上下文行。

測試您的 MUA 是否設定正確的一種方法是：

  • 將補丁傳送給自己，完全按照您通常的方式傳送，只是 To: 和 Cc: 行不包含列表和維護者地址。

  • 將該補丁儲存為 UNIX 郵箱格式的檔案。例如，將其命名為 a.patch。

  • 應用它：

    $ git fetch <project> master:test-apply
$ git switch test-apply
$ git restore --source=HEAD --staged --worktree :/
$ git am a.patch

如果它無法正確應用，可能有多種原因。

  • 補丁本身不能幹淨地應用。這是不好的，但與您的 MUA 關係不大。在這種情況下，您可能希望在使用 git-rebase[1] 重新生成補丁之前對其進行 rebase。

  • MUA 損壞了您的補丁；"am" 會抱怨補丁無法應用。檢視 .git/rebase-apply/ 子目錄，看看 patch 檔案包含什麼，並檢查上面提到的常見損壞模式。

  • 同時，也檢查 info 和 final-commit 檔案。如果 final-commit 中的內容與您希望在提交日誌訊息中看到的內容不完全一致，則接收方在應用您的補丁時很可能會手動編輯日誌訊息。諸如補丁電子郵件中的“Hi, this is my first patch.\n”之類的文字應在表示提交訊息結束的三劃線之後出現。

MUA 特定提示

以下是一些關於如何使用各種郵件程式成功地內聯提交補丁的提示。

GMail

GMail 的網頁介面沒有任何關閉行包裝的方法，因此它會破壞您傳送的任何電子郵件。但是，您可以使用 "git send-email" 並透過 GMail SMTP 伺服器傳送補丁，或者使用任何 IMAP 電子郵件客戶端連線到 Google IMAP 伺服器並透過它轉發電子郵件。

有關使用 git send-email 透過 GMail SMTP 伺服器傳送補丁的提示，請參見 git-send-email[1] 的 EXAMPLE 部分。

有關使用 IMAP 介面提交的提示，請參見 git-imap-send[1] 的 EXAMPLE 部分。

Thunderbird

預設情況下，Thunderbird 會對電子郵件進行換行，並將其標記為 format=flowed，這兩者都會導致生成的電子郵件無法被 Git 使用。

有三種不同的方法：使用附加元件關閉行包裝，配置 Thunderbird 不破壞補丁，或者使用外部編輯器阻止 Thunderbird 破壞補丁。

方法 #1 (附加元件)

安裝可從 https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ 獲取的 Toggle Word Wrap 附加元件。它會在撰寫器的“選項”選單中新增一個“啟用自動換行”選單項，您可以將其取消勾選。現在您可以像平常一樣撰寫訊息（剪下+貼上、git format-patch | git imap-send 等），但您必須手動在您輸入的任何文字中插入換行符。

方法 #2 (配置)

分三步：

  1. 將郵件伺服器撰寫配置為純文字：編輯…賬戶設定…撰寫與地址，取消勾選“以 HTML 格式撰寫訊息”。

  2. 配置您的常規撰寫視窗不換行。

    在 Thunderbird 2 中：編輯..首選項..撰寫，將純文字訊息換行設定為 0。

    在 Thunderbird 3 中：編輯..首選項..高階..配置編輯器。搜尋“mail.wrap_long_lines”。切換它以確保其設定為 false。此外，搜尋“mailnews.wraplength”並將其值設定為 0。

  3. 停用 format=flowed 的使用：編輯..首選項..高階..配置編輯器。搜尋“mailnews.send_plaintext_flowed”。切換它以確保其設定為 false。

完成這些操作後，您應該能夠像平常一樣撰寫電子郵件（剪下+貼上、git format-patch | git imap-send 等），並且補丁不會被破壞。

方法 #3 (外部編輯器)

需要以下 Thunderbird 擴充套件：AboutConfig 來自 https://mjg.github.io/AboutConfig/ 和 External Editor 來自 https://globs.org/articles.php?lng=en&pg=8

  1. 使用您選擇的方法將補丁準備成文字檔案。

  2. 在開啟撰寫視窗之前，使用“編輯”→“賬戶設定”取消勾選要用於傳送補丁的賬戶的“撰寫與地址”面板中的“以 HTML 格式撰寫訊息”設定。

  3. 在 Thunderbird 主視窗中，在您開啟補丁的撰寫視窗之前，使用“工具”→“about:config”將以下設定更改為指定值：

    	mailnews.send_plaintext_flowed  => false
	mailnews.wraplength             => 0

  4. 開啟撰寫視窗並點選外部編輯器圖示。

  5. 在外部編輯器視窗中，讀入補丁檔案並正常退出編輯器。

旁註：可能可以透過 about:config 和以下設定來完成第 2 步，但還沒有人嘗試過。

	mail.html_compose                       => false
	mail.identity.default.compose_html      => false
	mail.identity.id?.compose_html          => false

contrib/thunderbird-patch-inline 中有一個指令碼可以幫助您輕鬆地在 Thunderbird 中包含補丁。要使用它，請執行上述步驟，然後將該指令碼用作外部編輯器。

KMail

這應該可以幫助您使用 KMail 內聯提交補丁。

  1. 將補丁準備成文字檔案。

  2. 點選“新郵件”。

  3. 在“撰寫器”視窗中的“選項”下，確保未設定“自動換行”。

  4. 使用“訊息”→“插入檔案…”並插入補丁。

  5. 回到撰寫視窗：新增您希望在郵件中包含的任何其他文字，填寫收件人地址和主題欄位，然後按下發送。

基礎樹資訊

基礎樹資訊塊用於讓維護者或第三方測試人員瞭解補丁系列應用的精確狀態。它包含一個基礎提交，這是一個眾所周知的提交，是專案歷史中穩定且其他人都在此基礎上進行工作的部分；以及零個或多個前置補丁，這些是正在進行中但尚未成為基礎提交一部分的眾所周知補丁，需要在補丁應用之前以拓撲順序在基礎提交之上應用。

基礎提交顯示為“base-commit: ”，後跟提交物件名稱的40位十六進位制值。前置補丁顯示為“prerequisite-patch-id: ”，後跟40位十六進位制的補丁ID，該ID可透過將補丁透過git patch-id --stable命令獲得。

想象一下，在公共提交P之上，您應用了其他人提供的眾所周知的補丁X、Y和Z，然後構建了您的三個補丁系列A、B、C，歷史將是這樣的

---P---X---Y---Z---A---B---C

使用git format-patch --base=P -3 C（或其變體，例如使用--cover-letter或使用Z..C代替-3 C來指定範圍），基礎樹資訊塊顯示在命令輸出的第一個訊息（無論是第一個補丁還是求職信）的末尾，如下所示：

base-commit: P
prerequisite-patch-id: X
prerequisite-patch-id: Y
prerequisite-patch-id: Z

對於非線性拓撲，例如：

---P---X---A---M---C
    \         /
     Y---Z---B

您也可以使用git format-patch --base=P -3 C為A、B和C生成補丁，並且P、X、Y、Z的識別符號會附加到第一個訊息的末尾。

如果在命令列中設定--base=auto，它將自動計算基礎提交，作為遠端跟蹤分支的尖端提交與命令列中指定的修訂範圍的合併基礎。對於本地分支，在使用此選項之前，您需要透過git branch --set-upstream-to使其跟蹤遠端分支。

示例

  • 提取修訂版本R1和R2之間的提交，並使用git am將其挑選（cherry-pick）應用到當前分支之上

    $ git format-patch -k --stdout R1..R2 | git am -3 -k

  • 提取當前分支中有但origin分支中沒有的所有提交

    $ git format-patch origin

    對於每個提交，都會在當前目錄中建立一個單獨的檔案。

  • 提取自專案啟動以來所有指向origin的提交

    $ git format-patch --root origin

  • 與前一個相同

    $ git format-patch -M -B origin

    此外，它能智慧地檢測並處理重新命名和完全重寫，以生成重新命名補丁。重新命名補丁減少了文字輸出量，通常使其更容易審查。請注意，非Git的“patch”程式無法理解重新命名補丁，因此，僅當您知道接收者使用Git應用您的補丁時才使用它。

  • 提取當前分支最上面的三個提交，並將其格式化為可傳送郵件的補丁

    $ git format-patch -3

注意事項

請注意，format-patch將從輸出中省略合併提交，即使它們是請求範圍的一部分。一個簡單的“補丁”不包含足夠的資訊，無法讓接收方重現相同的合併提交。

另請參閱

git-am[1], git-send-email[1]

GIT

Git[1] 套件的一部分

scroll-to-top