簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-interpret-trailers 上次更新於 2.51.1

名稱

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>。此配置允許在命令列上使用更短的 --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 尾註，其 cmd 使用一個指令碼 glog-find-author，該指令碼在 git 儲存庫中從 git log 中搜索指定的作者身份，並展示其工作方式

    $ 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 尾註，其 cmd 使用一個指令碼 glog-grep 來在 git 儲存庫的 git log 中 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 來刪除空值尾註並新增 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] 套件的一部分