Git
简体中文 ▾ Topics ▾ Latest version ▾ git-interpret-trailers last updated in 2.45.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 的输出）时，请使用这个方法。

配置变量

trailer.separators

这个选项告诉我们哪些字符可以被识别为尾注分隔符。默认情况下，只有 : 被识别为尾注分隔符，但为了与其他 git 命令兼容，命令行上总是接受 =。

当这个尾注的配置中没有指定其他分隔符时，这个选项给出的第一个字符将是默认使用的字符。

例如，如果该选项的值为 "%=$"，那么只有使用 "<键><分隔符><值>" 格式（<分隔符> 包含 %、= 或 $，然后是空格）的行才会被视为尾注。而 % 将是默认使用的分隔符，因此默认情况下，预告片将显示如下：<键>% <值>'（在键和值之间会出现一个百分号和一个空格）。

trailer.where

这个选项告诉人们新的尾注将被添加到哪里。

默认是 end，也可以是 start，after 或 before。

如果它是 end，那么每个新的拖车将出现在现有拖车的末尾。

如果是 start，那么每个新尾注将出现在现有尾注的开端，而不是结尾。

如果是 after，那么每个新的尾注将出现在具有相同 <键> 的最后一个尾注之后。

如果是 before，那么每个新的尾注将出现在具有相同 <键> 的第一个尾注之前。

trailer.ifexists

通过该选项，可以选择在输入中至少有一个相同 <键> 的尾注时将执行的操作。

这个选项的有效值是： addIfDifferentNeighbor（这是默认值），addIfDifferent，add，replace 或 doNothing。

使用 addIfDifferentNeighbor，只有在没有相同（<键>, <值>）的尾注对在新尾注的上方或下方，才会添加新的尾注。

使用 addIfDifferent，只有当信息中没有相同的（<键>, <值>）尾注时，才会添加新的尾注。

使用 add，一个新的尾注将被添加，即使一些具有相同（<键>, <值>）对的尾注已经在信息中。

使用 replace，一个具有相同 <键> 的现有尾注将被删除，新的尾注将被添加。被删除的尾注将是离新尾注位置最近的一个（具有相同的<键>）。

使用 doNothing，将不做任何事情；也就是说，如果消息中已经有一个相同的 <键>，将不会再添加新的尾注。

trailer.ifmissing

这个选项使我们有可能选择当信息中还没有任何具有相同 <键> 的尾注时，将执行什么行为。

这个选项的有效值是： add（这是默认值）和 doNothing。

使用 add，一个新的尾注将被添加。

有了 doNothing，就不会有任何事情发生。

trailer.<键别名>.key

为 <键> 定义 <键别名> 。<键别名> 必须是 <键> 的前缀（大小写并不重要）。例如，在 git config trailer.ack.key "Acked-by" 中，"Acked-by" 是 <键>，"ack" 是 <键别名>。这种配置允许在命令行上使用 "ack" <键别名> 调用较短的 --trailer "ack:..."，而不是较长的 --trailer "Acked-by:..."。

这个 key 将被用来代替尾注中的 <键>。在这个键的末端，可以出现一个分隔符，然后是一些空格字符。默认情况下，唯一有效的分隔符是 :，但这可以通过 trailer.separators 配置变量来改变。

如果密钥中有分隔符，则在添加尾注时会覆盖默认分隔符。

trailer.<键别名>.where

这个选项与 trailer.where 配置变量的取值相同，对于指定 <键别名> 的尾注，它覆盖了该选项所指定的内容。

trailer.<键别名>.ifexists

这个选项与 trailer.ifexists 配置变量的取值相同，对于具有指定 <键别名> 的尾注，它覆盖了该选项所指定的内容。

trailer.<键别名>.ifmissing

这个选项与 trailer.ifmissing 配置变量的取值相同，对于指定 <键别名> 的尾注，它覆盖该选项所指定的内容。

trailer.<键别名>.command

已弃用，改用 trailer.<键别名>.cmd。 该选项的作用与 trailer.<键别名>.cmd 相同，但它不会将任何内容作为参数传递给指定的命令。 相反，子串 $ARG 的第一次出现会被作为参数传递的 <值> 所替代。

请注意，用户命令中的 $ARG 只被替换一次，而原来替换 $ARG 的方法并不安全。

当 trailer.<键别名>.cmd 和 trailer.<键别名>.command 都是针对同一个 <键别名> 给出的时候，使用 trailer.<键别名>.cmd，trailer.<键别名>.command 被忽略。

trailer.<键别名>.cmd

这个选项可以用来指定一个将被调用的shell 命令：一次自动添加一个指定的 <键别名> 的尾注，然后每次用 --trailer <键别名>=<值> 参数来修改这个选项将产生的尾注的 <值>。

当第一次调用指定的命令来添加带有指定 <token> 的尾注时，其行为就像在 "git interpret-trailers" 命令的开头添加了一个特殊的 --trailer <键别名>=<值> 参数，其中 <值> 被认为是该命令的标准输出，其前面和后面的空白被修剪掉。

如果在命令行中还传递了一些 --trailer <键别名>=<值> 参数，那么对于这些参数中的每一个，都会以相同的 <键别名> 再次调用该命令。而这些参数的 <值> 部分，如果有的话，将作为第一个参数传递给命令。这样，命令可以产生一个从 --trailer <键别名>=<值> 参数中传递的 <值> 计算出来的 <值>。

实例

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