Git

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

名称

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[1] 文档

Setup and Config

Getting and Creating Projects

Basic Snapshotting

Branching and Merging

Sharing and Updating Projects

Inspection and Comparison

Patching

Debugging

Email

External Systems

Server Admin

Guides

Administration

Plumbing Commands

名称

概述

描述

选项

配置变量

实例

参见

GIT