SYNOPSIS
gitinterpret-trailers[--in-place] [--trim-empty] [(--trailer(<key>|<key-alias>)[(=|:)<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.* 構成変数を適用します(これにより新しいトレーラーが追加されたり、 位置が変更されたりする可能性があります)。 また、 構成変数を上書きできるコマンドライン引数(たとえば、 新しいトレーラーを追加する可能性のある --trailer=... など)も各入力ファイルに適用されます。 結果は標準出力に出力されます。
このコマンドでは git-format-patch(1) の出力を操作することもできます。 これは、 素のコミット・メッセージよりも複雑です。 つまり、 このような出力には、 (上記のとおりの)コミット・メッセージと --- 区切り線とパッチ部分が含まれます。 これらの入力の場合 --no-divider が指定されない限り、 区切り線以下とパッチ部分はこのコマンドによって変更されず、 そのまま出力されます。
いくつかの設定変数は --trailer 引数が各入力に適用される方法と、 入力内の既存のトレーラーが変更される方法を制御します。 また、 いくつかのトレーラを自動的に追加することもできます。
デフォルトでは、 --trailer で指定された <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> の前または内部に空白(whitespace)を含めることはできませんが、 <key> とセパレーターの間には、 任意の数の通常の空白(space)文字達とタブ文字達を使用できます。 <value> の前または内部または後ろに空白達(whitespaces)を入れることができます。 RFC 822 の「folding」(折り畳み)のように、 <value> は複数の行に分割され、 後続の各行の先頭は1つ以上の空白(whitespace)で始まります。
key: This is a very long value, with spaces and
newlines in it.注意: トレーラーはRFC822ヘッダー規則の多くに従うことを意図してませんし、 従わないことに注意してください。 たとえば、 それらはエンコーディング規則に従いません。
OPTIONS
-
--in-place -
その場でファイルを編集します。
-
--trim-empty -
トレーラーの <value> 部分に空白(whitespace)のみが含まれている場合、 出力からトレーラー全体が削除されます。 これは、 新しいトレーラーだけでなく、 既存のトレーラーにも適用されます。
-
--trailer<key>[(=|:)<value>] -
入力のトレーラーとして適用する必要があるペア(<key>, <value>)を指定します。 詳しくはこのコマンドの説明を参照してください。
-
--where<placement> -
--no-where -
すべての新しいトレーラーが追加される場所を指定します。
--whereで指定する設定は、trailer.whereや、 適用可能なtrailer.<keyAlias>.where構成変数を上書きし、 次に--whereまたは--no-whereが現れるまでのすべての--trailerオプションに適用されます。--no-whereに遭遇すると、 それまでに使用された--whereの効果がクリアされ、 関連する構成変数が上書きされなくなります。 <placement> として可能な値は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`の出力が含まれておらず、)入力にコミットメッセージ自体だけが含まれていることがわかっている場合にこれを使用します。
CONFIGURATION VARIABLES
- trailer.separators
-
このオプションは、どの文字がトレーラー区切り文字として認識されるかを示します。 デフォルトでは、
:のみがトレーラー区切り文字として認識されます。ただし、他のgitコマンドとの互換性のために、コマンドラインでは=が常に受け入れられます。このオプションで指定された最初の1文字は、このトレーラーの構成で別の区切り文字が指定されていない場合に使用されるデフォルトの文字になります。
たとえば、このオプションの値が "%=$" の場合、 <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> のプレフィックスである必要があり(大文字小文字は関係ありません)、 たとえば、
gitconfigtrailer.ack.key"Acked-by" ではAcked-byが <key> であり、ackが <keyAlias> です。 この設定により、 コマンドラインで長い--trailer"Acked-by:..." の代わりに、短い--trailer"ack:..." をack<keyAlias> を使って呼び出すことができます。<key> の末尾には、 セパレーターとその後にいくつかの空白文字(space characters)が現れることがあります。 デフォルトでは有効なセパレーターは
:のみですが、これは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 を置き換えるこのオリジナルの方法は安全ではないことに注意してください。
trailer.<keyAlias>.cmdとtrailer.<keyAlias>.commandの両方が同じ <keyAlias> で指定されている場合、trailer.<keyAlias>.cmdが使用され、trailer.<keyAlias>.commandは無視されます。 - trailer.<keyAlias>.cmd
-
このオプションは、 指定された <keyAlias> のトレーラを自動的に追加するために一度だけ呼び出され、 かつ、 追加後は、 このオプションが生成するトレーラの <value> を変更するために --trailer <keyAlias>=<value> 引数が指定されるたびに呼び出されるシェルコマンド、 を指定するために使うことができます。
指定のコマンドを最初に呼び出して、指定の <keyAlias> のトレーラーを追加すると、動作は、「git interpret-trailers」コマンドの先頭に特別な
--trailer<keyAlias>=<value> 引数が追加されたかのように振る舞います。ここで、 <value> は、先頭と末尾の空白が削除された、コマンドからの標準出力と見なされます。いくつかの
--trailer<keyAlias>=<value> 引数がコマンドラインで渡された場合、同じ <keyAlias> を持つこれらの引数ごとにコマンドが1回呼び出されます。そして、これらの引数の <value> 部分は、もしあれば、最初の引数としてコマンドに渡されます。このようにして、コマンドは--trailer<keyAlias>=<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
Part of the git(1) suite