SYNOPSIS

git interpret-trailers [<options>] [(--trailer <token>[(=|:)<value>])…] [<file>…]
git interpret-trailers [<options>] [--parse] [<file>…]

DESCRIPTION

コミットメッセージの自由形式の部分の最後に、RFC 822 電子メールヘッダーに似たトレーラー(trailer)行の、追加またはパースを支援します。

このコマンドは、<file> 引数または、 <file>が指定されていない場合は標準入力のいずれかから、いくつかのパッチまたはコミットメッセージを読み取ります。 --parse が指定されている場合、出力はパースされたトレーラーで構成されます。

それ以外の場合、このコマンドは、 --trailer オプション(存在する場合)を使用して渡された引数を、各入力ファイルのコミットメッセージ部分に適用します。結果は標準出力に出力されます。

一部の構成変数は、 --trailer 引数が各コミットメッセージに適用される方法と、コミットメッセージ内の既存のトレーラーが変更される方法を制御します。また、トレーラーを自動的に追加することもできます。

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

token: value

これは、トリミングされた<token>と<value>が `: ` (1つのコロンとそれに続く1つのスペース)で区切られることを意味します。

デフォルトでは、新しいトレーラーは既存のすべてのトレーラーの後に出力されます。既存のトレーラーがない場合は、出力のコミットメッセージ部分の後に新しいトレーラーが出力されます。コミットメッセージ部分の最後に空白しかない行が存在しない場合は、新しいトレーラーの前に空行を1行追加します。

既存のトレーラーは、(i)すべてのトレーラーであるか、または、(ii)少なくとも1つのGit生成またはユーザー構成のトレーラーを含む少なくとも25％のトレーラーで構成される、1行以上のグループが入力メッセージから抽出されます。グループの前には、1行以上の空行(または空白のみの行)が必要です。グループは、メッセージの最後にあるか、 --- で始まる行の前の最後の非空白行である必要があります(その後にスペースまたは行の終わりが続きます)。このような3つのマイナス記号(---)は、メッセージのパッチ部分を開始します。 以下の --no-divider も参照してください。

トレーラーを読み取る場合、トークンと区切り文字と値の後に空白(whitespaces)を含めることができます。トークンと値の中に空白を含めることもできます。値は、RFC 822の "folding"(折りたたみ)のように、空白で始まる後続の各行で複数の行に分割される場合があります。

注意: トレーラーは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 と同じように動作します。代わりに、文字列に最初に現れる置換文字列 $ARG のみ、引数として渡される値に置き換えられます。

trailer.<token>.command オプションは非推奨になり’trailer.<token>.cmd' が採用されました。これは、ユーザーのコマンドの $ARG が一度だけ置き換えられることと、 $ARG を置き換える独創的な方法が安全でないためです。

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

trailer.<token>.cmd

このオプションを使用して、呼び出されるシェルコマンドを指定できます。最初の1回は、指定の <token> を持つトレーラーを自動的に追加し、その後、毎回 --trailer <token>=<value> 引数を使用して、このオプションが生成するトレーラーの <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

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

message

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

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

    $ cat msg.txt
subject

message

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

message

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」トレーラーを構成し、それがどのように機能するかを示します: 

    $ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers <<EOF
> EOF

Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers <<EOF
> Signed-off-by: Alice <alice@example.com>
> EOF

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
$ 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" <<EOF
> subject
>
> message
>
> EOF
subject

message

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
$ 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." <<EOF
> subject
>
> message
>
> EOF
subject

message

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

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

    $ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
$ git interpret-trailers <<EOF
> subject
>
> message
>
> see: HEAD~2
> EOF
subject

message

See-also: fe3187489d69c4 (subject of related commit)

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

    $ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
> ***subject***
>
> ***message***
>
> Fixes: Z
> Cc: Z
> Reviewed-by: Z
> Signed-off-by: Z
> EOF
$ git config commit.template commit_template.txt
$ cat >.git/hooks/commit-msg <<EOF
> #!/bin/sh
> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
> mv "\$1.new" "\$1"
> EOF
$ 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