简体中文 ▾ Topics ▾ Latest version ▾ git-interpret-trailers last updated in 2.49.0

名称

git-interpret-trailers - 添加或解析提交消息中的结构化信息

概述

git interpret-trailers [--in-place] [--trim-empty]
			[(--trailer (<key>|<key-alias>)[(=|:)<value>])…​]
			[--parse] [<file>…​]

描述

在提交信息中原本自由格式部分的末尾添加或解析与 RFC 822 电子邮件标题相似的 ‘尾注’ 行。例如，在以下提交信息中

主题

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 给出的 <键>=<值> 或 <键>:<值> 参数，只有在最后一个尾注具有不同的（<键>, <值>）对（或没有现有尾注）时，才会追加到现有尾注之后。<键> 和 <值> 部分将被修剪以去除起始和尾部的空白，修剪后的 <键> 和 <值> 将像这样出现在输出中：

键: 值

这意味着修剪后的 <键> 和 <值> 将用 ':'（一个冒号后加一个空格）分隔。

For convenience, a <key-alias> can be configured to make using --trailer shorter to type on the command line. This can be configured using the trailer.<key-alias>.key configuration variable. The <keyAlias> must be a prefix of the full <key> string, although case sensitivity does not matter. For example, if you have

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

时，只需在命令行中指定 --trailer="sign: foo"，而不是 -trailer="Signed-off-by:foo"。

默认情况下，新预告片将出现在所有现有尾注的末尾。如果没有现有尾注，新尾注将出现在输入内容的末尾。如果没有新尾注，则会在新尾注前添加一行空行。

从输入内容中提取现有尾注的方法是，在一行或多行中寻找一个组，该组(i) 全部是尾注，或 (ii) 包含至少一个 Git 生成或用户配置的尾注，且至少有 25% 的尾注。 该组行前必须有一个或多个空行（或仅空白行）。 该组必须位于输入内容的末尾，或者是以 --- 开头（后跟空格或行尾）的行之前的最后一行非空格行。

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

键: 这是个非常长的值，有空格和
  新行。

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

选项

--in-place

在原地编辑文件。

--trim-empty

如果任何尾注的 <值> 部分只包含空格，整个尾注将从产生的消息中被删除。 这适用于现有的尾注和新的尾注。

--trailer <键>[(=|:)<值>]

指定一个（<键>, <值>）对，应该作为尾注应用到输入信息中。参见此命令的描述。

--where <位置>
--no-where

指定所有新预告片的添加位置。 带有 --where 的设置会覆盖 trailer.where 和任何适用的 trailer.<键别名>.where 配置变量，并适用于所有 --trailer ` 选项，直到下一次出现 `--where 或 --no-where 。遇到 --no-where 选项时，会清除之前使用 --where 选项的效果，使相关配置变量不再被覆盖。可能的位置有 after 、before 、end 或 start。

--if-exists <行为>
--no-if-exists

指定当输入中已经存在至少一个具有相同 <键> 的尾注时将执行的操作。 使用 --if-exists 提供的设置会覆盖 trailer.ifExists 和任何适用的 trailer.<键别名>.ifExists 配置变量，并适用于所有 --trailer 选项，直到下一次出现 --if-exists 或 --no-if-exists。遇到 --no-if-exists 时，清除之前使用 --if-exists 的效果，使相关配置变量不再被覆盖。可能的操作包括 addIfDifferent 、addIfDifferentNeighbor 、add 、replace 和 doNothing。

--if-missing <行为>
--no-if-missing

指定当输入中没有与 <键> 相同的其他拖车时将执行的操作。 使用 --if-missing 提供的设置会覆盖 trailer.ifMissing 和任何适用的 trailer.<键别名>.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] 文档中摘录的。其内容与那里的内容相同：

Warning

Missing zh_HANS-CN/config/trailer.adoc

See original version for this content.

实例

  • 配置带有 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

正文

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

  • 使用 --in-place 选项就地编辑提交信息文件：

    $ cat msg.txt
subject

正文

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

正文

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
主题

正文

Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject

正文

Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject

正文

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

  • 在 cmd 中使用脚本 glog-find-author 配置一个 help 尾注，从 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

正文

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>

  • 在 cmd 中用脚本 glog-grep 从git仓库的git日志中搜索最后一次相关的提交并配置一个 ref 尾注，以下展示它是如何工作的：

    $ 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

正文

Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)

  • 配置一个带有命令的 see 尾注，以显示相关提交的主题，以下展示它是如何工作的：

    $ cat msg.txt
subject

正文

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

正文

See-also: fe3187489d69c4 (subject of related commit)

  • 配置一个带有一些空尾注的提交模板（使用 sed 来显示并保留尾注末尾的空格），然后配置一个 commit-msg 钩子，使用 git interpret-trailers 来移除空值尾注，并添加一个 git-version 尾注：

    $ cat temp.txt
***subject***

***消息***

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