English ▾ トピック ▾ 最新バージョン ▾ git-interpret-trailers は2.49.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つ）で区切られることを意味します。

便宜上、`--trailer`のコマンドラインでの入力を短くするために、を設定できます。これは、`trailer..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

トレーラーに複数行にわたる値（「折りたたまれた」とも呼ばれる）がある場合、その値を単一行に再フォーマットします。

--parse

`--only-trailers --only-input --unfold`の便利なエイリアスです。これにより、入力からのトレーラーのみを、コマンドラインオプションや設定変数の影響を受けることなく、`--unfold`によって機械にわかりやすい出力で表示することが容易になります。

--no-divider

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

設定変数

このセクションのこの行より下の内容は、git-config[1]ドキュメンテーションから選択的に含まれています。内容はそちらにあるものと同じです。

trailer.separators

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

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

例えば、このオプションの値が"%=$"の場合、``に`%`、`=`、または`$`を含み、その後にスペースが続く``形式の行のみがトレーラーと見なされます。そして、`%`がデフォルトの区切り文字として使用されるため、デフォルトではトレーラーは次のように表示されます: `% `（キーと値の間にパーセント記号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>を持つトレーラーを自動的に追加するために一度呼び出され、その後、このオプションが生成するトレーラーの<value>を変更するために`--trailer =`引数が指定されるたびに呼び出されるシェルコマンドを指定するために使用できます。

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

コマンドラインで`--trailer =`引数が渡される場合、同じ<keyAlias>を持つこれらの引数ごとにコマンドが再度呼び出されます。そして、これらの引数の<value>部分（もしあれば）は、コマンドの最初の引数として渡されます。このようにして、コマンドは`--trailer =`引数で渡された<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 log`から指定された著者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 log`から最後の関連コミットを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