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

名称

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

概述

git interpret-trailers [--in-place] [--trim-empty]
			[(--trailer (<键>|<键别名>)[(=|:)<值>])…​]
			[--parse] [<文件>…​]

描述

在提交信息中原本自由格式部分的末尾添加或解析与 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" 开头的最后两行是尾注。

This command reads commit messages from either the <file> arguments or the standard input if no <file> is specified. If --parse is specified, the output consists of the parsed trailers coming from the input, without influencing them with any command line options or configuration variables.

否则,该命令会在每个输入文件中应用 trailer.* 配置变量(可能会添加新的拖车,也可能会调整拖车的位置),以及任何可以覆盖配置变量的命令行参数(例如 --trailer=...,也可能会添加新的拖车)。结果将输出到标准输出中。

This command can also operate on the output of git-format-patch[1], which is more elaborate than a plain commit message. Namely, such output includes a commit message (as above), a "---" divider line, and a patch part. For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless --no-divider is specified.

一些配置变量可以控制 --trailer 参数应用于每条提交信息的方式,以及修改提交信息中任何现有尾注的方式。它们还可以自动添加一些尾注。

默认情况下,使用 --trailer 给出的 <键>=<值><键>:<值> 参数,只有在最后一个尾注具有不同的(<键>, <值>)对(或没有现有尾注)时,才会追加到现有尾注之后。<键> 和 <值> 部分将被修剪以去除起始和尾部的空白,修剪后的 <键> 和 <值> 将像这样出现在输出中:

键: 值

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

为方便起见,可以配置 <keyAlias> 以缩短使用 --trailer 命令行的键入时间。可以使用 trailer.<keyAlias>.key 配置变量进行配置。<keyAlias> 必须是完整 <key> 字符串的前缀,但大小写敏感性并不重要。例如

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

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

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

Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. The group must either be at the end of the input or be the last non-whitespace lines before a line that starts with --- (followed by a space or the end of the line).

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

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

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

选项

--in-place

在原地编辑文件。

--trim-empty

If the <value> part of any trailer contains only whitespace, the whole trailer will be removed from the output. This applies to existing trailers as well as new trailers.

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

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

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

Specify where all new trailers will be added. A setting provided with --where overrides the trailer.where and any applicable trailer.<keyAlias>.where configuration variables and applies to all --trailer options until the next occurrence of --where or --no-where. Upon encountering --no-where, clear the effect of any previous use of --where, such that the relevant configuration variables are no longer overridden. Possible placements are after, before, end or start.

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

Specify what action will be performed when there is already at least one trailer with the same <key> in the input. A setting provided with --if-exists overrides the trailer.ifExists and any applicable trailer.<keyAlias>.ifExists configuration variables and applies to all --trailer options until the next occurrence of --if-exists or --no-if-exists. Upon encountering '--no-if-exists, clear the effect of any previous use of '--if-exists, such that the relevant configuration variables are no longer overridden. Possible actions are addIfDifferent, addIfDifferentNeighbor, add, replace and doNothing.

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

Specify what action will be performed when there is no other trailer with the same <key> in the input. A setting provided with --if-missing overrides the trailer.ifMissing and any applicable trailer.<keyAlias>.ifMissing configuration variables and applies to all --trailer options until the next occurrence of --if-missing or --no-if-missing. Upon encountering '--no-if-missing, clear the effect of any previous use of '--if-missing, such that the relevant configuration variables are no longer overridden. Possible actions are doNothing or 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,也可以是 startafterbefore

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

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

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

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

trailer.ifexists

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

这个选项的有效值是: addIfDifferentNeighbor(这是默认值),addIfDifferentaddreplacedoNothing

使用 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

Deprecated in favor of trailer.<keyAlias>.cmd. This option behaves in the same way as trailer.<keyAlias>.cmd, except that it doesn’t pass anything as argument to the specified command. Instead the first occurrence of substring $ARG is replaced by the <value> that would be passed as argument.

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

trailer.<键别名>.cmdtrailer.<键别名>.command 都是针对同一个 <键别名> 给出的时候,使用 trailer.<键别名>.cmdtrailer.<键别名>.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>
  • 将最后一次提交的内容提取为补丁,并在其中加入 CcReviewed-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

属于 git[1] 文档

scroll-to-top