Git
English ▾ トピック ▾ 最新バージョン ▾ git-interpret-trailers 最終更新 2.45.0

名前

git-interpret-trailers - コミットメッセージに構造化情報を追加または解析する

概要

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

説明

RFC 822 電子メールヘッダーに似た _トレーラー_ 行を、コミットメッセージの自由形式の部分の最後に追加または解析します。たとえば、次のコミットメッセージでは

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.* 設定変数 (新しいトレーラーを追加したり、位置を変更したりする可能性があります) と、設定変数をオーバーライドできるコマンドライン引数 (新しいトレーラーを追加できる --trailer=... など) を各入力ファイルに適用します。結果は標準出力に出力されます。

このコマンドは、プレーンなコミットメッセージよりも精巧な git-format-patch[1] の出力に対しても操作できます。つまり、そのような出力には、コミットメッセージ (上記のように)、「---」区切り線、およびパッチ部分が含まれます。これらの入力の場合、区切り線とパッチ部分は、--no-divider が指定されていない限り、このコマンドによって変更されず、出力にそのまま出力されます。

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

デフォルトでは、--trailer を使用して指定された _<key>=<value>_ または _<key>:<value>_ 引数は、最後のトレーラーに異なる (<key>, <value>) ペアがある場合 (または既存のトレーラーがない場合) にのみ、既存のトレーラーの後に追加されます。 <key> と <value> の部分は、先頭と末尾の空白を削除するためにトリミングされ、結果のトリミングされた <key> と <value> は次のように出力に表示されます

key: value

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

便宜上、<key-alias> を設定して、コマンドラインで --trailer の入力を短縮できます。これは _trailer.<key-alias>.key_ 設定変数を使用して設定できます。 <keyAlias> は、大文字と小文字の区別は関係ありませんが、完全な <key> 文字列のプレフィックスである必要があります。たとえば、設定に

trailer.sign.key "Signed-off-by: "

がある場合、コマンドラインで --trailer="Signed-off-by: foo" の代わりに --trailer="sign: foo" を指定するだけで済みます。

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

既存のトレーラーは、(i) すべてトレーラーである、または (ii) 少なくとも1つのGitによって生成されたまたはユーザー設定のトレーラーを含み、少なくとも25％のトレーラーで構成される、1つ以上の行のグループを探すことによって入力から抽出されます。グループの前に1つ以上の空行 (または空白のみの行) が必要です。グループは入力の最後にあるか、_---_ (スペースまたは行末が続く) で始まる行の前の最後の非空白行である必要があります。

トレーラーを読み取るとき、<key> の前または内側に空白を含めることはできませんが、<key> と区切り文字の間に任意の数の通常のスペースとタブ文字を使用できます。 <value> の前、内側、または後には空白を含めることができます。 <value> は、RFC 822 の「折りたたみ」のように、後続の各行が少なくとも1つの空白で始まる複数の行に分割できます。例:

key: This is a very long value, with spaces and
  newlines in it.

トレーラーは、RFC 822 ヘッダーの多くのルールに従っていない (または従うことを意図していない) ことに注意してください。たとえば、エンコーディングルールには従いません。

オプション

--in-place

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

--trim-empty

トレーラーの <value> 部分に空白のみが含まれている場合、トレーラー全体が出力から削除されます。これは、既存のトレーラーと新しいトレーラーの両方に適用されます。

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

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

--where <placement>
--no-where

すべての新しいトレーラーを追加する場所を指定します。 _--where_ で指定された設定は、 `trailer.where` および該当する `trailer.<keyAlias>.where` 設定変数をオーバーライドし、 _--where_ または _--no-where_ が次に発生するまで、すべての _--trailer_ オプションに適用されます。 _--no-where_ に遭遇したら、 _--where_ の以前の使用による影響をクリアして、関連する設定変数がオーバーライドされなくなります。可能な配置は、 `after`、 `before`、 `end`、または `start` です。

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

入力に同じ <key> を持つトレーラーが既に1つ以上ある場合に実行されるアクションを指定します。 _--if-exists_ で指定された設定は、 `trailer.ifExists` および該当する `trailer.<keyAlias>.ifExists` 設定変数をオーバーライドし、 _--if-exists_ または _--no-if-exists_ が次に発生するまで、すべての _--trailer_ オプションに適用されます。 '--no-if-exists に遭遇したら、 '--if-exists の以前の使用による影響をクリアして、関連する設定変数がオーバーライドされなくなります。可能なアクションは、 `addIfDifferent`、 `addIfDifferentNeighbor`、 `add`、 `replace`、および `doNothing` です。

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

入力に同じ <key> を持つ他のトレーラーがない場合に実行されるアクションを指定します。 _--if-missing_ で指定された設定は、 `trailer.ifMissing` および該当する `trailer.<keyAlias>.ifMissing` 設定変数をオーバーライドし、 _--if-missing_ または _--no-if-missing_ が次に発生するまで、すべての _--trailer_ オプションに適用されます。 '--no-if-missing に遭遇したら、 '--if-missing の以前の使用による影響をクリアして、関連する設定変数がオーバーライドされなくなります。可能なアクションは、 `doNothing` または `add` です。

--only-trailers

入力の他の部分ではなく、トレーラーのみを出力します。

--only-input

入力に存在するトレーラーのみを出力します。コマンドラインから、または `trailer.*` 設定変数を適用することによって、トレーラーを追加しないでください。

--unfold

トレーラーの値が複数行にわたる場合 (別名「折りたたみ」)、値を1行に再フォーマットします。

--parse

--only-trailers --only-input --unfold の便利なエイリアスです。これにより、コマンドラインオプションまたは設定変数で影響を与えることなく、入力からのトレーラーのみを簡単に確認でき、 `--unfold` で出力を機械可読にすることもできます。

--no-divider

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

設定変数

trailer.separators

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

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

例えば、このオプションの値が "%=$" の場合、<key><sep><value> の形式で、<sep> に %、=、または $ が含まれ、その後にスペースがある行のみがトレーラーと見なされます。そして、% がデフォルトで使用される区切り文字となるため、デフォルトではトレーラーは <key>% <value> のように表示されます（キーと値の間にパーセント記号1つとスペース1つが表示されます）。

trailer.where

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

これは、デフォルトの end、start、after、または before を指定できます。

end の場合、新しいトレーラーは既存のトレーラーの末尾に追加されます。

start の場合、新しいトレーラーは既存のトレーラーの末尾ではなく、先頭に追加されます。

after の場合、新しいトレーラーは同じ <key> を持つ最後のトレーラーの直後に追加されます。

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

trailer.ifexists

このオプションは、入力に同じ <key> を持つトレーラーが既に1つ以上存在する場合に実行されるアクションを選択できるようにします。

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

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

addIfDifferent を使用すると、入力に同じ (<key>, <value>) のペアを持つトレーラーがまだない場合にのみ、新しいトレーラーが追加されます。

add を使用すると、同じ (<key>, <value>) のペアを持つトレーラーが入力に既に存在する場合でも、新しいトレーラーが追加されます。

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

doNothing を使用すると、何も実行されません。つまり、入力に同じ <key> を持つトレーラーが既に存在する場合、新しいトレーラーは追加されません。

trailer.ifmissing

このオプションを使用すると、入力に同じ <key> を持つトレーラーがまだ存在しない場合に実行されるアクションを選択できます。

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

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

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

trailer.<keyAlias>.key

<key> の <keyAlias> を定義します。 <keyAlias> は <key> のプレフィックスである必要があります（大文字と小文字は区別されません）。たとえば、git config trailer.ack.key "Acked-by" では、「Acked-by」が <key> で、「ack」が <keyAlias> です。この設定により、長い --trailer "Acked-by:..." の代わりに、「ack」<keyAlias> を使用した短い --trailer "ack:..." 呼び出しをコマンドラインで使用できます。

<key> の末尾に区切り文字とスペース文字を指定できます。デフォルトでは、有効な区切り文字は : のみですが、これは trailer.separators 設定変数を使用して変更できます。

キーに区切り文字がある場合、トレーラーを追加するときにデフォルトの区切り文字がオーバーライドされます。

trailer.<keyAlias>.where

このオプションは、_trailer.where_ 設定変数と同じ値を受け取り、指定された <keyAlias> を持つトレーラーに対してそのオプションで指定された内容をオーバーライドします。

trailer.<keyAlias>.ifexists

このオプションは、_trailer.ifexists_ 設定変数と同じ値を受け取り、指定された <keyAlias> を持つトレーラーに対してそのオプションで指定された内容をオーバーライドします。

trailer.<keyAlias>.ifmissing

このオプションは、_trailer.ifmissing_ 設定変数と同じ値を受け取り、指定された <keyAlias> を持つトレーラーに対してそのオプションで指定された内容をオーバーライドします。

trailer.<keyAlias>.command

_trailer.<keyAlias>.cmd_ が推奨されるため、非推奨となりました。 このオプションは _trailer.<keyAlias>.cmd_ と同じように動作しますが、指定されたコマンドに引数として何も渡しません。代わりに、部分文字列 $ARG の最初の出現箇所が、引数として渡される <value> に置き換えられます。

ユーザーのコマンドの $ARG は一度だけ置き換えられ、元の $ARG の置き換え方法は安全ではないことに注意してください。

同じ <keyAlias> に対して _trailer.<keyAlias>.cmd_ と _trailer.<keyAlias>.command_ の両方が指定されている場合、_trailer.<keyAlias>.cmd_ が使用され、_trailer.<keyAlias>.command_ は無視されます。

trailer.<keyAlias>.cmd

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

指定されたコマンドが、指定された <keyAlias> を持つトレーラーを追加するために最初に呼び出されたとき、特別な _--trailer <keyAlias>=<value>_ 引数が "git interpret-trailers" コマンドの先頭に追加されたように動作します。ここで、<value> は、コマンドの標準出力から先頭と末尾の空白が削除されたものとみなされます。

いくつかの _--trailer <keyAlias>=<value>_ 引数もコマンドラインで渡された場合、コマンドはこれらの引数のそれぞれについて、同じ <keyAlias> を使用してもう一度呼び出されます。そして、これらの引数の <value> 部分（もしあれば）は、コマンドの最初の引数として渡されます。このようにして、コマンドは _--trailer <keyAlias>=<value>_ 引数で渡された <value> から計算された <value> を生成できます。

例

  • _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>

  • この文字の後にスペースがない _#_ を含むキーを使用して _fix_ トレーラーを設定し、その動作を示します

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

Fix #42

  • gitリポジトリのgitログから指定された作者IDを検索するスクリプト `glog-find-author` を使用するcmdで _help_ トレーラーを設定し、その動作を示します

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

  • gitリポジトリのgitログから最後の関連コミットをgrepするスクリプト `glog-grep` を使用するcmdで _ref_ トレーラーを設定し、その動作を示します

    $ 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_ を使用して空の値を持つトレーラーを削除し、_git-version_ トレーラーを追加するcommit-msgフックを設定します

    $ 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

関連項目

git-commit[1]、git-format-patch[1]、git-config[1]

GIT

git[1] スイートの一部

scroll-to-top