SYNOPSIS

git interpret-trailers [--in-place] [--trim-empty]
                        [(--trailer <token>[(=|:)<value>])…]
                        [--parse] [<file>…]

DESCRIPTION

コミット メッセージの自由形式部分の最後の、 RFC 822 電子メール・ヘッダーに似た「トレーラー」(trailer)行の追加またはパースを行います。 たとえば、 以下コミットメッセージ:

subject

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

ここで、「Signed-off-by」で始まる最後の 2 行はトレーラーです。

このコマンドは、 <file> 引数、 または <file> が指定されていない場合は標準入力からコミット・メッセージを読み取ります。 --parse が指定されている場合、 出力はパースされたトレーラーで構成されます。 それ以外の場合、 このコマンドは、 --trailer オプションを使用して渡された引数(存在する場合)を各入力ファイルに適用します。 結果は標準出力に出力されます。

このコマンドでは git-format-patch(1) の出力を操作することもできます。 これは、 素のコミット・メッセージよりも複雑です。 つまり、 このような出力には、 (上記のとおりの)コミット・メッセージと --- 区切り線とパッチ部分が含まれます。 これらの入力の場合 --no-divider が指定されない限り、 区切り線以下とパッチ部分はこのコマンドによって変更されず、 そのまま出力されます。

いくつかの設定変数は --trailer 引数が各入力に適用される方法と、 入力内の既存のトレーラーが変更される方法を制御します。 また、 いくつかのトレーラを自動的に追加することもできます。

デフォルトでは、 --trailer で指定された <token>=<value> または <token>:<value> 引数は、既存の最後のトレーラーのペア(<token>, <value>)が指定のペア異なる場合(または、既存のに無い場合)にのみ、指定したモノが既存のトレーラーの後に追加されます。 <token>と<value>の部分は、先頭と末尾の空白がトリミングされ、以下のように出力に表示されます:

token: value

これは、 トリミングされた <token> と <value> が ": " (1つのコロンと1つのスペース)で区切られることを意味します。 簡便にするために <token> は出力の区切り文字の前に表示されべきである完全な文字列(例: Signed-off-by) の代わりに、 短縮された文字列キー(例: sign)にすることができます。 これは、 trailer.<token>.key 構成変数を使用して構成できます。

デフォルトでは、 すべての既存のトレーラーの末尾の後ろに新しいトレーラーが出力されます。 既存のトレーラーがない場合は、 新しいトレーラーが入力の末尾の後ろに出力表示されます。 その新しいトレーラーの前にまだ空行がない場合は、 空行が追加されます。

入力から、 (i) すべてのトレーラーを含むか、 または (ii) 1つ以上の Git 生成またはユーザー構成のトレーラーを含む25％以上のトレーラーで構成される、 1行以上のグループから、 既存のトレーラーを探し出して抽出します。 そのグループの前には、 1行以上の空行(または空白のみの行)が必要です。 そのグループは、 入力の末尾にあるか、 あるいは --- で始まる行より前の最後の非空白行達である必要があります(その後にスペースまたは行の終わりが続きます)。

トレーラーを読み取る場合、 <token> の前または内部に空白(whitespace)を含めることはできませんが、 <token> とセパレーターの間には、 任意の数の通常の空白(space)文字達とタブ文字達を使用できます。 <value> の前または内部または後ろに空白達(whitespaces)を入れることができます。 RFC 822 の「folding」(折り畳み)のように、 <value> は複数の行に分割され、 後続の各行の先頭は1つ以上の空白(whitespace)で始まります。

token: これは非常に長い値であり、
空白や改行が含まれます。

注意: トレーラーはRFC822ヘッダー規則の多くに従うことを意図してませんし、 従わないことに注意してください。 たとえば、 それらはエンコーディング規則に従いません。

OPTIONS

--in-place

その場でファイルを編集します。

--trim-empty

トレーラーの <value> 部分に空白(whitespace)のみが含まれている場合、 出力からトレーラー全体が削除されます。 これは、 新しいトレーラーだけでなく、 既存のトレーラーにも適用されます。

--trailer <token>[(=|:)<value>]

入力のトレーラーとして適用する必要があるペア(<token>、<value>)を指定します。 詳しくはこのコマンドの説明を参照してください。

--where <placement>
--no-where

すべての新しいトレーラーが追加される場所を指定します。 --where で指定する設定は、すべての構成変数をオーバーライドし、 --where または --no-where が次に出現するまですべての --trailer オプションに適用されます。 <placement> として可能な値は、 after または before または end または start です。

--if-exists <action>
--no-if-exists

入力に同一の <token> を持つトレーラーがすでに少なくとも1つある場合に実行される操作を指定します。 --if-exists で指定する設定は、 すべての構成変数をオーバーライドし、 --if-exists または --no-if-exists が次に出現するまですべての --trailer オプションに適用されます。 可能な操作は addIfDifferent, addIfDifferentNeighbor, add, replace, doNothing です。

--if-missing <action>
--no-if-missing

入力に同一の <token> を持つ他のトレーラーが無い場合に実行される操作を指定します。 --if-missing で指定する設定は、 すべての構成変数をオーバーライドし、 --if-missing または --no-if-missing が次に出現するまですべての --trailer オプションに適用されます。 可能な操作は doNothing, add です。

--only-trailers

トレーラーのみを出力し、入力の他の部分は出力しません。

--only-input

入力に存在するトレーラーのみを出力します。コマンドラインや、構成された trailer.* ルールに従って追加することはありません。

--unfold

トレーラーの複数行に渡る先頭空白による継続を解除して、各トレーラーが1行で完結するよう出力します。

--parse

--only-trailers --only-input --unfold の便利なエイリアス。

--no-divider

--- をコミットメッセージの終わりとして扱わないでください。(電子メールや `git format-patch`の出力が含まれておらず、)入力にコミットメッセージ自体だけが含まれていることがわかっている場合にこれを使用します。

CONFIGURATION VARIABLES

trailer.separators

このオプションは、どの文字がトレーラー区切り文字として認識されるかを示します。 デフォルトでは、 : のみがトレーラー区切り文字として認識されます。ただし、他のgitコマンドとの互換性のために、コマンドラインでは = が常に受け入れられます。

このオプションで指定された最初の1文字は、このトレーラーの構成で別の区切り文字が指定されていない場合に使用されるデフォルトの文字になります。

たとえば、このオプションの値が "%=$" の場合、 <token><sep><value> の形式を使用し、<sep> に % または = または $ と、空白達を含む行のみトレーラーと見なされます。 また、 % がデフォルトの区切り文字として使用されるため、デフォルトでは、トレーラーは <token>% <value> と出力されます(デフォルトの場合はこのようにトークンと値の間に1つの区切り文字列の最初の文字(パーセント記号)と「1つのスペース」が出力されます)。

trailer.where

このオプションは、新しいトレーラーが追加される場所を示します。

これは、デフォルトの end の他に start または after または before にすることができます。

end の場合、新しいトレーラーはそれぞれ、既存のトレーラーの最後に出力されます。

start の場合、新しい各トレーラーは、既存のトレーラーの最後ではなく、最初に出力されます。

after の場合、新しいトレーラーはそれぞれ、同じ <token> を持つ最後のトレーラーの直後に出力されます。

before の場合、新しい各トレーラーは、同じ <token> を持つ最初のトレーラーの直前に出力されます。

trailer.ifexists

このオプションを使用すると、 入力に同一の <token> を持つトレーラーがすでに少なくとも1つある場合に実行する操作を選択できます。

このオプションの有効な値は、 addIfDifferentNeighbor (デフォルト)、 または addIfDifferent または add または replace または doNothing です。

addIfDifferentNeighbor を使用すると、同一のペア(<token>、<value>)のトレーラーが、新しいトレーラーが追加される行の上または下にない場合にのみ、新しいトレーラーが追加されます。

addIfDifferent を使用すると、 同一のペア(<token>、<value>)のトレーラーが入力に含まれてい無い場合にのみ、 新しいトレーラーが追加されます。

add を使用すると、 同一のペア(<token>, <value>)のトレーラーがすでにメッセージに含まれている場合でも、 新しいトレーラーが追加されます。

replace を使用すると、同じ <token> を持つ既存のトレーラーが削除され、新しいトレーラーが追加されます。削除されるトレーラーは、新しいトレーラーが追加される場所に最も近い(同じ <token> を持つ)トレーラーになります。

doNothing を使用すると、 何も実行されません。 つまり、 メッセージに同一の <token> を持つトレーラーがすでに存在する場合、 新しいトレーラーは追加されません。

trailer.ifmissing

このオプションを使用すると、 入力に同一の <token> を持つトレーラーがまだ無い場合に実行する操作を選択できます。

このオプションの有効な値は、 add (デフォルト)と doNothing です。

`add`を使用すると、新しいトレーラーが追加されます。

doNothing を使用すると、何も実行されません。

trailer.<token>.key

この キー(key) は、トレーラーで <token> の代わりに使用されます。このキーの後ろに、区切り文字を出力してから、いくつかのスペース文字を出力できます。デフォルトでは、有効な区切り文字は : のみですが、これは trailer.separators 構成変数を使用して変更できます。

トレーラーを追加するときに、この構成値内に区切り文字がある場合、 <token> とデフォルトの区切り文字の両方(つまり、<token><区切り文字><空白1つ>)がキーで置き換えられます。

trailer.<token>.where

このオプションは、「trailer.where」構成変数と同じ値を取り、指定された <token> を持つトレーラーに対してそのオプションで指定されたものをオーバーライドします。

trailer.<token>.ifexists

このオプションは、「trailer.ifexists」構成変数と同じ値を取り、指定された <token> を持つトレーラーに対してそのオプションで指定されたものをオーバーライドします。

trailer.<token>.ifmissing

このオプションは、「trailer.ifmissing」構成変数と同じ値を取り、指定された <token> を持つトレーラーに対してそのオプションで指定されたものをオーバーライドします。

trailer.<token>.command

非推奨: trailer.<token>.cmd に取って代わられ、 非推奨となりました。 このオプションは、 指定のコマンドに引数として何も渡さないことを除いて、 trailer.<token>.cmd と同じように動作します。 その代わりに、 文字列に最初に現れる置換文字列 $ARG のみ、 引数として渡される値に置き換えられます。

注意: ユーザーのコマンド内の $ARG は一度しか置き換えられず、 $ARG を置き換えるこのオリジナルの方法は安全ではないことに注意してください。

trailer.<token>.cmd と trailer.<token>.command の両方が同じ<token>で指定されている場合、 trailer.<token>.cmd が使用され、 trailer.<token>.command は無視されます。

trailer.<token>.cmd

このオプションは、 指定された <token> のトレーラを自動的に追加するために一度だけ呼び出され、 かつ、 追加後は、 このオプションが生成するトレーラの <value> を変更するために --trailer <token>=<value> 引数が指定されるたびに呼び出されるシェルコマンド、 を指定するために使うことができる。

指定のコマンドを最初に呼び出して、指定の <token> のトレーラーを追加すると、動作は、「git interpret-trailers」コマンドの先頭に特別な --trailer <token>=<value> 引数が追加されたかのように振る舞います。ここで、 <value> は、先頭と末尾の空白が削除された、コマンドからの標準出力と見なされます。

いくつかの --trailer <token>=<value> 引数がコマンドラインで渡された場合、同じ <token> を持つこれらの引数ごとにコマンドが1回呼び出されます。そして、これらの引数の <value> 部分は、もしあれば、最初の引数としてコマンドに渡されます。このようにして、コマンドは --trailer <token>=<value> 引数で渡された <value> から計算された <value> を生成できます。

EXAMPLES

  • 「Signed-off-by」キーを使用して「sign」トレーラーを構成してから、 これら2つのトレーラーをコミット・メッセージ・ファイルへ追加します: 

    $ git config trailer.sign.key "Signed-off-by"
$ cat msg.txt
subject

body text
$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject

body text

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

  • --in-place オプションを使用して、 コミット・メッセージ・ファイルをその場で編集します: 

    $ cat msg.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
$ cat msg.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>

  • 最後のコミットをパッチとして抽出し、それに「Cc」トレーラーと「Reviewed-by」トレーラーを追加します: 

    $ git format-patch -1
0001-foo.patch
$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch

  • 「Signed-off-by: 」がまだない場合にのみ、作者情報を含む「Signed-off-by: 」を自動的に追加するコマンドを伴って「sign」トレーラーを構成し、それがどのように機能するかを示します: 

    $ cat msg1.txt
subject

body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers --trailer sign <msg1.txt
subject

body text

Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject

body text

Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject

body text

Signed-off-by: Alice <alice@example.com>

  • trailer.fix.key に 区切り文字 # を含み、その後ろにスペースを含まないキーを使用して「fix」トレーラーを構成し、それがどのように機能するかを示します: 

    $ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject

Fix #42

  • cmdを使用して「ヘルプ」トレーラーを構成します。スクリプト glog-find-author を使用して、gitリポジトリのgitログから指定された作成者IDを検索し、その動作を示します。 

    $ cat ~/bin/glog-find-author
#!/bin/sh
test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
$ cat msg.txt
subject

body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject

body text

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>

  • cmdを使用して ref トレーラーを構成し、スクリプト glog-grep を使用して、gitリポジトリのgitログから最後の関連するコミットをgrepし、それがどのように機能するかを示します。 

    $ cat ~/bin/glog-grep
#!/bin/sh
test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
$ cat msg.txt
subject

body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject

body text

Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)

  • 関連するコミットの件名を出力し、それがどのように機能するかを示すコマンドを使用して、「see」トレーラーを構成します: 

    $ cat msg.txt
subject

body text

see: HEAD~2
$ cat ~/bin/glog-ref
#!/bin/sh
git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
$ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.cmd "glog-ref"
$ git interpret-trailers --trailer=see <msg.txt
subject

body text

See-also: fe3187489d69c4 (subject of related commit)

  • 空の値を持ついくつかのトレーラーを使用してコミットテンプレートを構成し(sedを使用してトレーラーの後に末尾のスペースを出力および保持します)、次に、「git interpret-trailers」を使用するcommit-msgフックを構成して、値が空のトレーラーを削除し、「git-version」トレーラーを追加します: 

    $ cat temp.txt
***subject***

***message***

Fixes: Z
Cc: Z
Reviewed-by: Z
Signed-off-by: Z
$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
$ git config commit.template commit_template.txt
$ cat .git/hooks/commit-msg
#!/bin/sh
git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
mv "\$1.new" "\$1"
$ chmod +x .git/hooks/commit-msg

SEE ALSO

git-commit(1), git-format-patch(1), git-config(1)

GIT

Part of the git(1) suite