简体中文 ▾ 主题 ▾ 最新版本 ▾ 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" 开头的行是尾部。

如果没有指定 <文件>，此命令会从 <文件> 参数或标准输入读取提交消息。如果指定了 --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>。

示例

  • 配置一个 sign 尾部，其键为 Signed-off-by，然后将其中两个尾部添加到提交消息文件

    $ 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 日志中搜索指定的作者身份，并展示其工作原理

    $ 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 日志中 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 尾部

    $ 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] 套件的一部分