中文 (简体) ▾ 主题 ▾ 最新版本 ▾ 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 电子邮件标头的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" 开头的最后两行是 trailers。

如果未指定 <file>，此命令从 <file> 参数或标准输入读取提交消息。 如果指定了 --parse，则输出由来自输入的已解析 trailers 组成，而不受任何命令行选项或配置变量的影响。

否则，此命令将应用 trailer.* 配置变量（可能添加新的 trailers 并重新定位它们），以及任何可以覆盖配置变量的命令行参数（例如 --trailer=...，也可以添加新的 trailers）到每个输入文件。结果将输出到标准输出。

此命令还可以操作 git-format-patch[1] 的输出，该输出比普通提交消息更详细。也就是说，此类输出包括提交消息（如上），"---" 分隔线和补丁部分。对于这些输入，分隔符和补丁部分不会被此命令修改，并且按原样输出，除非指定了 --no-divider。

一些配置变量控制着将 --trailer 参数应用于每个输入的方式，以及更改输入中任何现有 trailer 的方式。 它们还可以自动添加一些 trailers。

默认情况下，使用 --trailer 给出的<key>=<value> 或 <key>:<value> 参数仅在最后一个 trailer 具有不同的 (<key>, <value>) 对时（或者如果没有现有 trailer 时）才会被追加到现有 trailers 之后。 <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"。

默认情况下，新的 trailer 将出现在所有现有 trailers 的末尾。 如果没有现有 trailer，则新的 trailer 将出现在输入的末尾。 如果还没有空行，则会在新的 trailer 之前添加一个空行。

通过查找一组或多行来从输入中提取现有 trailers，这些行 (i) 全部是 trailers，或 (ii) 包含至少一个 Git 生成或用户配置的 trailer，并且至少由 25% 的 trailers 组成。 该组必须以一个或多个空行（或仅包含空格的行）开头。 该组必须位于输入的末尾，或者是以 ---（后跟空格或行尾）开头的行之前的最后非空格行。

读取 trailers 时，<key> 之前或内部不能有空格，但 <key> 和分隔符之间允许任意数量的常规空格和制表符。 <value> 之前、内部或之后可以有空格。 <value> 可以分成多行，每后续行以至少一个空格开头，就像 RFC 822 中的“折叠”一样。 例

key: This is a very long value, with spaces and
  newlines in it.

请注意，trailers 不遵循（也不打算遵循）RFC 822 标头的许多规则。 例如，它们不遵循编码规则。

选项

--in-place

就地编辑文件。

--trim-empty

如果任何 trailer 的 <value> 部分仅包含空格，则整个 trailer 将从输出中删除。 这适用于现有 trailers 以及新的 trailers。

--trailer <key>[(=|:)<value>]

指定应作为 trailer 应用于输入的 (<key>, <value>) 对。 请参阅此命令的描述。

--where <placement>
--no-where

指定所有新 trailers 将添加到的位置。 使用 --where 提供的设置会覆盖 trailer.where 和任何适用的 trailer.<keyAlias>.where 配置变量，并应用于所有 --trailer 选项，直到下一次出现 --where 或 --no-where。 遇到 --no-where 时，清除先前使用 --where 的任何效果，以便不再覆盖相关的配置变量。 可能的位置是 after、before、end 或 start。

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

指定当输入中已存在至少一个具有相同 <key> 的 trailer 时将执行的操作。 使用 --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> 的 trailer 时将执行的操作。 使用 --if-missing 提供的设置会覆盖 trailer.ifMissing 和任何适用的 trailer.<keyAlias>.ifMissing 配置变量，并应用于所有 --trailer 选项，直到下一次出现 --if-missing 或 --no-if-missing。 遇到 '--no-if-missing 时，清除先前使用 '--if-missing 的任何效果，以便不再覆盖相关的配置变量。 可能的操作是 doNothing 或 add。

--only-trailers

仅输出 trailers，而不输出输入的任何其他部分。

--only-input

仅输出输入中存在的 trailers； 不要从命令行或通过应用 trailer.* 配置变量添加任何内容。

--unfold

如果 trailer 的值跨越多行（也称为“折叠”），则将该值重新格式化为单行。

--parse

--only-trailers --only-input --unfold 的便捷别名。 这样可以更容易地只查看来自输入的 trailers，而不会受到任何命令行选项或配置变量的影响，同时还通过 --unfold 使输出对机器友好。

--no-divider

不要将 --- 视为提交信息的结尾。当您知道您的输入只包含提交信息本身（而不是电子邮件或 git format-patch 的输出）时，请使用此选项。

配置变量

本节中此行以下的所有内容均有选择地包含在 git-config[1] 文档中。 内容与在那里找到的相同

trailer.separators

此选项指定哪些字符被识别为 trailer 分隔符。 默认情况下，只有 *:* 被识别为 trailer 分隔符，但为了与其他 git 命令兼容，命令行的 *=* 始终被接受。

此选项给出的第一个字符将是默认字符，当此 trailer 的配置中未指定其他分隔符时使用。

例如，如果此选项的值为 "%=$"，则只有使用 <key><sep><value> 格式的行，且 <sep> 包含 %, = 或 $ 以及空格，才会被视为 trailers。% 将是使用的默认分隔符，因此默认情况下 trailers 将显示为：<key>% <value> (key 和 value 之间将出现一个百分号和一个空格)。

trailer.where

此选项指定新 trailer 将被添加到哪个位置。

可以是 end (默认值), start, after 或 before。

如果是 end，则每个新 trailer 将出现在现有 trailers 的末尾。

如果是 start，则每个新 trailer 将出现在现有 trailers 的开头，而不是末尾。

如果是 after，则每个新 trailer 将出现在与 <key> 相同的最后一个 trailer 之后。

如果是 before，则每个新 trailer 将出现在与 <key> 相同的第一个 trailer 之前。

trailer.ifexists

此选项允许您选择当输入中已经存在至少一个具有相同 <key> 的 trailer 时，将执行什么操作。

此选项的有效值为：addIfDifferentNeighbor (默认值), addIfDifferent, add, replace 或 doNothing。

使用 addIfDifferentNeighbor，仅当在将添加新 trailer 的行的上方或下方，没有具有相同 (<key>, <value>) 对的 trailer 时，才会添加新的 trailer。

使用 addIfDifferent，仅当输入中不存在具有相同 (<key>, <value>) 对的 trailer 时，才会添加新的 trailer。

使用 add，即使输入中已经存在一些具有相同 (<key>, <value>) 对的 trailers，也会添加新的 trailer。

使用 replace，具有相同 <key> 的现有 trailer 将被删除，并添加新的 trailer。 被删除的 trailer 将是（具有相同 <key>）最接近新 trailer 将被添加的位置的 trailer。

使用 doNothing，将不执行任何操作； 也就是说，如果输入中已经存在一个具有相同 <key> 的 trailer，则不会添加新的 trailer。

trailer.ifmissing

此选项允许您选择当输入中尚不存在任何具有相同 <key> 的 trailer 时，将执行什么操作。

此选项的有效值为：add (默认值) 和 doNothing。

使用 add，将添加新的 trailer。

使用 doNothing，将不执行任何操作。

trailer.<keyAlias>.key

定义 <key> 的 <keyAlias>。 <keyAlias> 必须是 <key> 的前缀（不区分大小写）。 例如，在 git config trailer.ack.key "Acked-by" 中，"Acked-by" 是 <key>，"ack" 是 <keyAlias>。 此配置允许在命令行上使用较短的 --trailer "ack:..." 调用，使用 "ack" <keyAlias> 代替较长的 --trailer "Acked-by:..."。

在 <key> 的末尾，可以出现分隔符，然后是一些空格字符。 默认情况下，唯一有效的分隔符是 *:*，但这可以使用 trailer.separators 配置变量来更改。

如果 key 中存在分隔符，则在添加 trailer 时，它将覆盖默认分隔符。

trailer.<keyAlias>.where

此选项采用与 *trailer.where* 配置变量相同的值，并且它会覆盖该选项为具有指定 <keyAlias> 的 trailers 指定的值。

trailer.<keyAlias>.ifexists

此选项采用与 *trailer.ifexists* 配置变量相同的值，并且它会覆盖该选项为具有指定 <keyAlias> 的 trailers 指定的值。

trailer.<keyAlias>.ifmissing

此选项采用与 *trailer.ifmissing* 配置变量相同的值，并且它会覆盖该选项为具有指定 <keyAlias> 的 trailers 指定的值。

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，然后在每次指定 --trailer <keyAlias>=<value> 参数以修改此选项将生成的 trailer 的 <value> 时，都会被调用。

当首次调用指定的命令以添加一个带有指定 <keyAlias> 的 trailer 时，其行为就像在 "git interpret-trailers" 命令的开头添加了一个特殊的 --trailer <keyAlias>=<value> 参数，其中 <value> 被视为该命令的标准输出，并去除了任何前导和尾随空格。

如果一些 --trailer <keyAlias>=<value> 参数也通过命令行传递，则对于每个具有相同 <keyAlias> 的参数，该命令将再次被调用一次。 这些参数的 <value> 部分（如果有）将作为其第一个参数传递给该命令。 这样，该命令可以生成一个从 --trailer <keyAlias>=<value> 参数中传递的 <value> 计算出的 <value>。

示例

  • 配置一个带有 Signed-off-by key 的 sign trailer，然后将两个这样的 trailers 添加到一个提交消息文件中

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

    $ 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 trailer，该 trailer 带有一个命令，可以自动添加一个 '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 trailer，该 trailer 的 key 包含一个 *#*，并且在该字符后没有空格，并展示它是如何工作的

    $ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject

Fix #42

  • 配置一个 help trailer，该 trailer 带有一个 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 trailer，该 trailer 带有一个 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 trailer，该 trailer 带有一个命令以显示相关提交的主题，并展示它是如何工作的

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

  • 使用一些带有空值的 trailers 配置一个提交模板 (使用 sed 来显示并保留 trailers 末尾的尾随空格)，然后配置一个 commit-msg hook，该 hook 使用 git interpret-trailers 来删除带有空值的 trailers 并添加一个 git-version trailer

    $ 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