git-format-patch(1)

SYNOPSIS

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> ]

DESCRIPTION

UNIXメールボックスに似た形式で、コミットごとに1つの「メッセージ」に「パッチ」を含む各非マージコミットを準備します。このコマンドの出力は、電子メールの送信や「git am」での使用に便利です。

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

短いメタデータヘッダー。「file(1)」などのプログラムが、ファイルがこのコマンドからの出力であることを認識できるように「From <commit>」と、固定の日付スタンプ「Mon Sep 17 00:00:00 2001」で始まり、作者ID(author identity)や作者の日付(author date)や変更のタイトル(title of the change)(コミットログメッセージの最初の段落から取得)が記入されたフィールドがあります。
コミットログメッセージの2番目以降の段落。
コミットとその親の間の diff -p --stat 出力(git-diff(1) 参照)である「パッチ」。

ログメッセージとパッチは、3本のダッシュ(---)で区切られています。

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

単一のコミット<since>は、現在のブランチの先端につながるコミットで、<since>が出力される履歴にないことを指定します。
一般的な <revision-range> 評価式(gitrevisions(7) の「SPECIFYING REVISIONS」セクション参照)は、指定された範囲でのコミットを意味します。

単一の <commit> の場合、最初のルールが優先されます。2番目のルールを適用する、つまり、履歴の開始から <commit> までのすべてをフォーマットするには、 --root オプションを使用します: git format-patch --root <commit> とします。あなたが <commit> 自体のみをフォーマットしたい場合は、 git format-patch -1 <commit> を使用して行うことができます。

デフォルトでは、各出力ファイルには1から順番に番号が付けられ、ファイル名としてコミットメッセージの最初の行(パス名の安全のためにもみもみ(massage)れます)が使用されます。 --numbered-files オプションを使用すると、出力ファイル名は数字のみになり、コミットの最初の行は追加されません。 `--stdout`オプションが指定されていない限り、出力ファイル名が標準出力に出力されます。

-o を指定すると、出力ファイルは <dir> に作成されます。それ以外の場合は、現在の作業ディレクトリに作成されます。デフォルトのパスは、format.outputDirectory 構成オプションで設定できます。 -o オプションは format.outputDirectory よりも優先されます。 format.outputDirectory が他の場所を指している場合でも、パッチを現在の作業ディレクトリに保存したいときは、-o. を使用します。すべてのディレクトリコンポーネントが作成されます。

デフォルトでは、単一のパッチの件名は "[PATCH] " で、その後に、コミットメッセージから最初の空白行までの行が連結されます (git-commit(1)の DISCUSSION セクション参照)。

複数のパッチが出力される場合、件名のプレフィックスは "[PATCH n/m] " になります。 1つのパッチに 1/1 を強制的に追加するには -n を使用します。件名からパッチ番号を省略するには -N を使用します。

--thread を指定すると、 git-format-patch は In-Reply-To ヘッダーと References ヘッダーを生成し、2番目以降のパッチメールを最初のメールへの返信として表示します。これにより、参照する Message-ID ヘッダーも生成されます。

OPTIONS

-p

--no-stat

diffstatsなしでプレーン・パッチを生成します。

-U<n>

--unified=<n>

通常の3行ではなく、<n> 行の内容でdiffを生成します。

--output=<file>

stdout ではなく指定のファイルに出力します。

--output-indicator-new=<char>

--output-indicator-old=<char>

--output-indicator-context=<char>

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

--indent-heuristic

diffハンクの境界をずらす(shift)ヒューリスティックを有効にして、パッチを読みやすくします。これがデフォルトです。

--no-indent-heuristic

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

--minimal

より多くの時間を費やして、可能な限り最小のdiffが生成されるようにします。

--patience

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

--histogram

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

--anchored=<text>

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

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

行が比較元(source)と比較先(destination)の両方に存在し、かつ、1回だけ存在し、かつ、 <text> で始まる場合、このアルゴリズムは、その行が出力に削除または追加として表示されないようにします。内部で「patience diff」アルゴリズムを使用します。

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

diffアルゴリズムを選択します。そのバリエーションは以下のとおりです:

default
myers: 基本的な貪欲な差分アルゴリズム(greedy diff algorithm)。現在、これがデフォルトです。
minimal: より多くの時間を費やして、可能な限り最小のdiffが生成されるようにします。
patience: パッチを生成する時に "patience diff" アルゴリズムを使います。
histogram: このアルゴリズムは、忍耐アルゴリズム(patience algorithm)を拡張して、「発生率の低い共通要素をサポート」(support low-occurrence common elements)します。

たとえば、あなたが 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 の使用は統計グラフを生成するすべてのコマンドに影響しますが、 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 )、 diffstat のモード変更(実行可能ビットを追加または削除する場合は、それぞれ +x または -x )など、拡張ヘッダー情報の要約を出力します。情報はファイル名部分とグラフ部分の間に置かれます。本機能は --stat の機能を含んでいます。

--numstat

--stat に似ていますが、プログラムで処理しやすい(machine friendly)ように、追加および削除された行数を10進表記とパス名で省略形なしで表示します。バイナリファイルの場合、 0 0 の代わりに2つの - を出力します。

--shortstat

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

-X [<param>,...]

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

各サブディレクトリの相対的な変更量の分布を出力します。 --dirstat の動作は、パラメータのコンマ区切りリストを渡すことでカスタマイズできます。デフォルトは、 diff.dirstat 構成変数によって制御されます(git-config(1) 参照)。以下のパラメータを使用できます:

changes: 比較元(source)から削除された、または比較先(destination)に追加された行をカウントして、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

作成、名前変更、モード変更などの拡張ヘッダー情報の短い要約(condensed summary)を出力します。

--no-renames

構成ファイルにデフォルトで指定されている場合でも、名前変更の検出をオフにします。

--[no-]rename-empty

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

--full-index

パッチ形式の出力を生成するときは、最初の一握りの文字(first handful of characters)の代わりに、「インデックス」行にイメージ前およびイメージ後の完全ブロブオブジェクト名を表示します。

--binary

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

--abbrev[=<n>]

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

-B[<n>][/<m>]

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

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

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

-M と一緒に使用すると、完全に書き換えられたファイルも名前変更のソースと見なされ(通常、 -M は、消えたファイルのみを名前変更のソースと見なします)、数 n が -Bオプションのこの側面を制御します(デフォルトは50%)。 -B20% は、ファイルのサイズの20%以上と比較して、追加および削除を伴う変更が、別のファイルへの名前変更の可能なソースとして取得される資格があることを指定します。

-M[<n>]

--find-renames[=<n>]

名前の変更(renames)を検知する。 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 オプションは、コピーの元のファイルが同じ変更組(changeset)で変更された場合にのみコピーを検索します。このフラグにより、コマンドは変更されていないファイルをコピー元の候補として検査します。これは大規模なプロジェクトでは非常にコストのかかる操作であるため、注意して使用してください。複数の -C オプションを指定しても同じ効果があります。

-D

--irreversible-delete

削除するプレイメージ(preimage)を省略します。つまり、ヘッダーのみを出力し、プレイメージと /dev/null の差分は出力しません。結果のパッチは、 patch または git apply で適用されることを意図していません。これは、変更後にテキストを確認することに集中したい人のためだけのものです。さらに、出力には明らかに、そのようなパッチを手動でも逆に適用するのに十分な情報が不足しているため、このようなオプション名になっています。

-B と併用する場合は、削除/作成ペアの削除部分のプリイメージ(preimage)も省略します。

-l<num>

-M および -C オプションには、名前変更/コピーのサブセットを安価に検出できるいくつかの準備手順が含まれ、その後に、残りのすべてのペアになっていない比較先(destinations)をすべての関連ソースと比較する徹底的なフォールバック部分が続きます。(名前の変更の場合、残りのペアになっていないソースのみが関係します。コピーの場合、すべての元のソースが関係します)。N個の、ソースと比較先の場合、この徹底的なチェックのコストは O(N^2) です。このオプションは、関係するソース/比較先ファイルの数が指定された数を超えた場合に、名前変更/コピー検出の完全な部分が実行されないようにします。デフォルトは diff.renameLimit です。値0は無制限として扱われることに注意してください。

-O<orderfile>

ファイルが出力に表示される順序を制御します。これは diff.orderFile 構成変数をオーバーライドします(git-config(1) 参照)。 diff.orderFile をキャンセルするには、 -O/dev/null を使用します。

出力順序は、 <orderfile> 内のglobパターンの順序によって決定されます。最初のパターンに一致するパス名を持つすべてのファイルが最初に出力され、2番目のパターンに一致する(ただし最初のパターンには一致しない)パス名を持つすべてのファイルが次に出力されます。パス名がどのパターンとも一致しないすべてのファイルは、ファイルの最後に暗黙のすべて一致パターンがあるかのように、最後に出力されます。複数のパス名のランクが同じである場合(同じパターンに一致するが、以前のパターンには一致しない)、相互の出力順序は通常の順序です。

<orderfile> は以下のとおりパースされます:

空白行は無視されるため、読みやすくするための区切りとして使用できます。
ハッシュ ("#") で始まる行は無視されるため、コメントに使用できます。パターンがハッシュで始まる場合は、パターンの先頭にバックスラッシュ(訳注:日本では環境により円記号)("\") を追加します。
他の各行には、単一のパターンが含まれています。

パターンは、 FNM_PATHNAME フラグなしで fnmatch(3) に使用されるパターンと同じ構文とセマンティクスを持ちますが、最終的なパス名コンポーネントをいくつも削除するとパターンと一致する場合、パス名もパターンと一致する点が異なります。たとえば、パターン 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

比較を行うときは、行末のキャリッジリターン(carriage-return)を無視します。

--ignore-space-at-eol

行末(EOL)での空白(whitespace)の変更を無視します。

-b

--ignore-space-change

空白(whitespace)の数の変更は無視してください。これは、行末の空白(whitespace)を無視し、1つ以上の空白文字(whitespace characters)の他のすべてのシーケンスを同等と見なします。

-w

--ignore-all-space

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

--ignore-blank-lines

全て空白の行の変更は無視します。

-I<regex>

--ignore-matching-lines=<regex>

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

--inter-hunk-context=<number>

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

-W

--function-context

関数全体を各変更のコンテキスト行として表示します。関数名は、 git diff がパッチハンクヘッダーを処理するのと同じ方法で決定されます(gitattributes(5) の「Defining a custom hunk-header」参照)。

--ext-diff

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

--no-ext-diff

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

--textconv

--no-textconv

バイナリファイルを比較するときに、外部テキスト変換フィルターの実行を許可(または禁止)します。詳細については、 gitattributes(5) を参照してください。textconvフィルターは通常、一方向の変換であるため、結果のdiffは人間の消費に適していますが、適用(apply)することはできません。このため、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/" の代わりに、指定した比較元プレフィックス(source <prefix>)を表示します。

--dst-prefix=<prefix>

"b/" の代わりに、指定した比較先プレフィックス(destination <prefix>)を表示します。

--no-prefix

比較元(source)または比較先(destination)のプレフィックスを表示しません。

--default-prefix

デフォルトの比較元(source)および比較先(destination)のプレフィックスを使用します("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 attachment)を作成します。最初の部分はコミットメッセージで、2番目の部分はパッチ自体です。 Content-Disposition: attachment を使用します。
--no-attach: 添付ファイルの作成を無効にして、構成設定を上書きします。
--inline[=<boundary>]: マルチパート/混合の添付(multipart/mixed attachment)を作成します。最初の部分はコミットメッセージで、2番目の部分はパッチ自体です。 Content-Disposition: inline を使用します。
--thread[=<style>]
--no-thread: In-Reply-To ヘッダーと References ヘッダーの追加を制御して、 2番目以降のメールを最初のメールへの返信として表示します。また、参照する 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 とかでもOK)、このようなreroll-countを使用することの欠点は、以前のバージョンとの range-diff/interdiff で、新しい相互作用(new interation)がどのバージョンと比較されるかを正確に表示できなくなります。
--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: が追加されます。これは、メーリング・リスト・ソフトウェアが送信者の身元を解読する場合に役立ちます。デフォルトは 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: ヘッダーをそのまま(verbatim)出力する代わりに、非ASCII文字を含む電子メールヘッダーを Q-encoding (RFC 2047で説明)でエンコードします。デフォルトは、 format.encodeEmailHeaders 構成変数の値です。
--interdiff=<previous>: レビュアーの補助として、カバーレターに、あるいは1パッチシリーズの単独パッチの解説として、パッチシリーズの前のバージョンと現在フォーマットされているシリーズとの違いを示す interdiff を挿入してください。 previous は、フォーマット中のシリーズと共通のベースを持つ、前のシリーズの先端を示す単一のリビジョンです(例えば、 git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2 )。
--range-diff=<previous>: レビューの補助として、カバーレターに range-diff (git-range-diff(1) 参照) を挿入するか、1パッチシリーズの単独パッチの解説として、そのパッチシリーズの前のバージョンと現在フォーマットされているシリーズとの相違を示します。前バージョンは、フォーマットされるシリーズと共通のベースがある場合、前のシリーズの先端を示す単一のリビジョン(例えば 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 とともに使用すると、作成/削除のコストファッジ係数(cost fudge factor)を調整することにより、以前の一連のパッチと現在の一連のパッチの間でコミットを一致させるヒューリスティックを微調整します。詳細については、 git-range-diff(1) を参照してください。

デフォルトは 999 です(git-range-diff(1) では 60)。このユースケースは、同一トピックの以前の反復との比較を表示するためにあり、ツールは2つのパッチ・セット間でより多くの対応を見つけるべきです。
--notes[=<ref>]
--no-notes: 3つの破線(---)行の後に、コミットのnotes (git-notes(1) を参照)を追加します。

この場合、コミットログメッセージに属さないコミットの説明を書いて、パッチを送信する際に添付することが期待されます。これらの説明は、単に format-patch を実行した後で送信する前に書くこともできますが、Git notes として残しておくと、パッチシリーズのバージョン間でそれらを維持することができます(ただし、この作業フローを使用するには git-notes(1) の notes.rewrite 設定オプションに関するdiscussionを参照してください)。

format.notes 構成が設定されていない限り、デフォルトは --no-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へ進捗レポートを表示します。

CONFIGURATION

あなたは、各メッセージに追加するメールヘッダー行の指定、件名のプレフィックスとファイルのサフィックスのデフォルト、複数のパッチを出力する場合のパッチ番号の指定、 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

DISCUSSION

git format-patch によって生成されたパッチはUNIXメールボックス形式であり、ファイルが実際のメールボックスではなくformat-patchから出力されることを示す固定の「魔法の」タイムスタンプ(fixed "magic" time stamp)が付いています。

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 -- （訳注: >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: 行を保持する必要がある可能性があります。

パッチの破損のチェック

多くのメーラーは、適切に設定されていないと空白(whitespace)を破損します。破損の一般的な2つのタイプは以下のとおりです:

どの空白(whitespace)もない空のコンテキスト行。
先頭に1つの余分な空白(whitespace)がある空でないコンテキスト行。

あなたのMUAが正しく設定されているかどうかをテストする方法のひとつは以下のとおりです:

リストとメンテナのアドレスを含まない To: 行と Cc: 行を除き、全く同じ方法で、パッチを自分自身に送信します。
そのパッチをUNIXメールボックス形式のファイルに保存します。それを a.patch と呼ぶことにしましょう。

それをapplyします:

$ 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-SPECIFIC HINTS

さまざまなメーラーを使用してパッチをインラインで正常に送信する方法に関するヒントをいくつか。

GMail

Gmailには、Webインターフェイスでの行の折り返しをオフにする方法がないため、送信するすべての電子メールが破損します。ただし、 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はメールの行を折り返す(wrap)だけでなく、 format=flowed としてフラグを立てます。このため、結果のメールはGitで使用できなくなります。

3つの異なるアプローチがあります: アドオンを使用して行の折り返し(line wraps)をオフにする、またはパッチを切り刻まないようにThunderbirdを構成する、または外部エディターを使用してThunderbirdがパッチを切り刻まないようにします。

Approach #1 (add-on)

https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ から Toggle Word Wrap アドオンをインストールします。これは、コンポーザーの「オプション」メニューに「Enable Word Wrap」というメニュー項目を追加し、チェックを入れることができるようにします。これで、他の方法と同じようにメッセージを作成することができますが(カット＆ペースト、 git format-patch | git imap-send など)、入力したテキストには手動で改行を挿入する必要があります。

Approach #2 (configuration)

3ステップ:

メールサーバーの構成をプレーンテキストとして構成します。 [Edit…Account Settings…Composition & Addressing] で、 [Compose Messages in HTML] のチェックを外します(訳注:手元のThunderBird 91.7.0(64ビット)では、メールごとの[アカウント設定…編集とアドレス入力…編集][HTML形式でメッセージを編集する©])
行の折返しをしないように、あなたの一般作文ウィンドウ(general composition window)を設定します。

Thunderbird 2: [Edit..Preferences..Composition] で、 [wrap plain text messages] を 0 にセットする。

Thunderbird 3 : [Edit..Preferences..Advanced..ConfigEditor] で "mail.wrap_long_lines" を検索します。それをトグルして false に設定されていることを確認します。また、 mailnews.wraplength を検索し、値を0に設定します(訳注: ThunderBird 91.7.0(64ビット) 全体の設定…一般…の一番下にある[設定エディター…©]ボタン押下して「高度な設定」タブを開く。後は上記と一緒です)
format=flowed の使用を無効にします: [Edit..Preferences..Advanced..Config Editor](訳注:上記[設定エディター…©]参照) "mailnews.send_plaintext_flowed" を検索します。トグルして false に設定されていることを確認します。

これで今後は、あなたは他の方法(カット＆ペーストや git format-patch | git imap-send など)で電子メールを作成できるようになり、パッチが破損することはありません。

Approach #3 (external editor)

Thunderbird拡張機能が必要です: AboutConfig( https://mjg.github.io/AboutConfig/ ) と External Editor( https://globs.org/articles.php?lng=en&pg=8 )です。

あなたが選択した方法を使用して、パッチをテキストファイルとして準備します。
作文ウィンドウ(compose window)を開く前に、 [Edit…Account] を使用して、パッチの送信に使用するアカウントの[Composition & Addressing]パネルの[Compose messages in HTML format]設定のチェックを外します(訳注:手元のThunderBird 91.7.0(64ビット)では、メールごとの[アカウント設定…編集とアドレス入力…編集][HTML形式でメッセージを編集する©])。
Thunderbirdのメインウィンドウで、パッチの作成ウィンドウを開く前に、 [Tools]→ [about:config] を使用して、以下を指定された値に設定します(訳注: ThunderBird 91.7.0(64ビット) 設定…一般…の一番下にある[設定エディター…©]ボタン押下して「高度な設定」タブを開く):
```
        mailnews.send_plaintext_flowed  => false
        mailnews.wraplength             => 0
```
作文ウィンドウを開き、外部エディターアイコンをクリックします。
外部エディタウィンドウで、パッチファイルを読み込み、通常どおりエディタを終了します。

補足: aboutconfig と以下の設定を使用して手順2 を実行できる場合がありますが、まだ誰も試していません。

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

contrib/thunderbird-patch-inline には、あなたがThunderbirdにパッチを簡単にインクルードするのに役立つスクリプトがあります。これを使用するには、上記の手順を実行してから、スクリプトを外部エディターとして使用します。

KMail

これは、KMailを使用してパッチをインラインで送信するのに役立ちます。

パッチをテキストファイルとして準備します。
「New Mail」をクリックします。
Composer ウィンドウの [Options] の下に移動し、[Word wrap] が設定されていないことを確認します。
Use Message → Insert file して、パッチを挿入します。
作文ウィンドウに戻ります。メッセージに他のテキストを追加し、アドレス指定フィールドと件名フィールドに入力して、送信を押します。

BASE TREE INFORMATION

ベースツリー情報ブロックは、メンテナやサードパーティテスタが、パッチシリーズが適用される正確な状態を知るために使用されます。ベースツリー情報ブロックは、「ベースコミット」（プロジェクトの安定した歴史の一部であり、他のすべての人がそれを元に作業する）と、ゼロ個以上の「前提条件パッチ」(ベースコミットにまだ含まれない、よく知られたパッチで、パッチを適用する前にベースコミットにトポロジカルに追加する必要があります)で構成されています。

「ベースコミット」は、 base-commit: ` の後にコミットオブジェクト名の40進数が続くものとして表示されます。 `prerequisite patch は prerequisite-patch-id: ` の後に40-hexの `patch 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 または -3C の代わりに 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 の識別子が最初のメッセージの最後に追加されます。

cmdline で --base=auto を設定すると、cmdline で指定されたリモート追跡ブランチとリビジョン範囲の先端コミットのマージ・ベースとしてベース・コミットが自動的に計算されます。ローカルブランチの場合、このオプションを使用する前に、 gitbranch --set-upstream-to でリモートブランチを追跡する必要があります。

EXAMPLES

リビジョンR1とR2の間のコミットを抽出します。そして、それらをチェリーピックするために git am を使用して現在のブランチの先頭にそれらを適用します:
```
$ git format-patch -k --stdout R1..R2 | git am -3 -k
```
現在のブランチにはあるが、元のブランチにはないすべてのコミットを抽出します:
```
$ git format-patch origin
```
コミットごとに、現在のディレクトリに個別のファイルが作成されます。
プロジェクトの開始以降で origin につながるすべてのコミットを抽出します。
```
$ git format-patch --root origin
```
以下は上記と同一です:
```
$ git format-patch -M -B origin
```
さらに、名前変更を検出して処理し、名前変更パッチを生成するためにインテリジェントに書き換えを完了します。名前の変更パッチは、テキスト出力の量を減らし、一般的にレビューを容易にします。 Git以外の「パッチ」プログラムはパッチの名前変更を理解しないため、受信者がGitを使用してパッチを適用していることがわかっている場合にのみ使用してください。
現在のブランチの先頭から3つのコミットを抽出し、それらを電子メールで送信可能なパッチとしてフォーマットします:
```
$ git format-patch -3
```

CAVEATS

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

GIT

Part of the git(1) suite

git-format-patch(1) Manual Page

NAME