English ▾ トピック ▾ 最新バージョン ▾ 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メールボックスに似た形式で、コミットごとに1つの「メッセージ」に「パッチ」として準備します。このコマンドの出力は、メール送信やgit amでの使用に便利です。

コマンドによって生成される「メッセージ」は3つの部分で構成されます

  • 「file(1)」のようなプログラムがファイルがこのコマンドの出力であることを認識できるように、固定のMon Sep 17 00:00:00 2001の日付スタンプとともにFrom <commit>で始まる簡単なメタデータヘッダー、作成者ID、作成日、および変更のタイトル（コミットログメッセージの最初の段落から取得）を記録するフィールド。

  • コミットログメッセージの2番目以降の段落。

  • コミットとその親との間の「diff -p --stat」出力である「パッチ」（git-diff[1]を参照）。

ログメッセージとパッチは、3つのダッシュで区切られた行で区切られます。

操作するコミットを指定するには2つの方法があります。

  1. 単一のコミット<since>は、現在のブランチの先端までのコミットのうち、<since>までの履歴にないコミットが出力されることを指定します。

  2. 汎用的な<revision-range>式（gitrevisions[7]の「SPECIFYING REVISIONS」セクションを参照）は、指定された範囲のコミットを意味します。

単一の<commit>の場合、最初のルールが優先されます。2番目のルールを適用するには、つまり、履歴の最初から<commit>までのすべてをフォーマットするには、--rootオプションを使用します。git format-patch --root <commit>。<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は、2番目以降のパッチメールが最初のメールへの返信として表示されるようにIn-Reply-ToおよびReferencesヘッダーを生成します。これにより、参照するMessage-IDヘッダーも生成されます。

オプション

-p
--no-stat

diffstatを含まないプレーンなパッチを生成します。

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

通常の3行ではなく、<n>行のコンテキストを持つdiffを生成します。

--output=<file>

標準出力ではなく、指定されたファイルに出力します。

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

生成されるパッチで、新規行、古い行、コンテキスト行を示すために使用される文字を指定します。通常、それぞれ +、-、' ' です。

--indent-heuristic

パッチを読みやすくするために diff ハンク境界をシフトするヒューリスティックを有効にします。これがデフォルトです。

--no-indent-heuristic

インデントヒューリスティックを無効にします。

--minimal

可能な限り最小の差分が生成されるように、余分な時間を費やします。

--patience

「patience diff」アルゴリズムを使用して差分を生成します。

--histogram

「ヒストグラム diff」アルゴリズムを使用して差分を生成します。

--anchored=<text>

「アンカー付き diff」アルゴリズムを使用して差分を生成します。

このオプションは複数回指定できます。

行がソースとデスティネーションの両方に存在し、一度だけ存在し、<text> で始まる場合、このアルゴリズムは出力に削除または追加として表示されないようにします。内部的には「patience diff」アルゴリズムを使用します。

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

diff アルゴリズムを選択します。バリアントは以下の通りです

default
myers

基本的な貪欲な差分アルゴリズム。現在、これがデフォルトです。

minimal

可能な限り最小の差分が生成されるように、余分な時間を費やします。

patience

パッチを生成する際に「patience diff」アルゴリズムを使用します。

histogram

このアルゴリズムは、patience アルゴリズムを拡張して「出現頻度の低い共通要素をサポート」します。

たとえば、diff.algorithm 変数をデフォルト以外の値に設定している場合で、デフォルト値を使用したい場合は、--diff-algorithm=default オプションを使用する必要があります。

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

diffstatを生成します。デフォルトでは、ファイル名部分に必要に応じてスペースが使用され、残りはグラフ部分に充てられます。最大幅はデフォルトで端末の幅、または端末に接続されていない場合は80カラムとなり、<width>で上書きできます。ファイル名部分の幅は、カンマの後に別の幅<name-width>を指定するか、diff.statNameWidth=<name-width>を設定することで制限できます。グラフ部分の幅は、--stat-graph-width=<graph-width>を使用するか、diff.statGraphWidth=<graph-width>を設定することで制限できます。--statまたは--stat-graph-widthを使用すると、statグラフを生成するすべてのコマンドに影響しますが、diff.statNameWidthまたはdiff.statGraphWidthを設定してもgit format-patchには影響しません。3番目のパラメーター<count>を指定することで、出力を最初の<count>行に制限し、それ以上ある場合は...が続きます。

これらのパラメータは、--stat-width=<width>、--stat-name-width=<name-width>、--stat-count=<count>で個別に設定することもできます。

--compact-summary

ファイル作成または削除（「new」または「gone」、オプションでシンボリックリンクの場合は+l）やモード変更（実行可能ビットの追加または削除の場合はそれぞれ+xまたは-x）などの拡張ヘッダー情報の要約をdiffstatに出力します。情報はファイル名部分とグラフ部分の間に配置されます。--statを暗黙的に指定します。

--numstat

--statと同様ですが、追加および削除された行数を10進表記で表示し、パス名を省略せずに表示して、機械処理に適したものにします。バイナリファイルの場合、0 0と表示する代わりに2つの-を出力します。

--shortstat

変更されたファイルの総数、および追加および削除された行数を含む、--stat 形式の最後の行のみを出力します。

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

各サブディレクトリの変更の相対量の分布を出力します。--dirstatの動作は、カンマ区切りのパラメーターリストを渡すことでカスタマイズできます。デフォルトはdiff.dirstat設定変数によって制御されます（git-config[1]を参照）。以下のパラメーターが利用可能です。

changes

ソースから削除された行、または宛先に追加された行を数えることでdirstatの数を計算します。これは、ファイル内の純粋なコード移動の量を無視します。言い換えれば、ファイル内の行の並べ替えは他の変更と同じくらい数えられません。これは、パラメーターが指定されていない場合のデフォルトの動作です。

lines

通常の行ベースのdiff分析を行い、削除/追加された行数を合計することで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

空のブロブを名前変更元として使用するかどうか。

--full-index

パッチ形式出力を生成する際に、「index」行に最初の数文字ではなく、プレイメージとポストイメージの完全なブロブオブジェクト名を表示します。

--binary

--full-indexに加えて、git-applyで適用できるバイナリdiffを出力します。

--abbrev[=<n>]

diff-raw形式の出力やdiff-treeヘッダー行で完全な40バイトの16進オブジェクト名を表示する代わりに、オブジェクトを一意に参照する最短のプレフィックスを、少なくとも<n>桁の16進数で表示します。diff-patch出力形式では、--full-indexが優先されます。つまり、--full-indexが指定されている場合、--abbrevに関係なく完全なブロブ名が表示されます。デフォルト以外の桁数は--abbrev=<n>で指定できます。

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

完全な書き換え変更を削除と作成のペアに分割します。これには2つの目的があります。

これは、ファイルの完全な書き換えとなる変更を、テキスト的に一致する非常に少ない行がコンテキストとして混じった削除と挿入の連続としてではなく、古いものをすべて削除し、新しいものをすべて挿入するという単一の削除と挿入として扱う方法に影響します。そして、数値<m>は、-Bオプションのこの側面を制御します（デフォルトは60%）。-B/70%は、Gitがそれを完全な書き換えと見なすために、元の30%未満が結果に残っている必要があることを指定します（つまり、そうでなければ結果のパッチはコンテキスト行と混じり合った削除と挿入の連続になります）。

-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

削除のpreimageを省略します。つまり、ヘッダーのみを出力し、preimageと/dev/null間のdiffは出力しません。結果のパッチは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>のグロブパターンの順序によって決定されます。最初のパターンに一致するパス名を持つすべてのファイルが最初に出力され、2番目のパターンに一致するパス名を持つすべてのファイル（ただし、最初のパターンには一致しない）が次に出力され、以下同様です。どのパターンにも一致しないパス名を持つすべてのファイルは最後に出力されます。これは、ファイルの末尾に暗黙的なすべて一致パターンがある場合と同様です。複数のパス名が同じランクを持つ場合（同じパターンに一致するが、それより前のパターンには一致しない場合）、それら相互の出力順序は通常の順序です。

<orderfile> は次のように解析されます。

  • 空白行は無視されるため、可読性のための区切り文字として使用できます。

  • シャープ記号（「#」）で始まる行は無視されるため、コメントに使用できます。パターンがシャープ記号で始まる場合は、パターンの先頭にバックスラッシュ（「\」）を追加してください。

  • その他の各行には、単一のパターンが含まれます。

パターンは、FNM_PATHNAMEフラグなしでfnmatch(3)で使用されるパターンと同じ構文とセマンティクスを持ちます。ただし、パス名が最終パス名コンポーネントの任意の数を削除してもパターンに一致する場合も、そのパス名はパターンに一致します。たとえば、パターン「foo*bar」は「fooasdfbar」および「foo/bar/baz/asdf」に一致しますが、「foobarx」には一致しません。

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

名前付きの<file>より前のファイルをから出力から破棄する（つまり、skip to）、または出力の最後に移動する（つまり、rotate to）。これらのオプションは主に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

空白の量の変更を無視します。これは行末の空白を無視し、1 つ以上の空白文字の他のすべてのシーケンスを同等と見なします。

-w
--ignore-all-space

行を比較する際に空白を無視します。これにより、一方の行に空白があり、もう一方の行に空白がない場合でも、違いを無視します。

--ignore-blank-lines

すべての行が空白である変更を無視します。

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

すべての行が<regex>に一致する変更を無視します。このオプションは複数回指定できます。

--inter-hunk-context=<number>

diff のハンク間のコンテキストを指定された<number>行まで表示し、互いに近いハンクを結合します。設定オプションが設定されていない場合、デフォルトはdiff.interHunkContextまたは0です。

-W
--function-context

各変更のコンテキスト行として関数全体を表示します。関数名は、git diffがパッチハンクヘッダーを決定する方法と同じ方法で決定されます（gitattributes[5]の「カスタムハンクヘッダーの定義」を参照）。

--ext-diff

外部のdiffヘルパーの実行を許可します。gitattributes[5]で外部diffドライバーを設定した場合、git-log[1]とその仲間と一緒にこのオプションを使用する必要があります。

--no-ext-diff

外部diffドライバーの使用を禁止します。

--textconv
--no-textconv

バイナリファイルの比較時に外部テキスト変換フィルターの実行を許可（または禁止）します。詳細についてはgitattributes[5]を参照してください。textconvフィルターは通常一方向の変換であるため、生成されるdiffは人間が読むのに適していますが、適用することはできません。このため、textconvフィルターはデフォルトではgit-diff[1]およびgit-log[1]でのみ有効になっており、git-format-patch[1]やdiff配管コマンドでは有効になっていません。

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

diff生成時にサブモジュールの変更を無視します。allがデフォルトです。noneを使用すると、サブモジュールに追跡されていないファイルまたは変更されたファイルが含まれている場合、またはそのHEADがスーパープロジェクトに記録されているコミットと異なる場合に、サブモジュールが変更されたと見なされます。これは、git-config[1]またはgitmodules[5]のignoreオプションの設定をオーバーライドするために使用できます。untrackedを使用すると、サブモジュールが追跡されていないコンテンツのみを含む場合でも汚れているとは見なされません（ただし、変更されたコンテンツは引き続きスキャンされます）。dirtyを使用すると、サブモジュールのワークツリーへのすべての変更が無視され、スーパープロジェクトに保存されているコミットへの変更のみが表示されます（これは1.7.0までの動作でした）。allを使用すると、サブモジュールへのすべての変更が非表示になります。

--src-prefix=<prefix>

"a/" の代わりに指定されたソース <prefix> を表示します。

--dst-prefix=<prefix>

"b/" の代わりに指定された宛先 <prefix> を表示します。

--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では存在しないものとして表示されます。このオプションは--ita-visible-in-indexで元に戻すことができます。どちらのオプションも実験的なものであり、将来削除される可能性があります。

これらの共通オプションの詳細については、gitdiffcore[7]も参照してください。

-<n>

最も上位の<n>コミットからパッチを準備します。

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

結果のファイルを現在の作業ディレクトリではなく、<dir>に保存します。

-n
--numbered

単一のパッチでも、[PATCH n/m]形式で出力に名前を付けます。

-N
--no-numbered

出力に[PATCH]形式で名前を付けます。

--start-number <n>

パッチの番号付けを1ではなく<n>から開始します。

--numbered-files

出力ファイル名は、デフォルトのコミットの最初の行が付加されず、単純な番号シーケンスになります。

-k
--keep-subject

コミットログメッセージの最初の行から[PATCH]を削除/追加しないでください。

-s
--signoff

コミッターIDを使用して、コミットメッセージにSigned-off-byトレーラーを追加します。詳細についてはgit-commit[1]のsignoffオプションを参照してください。

--stdout

各コミットごとにファイルを作成する代わりに、すべてのコミットをmbox形式で標準出力に出力します。

--attach[=<boundary>]

multipart/mixed添付ファイルを作成します。最初の部分はコミットメッセージ、2番目の部分はパッチ自体で、Content-Disposition: attachmentとなります。

--no-attach

添付ファイルの作成を無効にし、設定を上書きします。

--inline[=<boundary>]

multipart/mixed添付ファイルを作成します。最初の部分はコミットメッセージ、2番目の部分はパッチ自体で、Content-Disposition: inlineとなります。

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

2番目以降のメールが最初のメールへの返信として表示されるように、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は、「Subject: [PATCH v4 1/20] Add makefile」を含むv4-0001-add-makefile.patchファイルを生成する場合があります。<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を使用します。コミットの作者IDが指定されたidentとテキスト的に同一でない場合、メッセージの本文に元の作者を持つFrom:ヘッダーを配置します。<ident>が指定されていない場合、コミッターIDを使用します。

このオプションは、実際にメールを送信していて、自分自身を送信者として識別したいが、元の作者を保持したい場合にのみ有用であることに注意してください（そしてgit amは本文のヘッダーを正しく取得します）。また、git send-emailは既にこの変換を処理しているため、結果をgit send-emailに渡す場合はこのオプションを使用しないでください。

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

--fromオプションで電子メール送信者が指定されている場合、デフォルトでは、送信者が作者と異なる場合、コミットの実際の作者を識別するために、コミットログメッセージの先頭に本文中の「From:」が追加されます。このオプションを使用すると、送信者と作者が同じ名前とアドレスを持っている場合でも、本文中の「From:」が追加されます。これは、メーリングリストソフトウェアが送信者のIDを誤って処理する場合に役立つ可能性があります。デフォルトはformat.forceInBodyFrom設定変数の値です。

--add-header=<header>

メールヘッダーに任意のヘッダーを追加します。これは設定済みのヘッダーに加えてのもので、複数回使用できます。たとえば、--add-header="Organization: git-foo"です。否定形--no-add-headerは、これまでに追加されたすべての（To:、Cc:、およびカスタム）ヘッダーを設定またはコマンドラインから破棄します。

--[no-]cover-letter

パッチに加えて、ブランチの説明、ショートログ、および全体的なdiffstatを含むカバーレターファイルも生成します。送信前にファイルに説明を記入できます。

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

非ASCII文字を含むメールヘッダーを、そのまま出力する代わりに、「Q-encoding」（RFC 2047で記述）でエンコードします。デフォルトはformat.encodeEmailHeaders設定変数の値です。

--interdiff=<previous>

レビュー担当者の助けとして、カバーレター、または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）です。

コマンドに渡されるdiffオプションは、format-patchの主要な生成物にどのように影響するかを決定し、カバーレターマテリアルを生成するために使用される基盤となるrange-diffメカニズムには渡されないことに注意してください（これは将来変更される可能性があります）。

--creation-factor=<percent>

--range-diffと共に使用され、作成/削除コストの調整係数を調整することで、以前のパッチシリーズと現在のパッチシリーズ間でコミットを照合するヒューリスティックを微調整します。詳細についてはgit-range-diff[1]を参照してください。

デフォルトは999（git-range-diff[1]は60を使用）です。これは、同じトピックの古いイテレーションとの比較を示すユースケースであり、ツールは2つのパッチセット間により多くの対応を見つけるべきであるためです。

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

コミットのメモ（git-notes[1]を参照）を3つのダッシュの行の後に追記します。

この機能の想定されるユースケースは、コミットログメッセージ自体には属さないが、パッチ提出時に含める必要がある、コミットに関する補足説明を記述することです。`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

リビジョン引数を、それが単一のコミットである場合でも（通常は<since>として扱われる）<revision-range>として扱います。指定された範囲に含まれるルートコミットは、このフラグとは関係なく常に作成パッチとしてフォーマットされることに注意してください。

--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のドラフトフォルダに配置され、3つのダッシュの後に変更ログに含めるべきではないタイムリーなコメントを追加するために編集され、その後、本文が「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:行を保持したいと思うでしょう。

パッチの破損チェック

多くのメーラーは適切に設定されていないと空白を破損させます。ここに一般的な2つの破損タイプを示します。

  • 空白が一切ない空のコンテキスト行。

  • 先頭に1つ余分な空白がある非空のコンテキスト行。

MUAが正しく設定されているかテストする1つの方法は以下の通りです。

  • 通常どおり、ただし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]でパッチをリベースしてから再生成することをお勧めします。

  • MUAがパッチを破損した。「am」がパッチが適用されないと文句を言うだろう。.git/rebase-apply/サブディレクトリを見て、patchファイルに何が含まれているかを確認し、上記で述べた一般的な破損パターンをチェックします。

  • ついでに、infoとfinal-commitファイルも確認してください。final-commitの内容がコミットログメッセージに表示したいものとまったく同じでない場合、受信者がパッチを適用するときにログメッセージを手動で編集することになる可能性が非常に高いです。パッチメールの「Hi, this is my first patch.\n」のようなものは、コミットメッセージの終わりを示す3つのダッシュの行の後に来るべきです。

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で使用できなくなります。

3つの異なるアプローチがあります。行の折り返しをオフにするアドオンを使用する、パッチを破損しないようにThunderbirdを設定する、または外部エディターを使用してThunderbirdがパッチを破損するのを防ぐ。

アプローチ1（アドオン）

https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/から入手できるToggle Word Wrapアドオンをインストールします。これにより、作成ウィンドウの「オプション」メニューに「単語の折り返しを有効にする」というメニューエントリが追加され、チェックを外すことができます。これで、通常どおりメッセージを作成できます（カット＆ペースト、git format-patch | git imap-sendなど）。ただし、入力するテキストには手動で改行を挿入する必要があります。

アプローチ2（設定）

3つのステップ

  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拡張機能が必要です。https://mjg.github.io/AboutConfig/からAboutConfig、https://globs.org/articles.php?lng=en&pg=8からExternal Editor。

  1. 選択した方法でパッチをテキストファイルとして準備します。

  2. 作成ウィンドウを開く前に、編集→アカウント設定を使用して、パッチの送信に使用するアカウントの「作成とアドレス指定」パネルで「HTML形式でメッセージを作成する」設定のチェックを外します。

  3. パッチの作成ウィンドウを開く前に、メインのThunderbirdウィンドウで、ツール→about:configを使用して、以下を指示された値に設定します。

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

  4. 作成ウィンドウを開き、外部エディターアイコンをクリックします。

  5. 外部エディターウィンドウで、パッチファイルを読み込み、通常どおりエディターを終了します。

補足: ステップ2はabout:configと以下の設定で可能かもしれませんが、まだ誰も試していません。

	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. 作成ウィンドウに戻り、メッセージに任意の追加テキストを追加し、宛先と件名フィールドを完了し、送信ボタンを押します。

ベースツリー情報

ベースツリー情報ブロックは、メンテナーまたはサードパーティのテスターがパッチシリーズが適用される正確な状態を知るために使用されます。これは、プロジェクト履歴の安定した部分であり、他のすべての人が作業する基盤となる既知のコミットであるベースコミットと、パッチが適用される前にベースコミットの上にトポロジカル順に適用する必要がある、ベースコミットの一部ではない既知のインフライトパッチである0個以上の前提条件パッチで構成されます。

ベースコミットは「base-commit: 」に続き、コミットオブジェクト名の40桁の16進数で表示されます。前提条件パッチは「prerequisite-patch-id: 」に続き、git patch-id --stableコマンドでパッチを通過させることで取得できる40桁の16進数パッチIDで表示されます。

公開されたコミットPの上に、他の誰かの既知のパッチX、Y、Zを適用し、その後3つのパッチシリーズA、B、Cを構築したとします。履歴は次のようになります。

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

git format-patch --base=P -3 C (または --cover-letter を使用したり、範囲を指定するために -3 C の代わりに Z..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 を使用して現在のブランチに適用してチェリーピックします。

    $ 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 を使用していることがわかっている場合にのみ使用してください。

  • 現在のブランチから最新の3つのコミットを抽出し、電子メールで送信可能なパッチとしてフォーマットします。

    $ git format-patch -3

注意点

format-patch は、要求された範囲の一部であっても、マージコミットを出力から省略することに注意してください。単純な「パッチ」には、受信側が同じマージコミットを再現するのに十分な情報が含まれていません。

関連項目

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

GIT

git[1]スイートの一部

scroll-to-top