英語 ▾ トピック ▾ 最新バージョン ▾ 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つの部分で構成されます。

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

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

  • 「パッチ」です。これはコミットとその親との間の「diff -p --stat」の出力です (git-diff[1]を参照)。

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

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

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

  2. 一般的な`<revision-range>`式 (gitrevisions[7]の「リビジョンの指定」セクションを参照) は、指定された範囲のコミットを意味します。

単一の`<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

可能な限り最小のdiffが生成されるように、追加の時間をかけます。

--patience

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

--histogram

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

--anchored=<text>

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

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

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

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

diffアルゴリズムを選択します。バリアントは次のとおりです。

default
myers

基本的なグリーディーdiffアルゴリズム。現在、これがデフォルトです。

minimal

可能な限り最小のdiffが生成されるように、追加の時間をかけます。

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

diffstatで、ファイルの作成または削除（「new」または「gone」、シンボリックリンクの場合はオプションで+l）、およびモード変更（実行可能ビットの追加または削除に対してそれぞれ+xまたは-x）などの拡張ヘッダー情報の簡潔な要約を出力します。この情報は、ファイル名部分とグラフ部分の間に配置されます。--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

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

--full-index

パッチ形式の出力を生成する際、「index」行に最初の数文字ではなく、pre-imageおよびpost-imageのblobオブジェクトのフルネームを表示します。

--binary

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

--abbrev[=<n>]

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

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

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

ファイルの完全な書き換えに相当する変更を、ごく少数のテキスト的に一致する行がコンテキストとして混ざった一連の削除と挿入としてではなく、古いものをすべて単一の削除とし、その後に新しいものをすべて単一の挿入として扱う方法に影響します。そして、数値<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の間の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

コミッターの身元を使用して、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通目以降のメールが1通目への返信として表示されるように、In-Reply-To および References ヘッダーの追加を制御します。また、参照用の Message-ID ヘッダーの生成も制御します。

オプションの <style> 引数は、shallow または deep のいずれかです。shallow スレッド化では、すべてのメールがシリーズの先頭への返信となります。先頭は、カバーレター、--in-reply-to、最初のパッチメールの順で選択されます。deep スレッド化では、すべてのメールが前のメールへの返信となります。

format.thread 設定がされていない限り、デフォルトは --no-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" も許可されます）が、そのようなリロールカウントを使用する欠点は、以前のバージョンとの 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:" が追加されます。これは、メーリングリストソフトウェアが送信者の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エンコーディング」（RFC 2047で記述）でエンコードし、ヘッダーをそのまま出力しないようにします。format.encodeEmailHeaders 設定変数の値がデフォルトです。

--interdiff=<previous>

レビューアの補助として、カバーレターに、または1パッチシリーズの単一パッチのコメントとして、以前のバージョンのパッチシリーズと現在フォーマットされているシリーズとの差を示す interdiff を挿入します。previous は、フォーマットされているシリーズと共通のベースを持つ以前のシリーズの先端を示す単一のリビジョンです（例: git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2）。

--range-diff=<previous>

レビューアの補助として、カバーレターに、または1パッチシリーズの単一パッチのコメントとして、以前のバージョンのパッチシリーズと現在フォーマットされているシリーズとの差を示す range-diff（git-range-diff[1] を参照）を挿入します。previous は、フォーマットされているシリーズと共通のベースを持つ以前のシリーズの先端を示す単一のリビジョンであるか（例: git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2）、またはシリーズの2つのバージョンが分離している場合はリビジョン範囲であることができます（例: 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

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

これの想定されるユースケースは、コミットログメッセージ自体に属さないコミットの補足説明を記述し、パッチ提出に含めることです。format-patch の実行後、送信前にこれらの説明を単純に記述することもできますが、Gitノートとして保持することで、パッチシリーズのバージョン間でそれらを維持することができます（ただし、このワークフローを使用するための git-notes[1] の notes.rewrite 設定オプションの議論を参照してください）。

format.notes 設定がされていない限り、デフォルトは --no-notes です。

--[no-]signature=<signature>

生成された各メッセージに署名を追加します。RFC 3676 に従って、署名は本文から '-- ' の行で区切られます。signature オプションが省略された場合、署名は 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

パッチの生成中に標準エラー出力に進行状況レポートを表示します。

設定

各メッセージに追加する追加のメールヘッダー行、件名接頭辞とファイル接尾辞のデフォルト、複数のパッチを出力する際のパッチ番号付け、「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が正しく設定されているかテストする一つの方法は、

  • リストおよびメンテナーアドレスを含まない 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サーバーに接続し、そこからメールを転送することができます。

GMail SMTPサーバー経由でパッチを送信するために git send-email を使用するヒントについては、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 アドオンをインストールします。これは、作成ウィンドウの「オプション」メニューに「Enable Word Wrap」というメニュー項目を追加し、チェックを外すことができます。これで、通常どおりメッセージを作成できます（切り取りと貼り付け、git format-patch | git imap-send など）が、入力するテキストには手動で改行を挿入する必要があります。

アプローチ #2 (設定)

3つのステップ

  1. メールサーバーの作成をプレーンテキストとして設定します：編集...アカウント設定...作成とアドレス指定、"Compose Messages in 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. 作成ウィンドウの「オプション」に進み、「Word wrap」が設定されていないことを確認します。

  4. メッセージ → ファイルを挿入…​ を使用して、パッチを挿入します。

  5. 作成ウィンドウに戻り、メッセージに任意のテキストを追加し、宛先と件名のフィールドを完成させ、「送信」を押します。

ベースツリー情報

ベースツリー情報ブロックは、メンテナやサードパーティのテスターがパッチシリーズが適用される正確な状態を知るために使用されます。これは、プロジェクト履歴の安定した部分であり、他の誰もが作業の出発点とする既知のコミットである ベースコミット と、まだ ベースコミット の一部ではないが、パッチを適用する前に ベースコミット の上にトポロジカルな順序で適用する必要がある既知の進行中のパッチであるゼロ以上の 前提パッチ で構成されます。

ベースコミット は "base-commit: " に続けてコミットオブジェクト名の40桁の16進数で表示されます。前提パッチ は "prerequisite-patch-id: " に続けて40桁の16進数 パッチID で表示されます。パッチIDは、git patch-id --stable コマンドを介してパッチを渡すことで取得できます。

公開コミット 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 を設定すると、リモートトラッキングブランチの先端コミットとコマンドラインで指定されたリビジョン範囲のmerge baseとしてベースコミットが自動的に計算されます。ローカルブランチの場合、このオプションを使用する前に 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