簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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”開頭的即為附註行。

此命令從 <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> 將由 : （一個冒號後跟一個空格）分隔。

為了方便起見，可以配置一個 <key-alias> 以縮短在命令列上鍵入 --trailer 的長度。這可以使用 trailer.<key-alias>.key 配置變數進行配置。<keyAlias> 必須是完整 <key> 字串的字首，儘管不區分大小寫。例如，如果您有

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

在您的配置中，您只需在命令列上指定 --trailer="sign: foo"，而無需指定 --trailer="Signed-off-by: foo"。

預設情況下，新的附註行將出現在所有現有附註行的末尾。如果沒有現有附註行，新的附註行將出現在輸入的末尾。如果新附註行前面沒有空行，則會新增一個空行。

現有附註行透過查詢一組一行或多行來從輸入中提取，該組行 (i) 全部是附註行，或者 (ii) 包含至少一個 Git 生成的或使用者配置的附註行，並且至少由 25% 的附註行組成。該組行之前必須有一行或多行空行（或僅包含空白字元的行）。該組行必須位於輸入的末尾，或者是在以 --- 開頭（後跟一個空格或行尾）的行之前的最後非空白行。

讀取附註行時，<key> 之前或內部不能有空白字元，但 <key> 和分隔符之間允許任意數量的常規空格和製表符。<value> 之前、內部或之後可以有空白字元。<value> 可以分成多行，每後續行都以至少一個空白字元開頭，類似於 RFC 822 中的“摺疊”。示例

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 配置變數，並適用於所有 --trailer 選項，直到下一次出現 --where 或 --no-where。當遇到 --no-where 時，清除之前使用 --where 的效果，使相關配置變數不再被覆蓋。可能的位置有 after（之後）、before（之前）、end（末尾）或 start（開頭）。

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

指定當輸入中已存在至少一個具有相同 <key> 的附註行時將執行的操作。使用 --if-exists 提供的設定會覆蓋 trailer.ifExists 和任何適用的 trailer.<keyAlias>.ifExists 配置變數，並適用於所有 --trailer 選項，直到下一次出現 --if-exists 或 --no-if-exists。當遇到 '--no-if-exists 時，清除之前使用 '--if-exists 的效果，使相關配置變數不再被覆蓋。可能的動作有 addIfDifferent、addIfDifferentNeighbor、add、replace 和 doNothing。

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

指定當輸入中沒有其他具有相同 <key> 的附註行時將執行的操作。使用 --if-missing 提供的設定會覆蓋 trailer.ifMissing 和任何適用的 trailer.<keyAlias>.ifMissing 配置變數，並適用於所有 --trailer 選項，直到下一次出現 --if-missing 或 --no-if-missing。當遇到 '--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 命令相容，命令列上始終接受 =。

此選項指定的第一個字元將是預設字元，當此附註行在配置中未指定其他分隔符時使用。

例如，如果此選項的值為“%=$”，那麼只有使用格式 <key><sep><value> 且 <sep> 包含 %、= 或 $，然後是空格的行才會被視為附註行。而 % 將是預設使用的分隔符，因此預設情況下附註行將顯示為：<key>% <value>（一個百分號和一個空格將出現在鍵和值之間）。

trailer.where

此選項指定新附註行將新增的位置。

這可以是預設值 end（末尾），start（開頭），after（之後）或 before（之前）。

如果是 end，則每個新附註行將出現在現有附註行的末尾。

如果是 start，則每個新附註行將出現在現有附註行的開頭，而不是末尾。

如果是 after，則每個新附註行將出現在具有相同 <key> 的最後一個附註行之後。

如果是 before，則每個新附註行將出現在具有相同 <key> 的第一個附註行之前。

trailer.ifexists

此選項使得在輸入中已存在至少一個具有相同 <key> 的附註行時，可以選擇要執行的操作。

此選項的有效值包括：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>。此配置允許在命令列上使用“ack”<keyAlias> 呼叫更短的 --trailer "ack:..."，而不是更長的 --trailer "Acked-by:..."。

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

此選項可用於指定一個 shell 命令，該命令將被呼叫一次以自動新增具有指定 <keyAlias> 的附註行，然後每當指定 --trailer <keyAlias>=<value> 引數時再次呼叫，以修改此選項將生成的附註行的 <value>。

當首次呼叫指定命令以新增具有指定 <keyAlias> 的附註行時，其行為等同於在“git interpret-trailers”命令開頭添加了一個特殊的 --trailer <keyAlias>=<value> 引數，其中 <value> 被認為是命令的標準輸出，並去除了任何前導和尾隨空白字元。

如果在命令列上也傳遞了某些 --trailer <keyAlias>=<value> 引數，則該命令將針對每個具有相同 <keyAlias> 的此類引數再次呼叫一次。並且這些引數的 <value> 部分（如果有）將作為其第一個引數傳遞給該命令。透過這種方式，命令可以從 --trailer <keyAlias>=<value> 引數中傳遞的 <value> 計算出 <value>。

示例

  • 配置一個帶有 Signed-off-by 鍵的 sign 附註行，然後將其中兩個附註行新增到提交訊息檔案中

    $ 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

  • 配置一個帶有命令的 sign 附註行，該命令僅在尚無“Signed-off-by:”的情況下自動新增帶有作者資訊的“Signed-off-by:”，並演示其工作原理

    $ 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

  • 配置一個帶有命令的 help 附註行，該命令使用指令碼 glog-find-author 從 Git 倉庫中的 Git 日誌中搜索指定的作者身份，並演示其工作原理

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

  • 配置一個帶有命令的 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 顯示並保留附註行末尾的尾隨空格），然後配置一個 commit-msg 鉤子，使用 git interpret-trailers 刪除值為空的附註行並新增一個 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

另請參閱

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

GIT

Git[1] 套件的一部分

scroll-to-top