Git
简体中文 ▾ Topics ▾ Latest version ▾ git-for-each-ref last updated in 2.45.2

名称

git-for-each-ref - 输出每个引用的信息

概述

git for-each-ref [--count=<数量>] [--shell|--perl|--python|--tcl]
		   [(--sort=<键>)…​] [--format=<格式>]
		   [ --stdin | <模式>…​ ]
		   [--points-at=<对象>]
		   [--merged[=<对象>]] [--no-merged[=<对象>]]
		   [--contains[=<对象>]] [--no-contains[=<对象>]]
		   [--exclude=<模式> …​]

描述

遍历所有与 <模式> 匹配的引用,并根据给定的 <格式> 显示它们,然后根据给定的 <键> 对它们进行排序。 如果给定了 <数量>,则在显示这么多记录后停止。 在指定的宿主语言中,<格式> 中的内插值可选择引用为字符串字面量,以便在该语言中直接求值。

选项

<模式>…​

如果给出一个或多个模式,则只显示至少与一个模式匹配的 refs,匹配方式可以是使用 fnmatch(3) 或字面匹配,在后一种情况下,完全匹配或从头匹配到斜线。

--stdin

如果提供了 --stdin,则会从标准输入而不是参数列表中读取模式列表。

--count=<数量>

默认情况下,该命令会显示与 <模式> 匹配的所有记录。 该选项可使其在显示了这么多索引后停止。

--sort=<键>

要排序的字段名。 前缀 - 表示按值的降序排序。 如果未指定,则使用 引用名 。 可以多次使用 --sort=<键> 选项,在这种情况下,最后一个键将成为主键。

--format=<格式>

一个字符串,从显示的 ref 和它指向的对象之间插入 %(字段名)。此外,字符串字面 %% 会显示为 %,而 %xx - 其中 xx 是十六进制数字 - 会显示为十六进制代码 xx 的字符。例如,%00`插值为 `\0 (NUL),%09`插值为 `\t (TAB),%0a`插值为 `\n (LF)。

未指定时,<格式> 默认为 %(对象名) SPC %(对象类型) TAB %(引用名)

--color[=<when>]

尊重`--format`选项中指定的任何颜色。<什么时候>`字段必须是`alwaysnever`或`auto`之一(如果没有<什么时候>,则表现为`always)。

--shell
--perl
--python
--tcl

如果给定,替代 %(字段名) 占位符的字符串将被引述为适合指定主机语言的字符串字面量。 这样做的目的是生成可直接 eval 的脚本。

--points-at=<对象>

只列出指向给定对象的引用。

--merged[=<对象>]

仅列出提示可从指定提交(如未指定,则为 HEAD)到达的引用。

--no-merged[=<对象>]

仅列出提示无法从指定提交(如未指定,则为 HEAD)到达的引用。

--contains[=<对象>]

仅列出包含指定提交(如未指定,则为 HEAD)的引用。

--no-contains[=<对象>]

仅列出不包含指定提交的引用(如未指定,则为 HEAD)。

--ignore-case

排序和筛选引用不区分大小写。

--omit-empty

在格式化的引用后不打印换行,因为格式化的引用会扩展为空字符串。

--exclude=<模式>

如果给出一个或多个模式,则只显示不匹配任何排除模式的参考文件。匹配规则与上文的 <模式> 相同。

字段名

引用对象中结构化字段的各种值可用于插值到输出结果中,或用作排序键。

所有对象都可以使用以下名称:

引用名

引用的名称($GIT_DIR/ 后面的部分)。 对于非含混的引用短名,可添加 :short。 选项 core.warnAmbiguousRefs 用于选择严格缩写模式。如果添加了 lstrip=<N> (rstrip=<N>),则会从引用名的前面(后面)删除 <N> 斜线分隔的路径组件(例如,%(refname:lstrip=2) 会将 refs/tags/foo 变成 foo%(refname:rstrip=2) 会将 refs/tags/foo 变成 refs)。 如果 <N> 是负数,则从指定的末端剥离尽可能多的路径组件,以留下 -<N> 路径组件(例如,%(refname:lstrip=-2)refs/tags/foo 转换为 tags/foo%(refname:rstrip=-1)refs/tags/foo 转换为 refs)。当引用没有足够的组件时,如果使用正 <N> 进行剥离,结果将变为空字符串;如果使用负 <N> 进行剥离,结果将变为完整的引用名称。 这两种情况都不是错误。

strip 可作为 lstrip 的同义词使用。

objecttype

对象的类型( blobtreecommittag )。

objectsize

对象的大小(与 git cat-file -s 报告相同)。 添加 :disk 可获得对象在磁盘上所占的大小(以字节为单位)。请参阅下文 注意事项 部分关于磁盘大小的说明。

objectname

对象名称(又称 SHA-1)。 如果是对象名称的非明确缩写,请添加 :short。 若要使用具有所需长度的对象名称缩写,请添加 :short=<长度>,其中最小长度为 MINIMUM_ABBREV。为确保对象名称的唯一性,长度可以超出设定值。

deltabase

如果给定对象存储为 delta,则扩展为 delta 基的对象名称。 否则,它会扩展为空对象名称(全部为零)。

上有仓库

可视为显示引用的 '上游' 的本地引用的名称。与上面的 引用名 相同,尊重 :short:lstrip:rstrip。 此外,还尊重 :track,以显示 "[前方 N,后方 M]" 和 :trackshort,以显示简短版本:">"(在前)、"<"(在后)、"<>"(在前和在后)或 "="(同步)。每当遇到未知的上游引用时,:track 也会打印 "[gone]"。添加 :track,nobracket,可显示不带括号的跟踪信息(即 "前方 N,后方 M")。

对于任何远程跟踪分支 %(upstream)%(upstream:remotename)%(upstream:remoteref)`分别指远程的名称和被跟踪的远程引用名称。换句话说,远程跟踪分支可以通过使用引用规范 `%(upstream:remoteref):%(upstream)%(upstream:remotename) 抓取来明确地单独更新。

如果引用没有关联跟踪信息,则该选项无效。 除 nobracket 以外的所有选项都是互斥的,但如果同时使用,则选择最后一个选项。

push

本地引用的名称,代表显示引用的 @{push}`位置。与 `upstream 相同,尊重 :short:lstrip:rstrip:track:trackshort:remotename:remoteref`选项。如果没有配置 `@{push} ref,则产生空字符串。

HEAD

如果 HEAD 与当前引用(已签出分支)匹配,则为 *,否则为 ''。

color

更改输出颜色。后跟 :<颜色名称>,其中颜色名称在 git-config[1] 的 “配置文件” 部分的 “值” 中有描述。 例如,%(color:bold red)

对齐

将 %(align:…​) 和 %(end) 之间的内容左对齐、中间对齐或右对齐。align: "之后是 width=<宽度>position=<位置>,顺序不限,中间用逗号隔开,其中 <位置> 可以是左对齐、右对齐或中间对齐,默认为左对齐 <宽度> 是对齐后内容的总长度。为简洁起见,可以省略前缀 "width=" 和/或 "position=",而使用裸露的 <宽度> 和 <位置>。 例如,%(align:<宽度>,<位置>)。如果内容长度大于宽度,则不执行对齐。如果与 --quote 一起使用,%(align:…​) 和 %(end) 之间的所有内容都会被加引号,但如果是嵌套内容,则只有最上层的内容会被加引号。

如果

作为 %(if)…​%(then)…​%(end) 或 %(if)…​%(then)…​%(else)…​%(end) 使用。 如果在 %(if)之后有一个带值或字符串字面意义的原子,则打印 %(then) 之后的所有内容;如果使用了 %(else) 原子,则打印 %(else) 之后的所有内容。当我们使用 %(HEAD) 原子打印 "*" 或 "",并希望仅在 HEAD 引用上应用 if 条件时,这将非常有用。 添加 ":equals=<字符串>" 或 ":notequals=<字符串>" 可将 %(if:…​) 原子和 %(then) 原子之间的值与给定字符串进行比较。

symref

所给符号引用指向的引用。如果不是符号引用,则不会打印任何内容。与上文的 引用名 相同,遵从 :short:lstrip:rstrip 选项。

signature

检查提交的 GPG 签名。

signature:grade

显示 "G" 代表一个好的(有效的)签名,"B" 代表一个坏的签名,"U" 代表一个有效性未知的好的签名,"X" 代表一个已经过期的好的签名,"Y" 代表一个由过期的钥匙制作的好的签名,"R" 代表一个由撤销的密钥制作的好的签名,"E" 如果不能检查签名(如缺少密钥),"N" 代表没有签名。

signature:signer

提交的 GPG 签名的签名者。

signature:key

提交的 GPG 签名密钥。

signature:fingerprint

提交的 GPG 签名指纹。

signature:primarykeyfingerprint

提交的 GPG 签名的主键指纹。

signature:trustlevel

提交的 GPG 签名的信任级别。可能的输出包括 ultimatefullymarginalneverundifined

工作目录树路径

如果引用在任何链接的工作树中签出,则该引用签出所在工作目录的绝对路径。否则为空字符串。

ahead-behind:<提交对象>

用空格分隔的两个整数,分别表示将输出引用与格式中指定的 <提交对象> 进行比较时,超前和滞后提交的次数。

describe[:options]

人类可读的名字,像 git-describe[1];空字符串表示不可描述的提交。 describe 字符串后面可以有冒号和零个或多个逗号分隔的选项。 当标签同时被添加或删除时,描述可能不一致。

tags=<布尔值>

详细内容请参见 git-describe[1] 中的相应选项。

abbrev=<数字>

至少使用 <数字> 十六进制数字;详见 git-describe[1] 中的相应选项。

match=<模式>

只考虑与给定的 glob(7) 模式匹配的标签,不包括 "refs/tags/" 前缀;详见 git-describe[1] 中的相应选项。

exclude=<模式>

不考虑与给定的 glob(7) 模式(不包括 "refs/tags/" 前缀)匹配的标签;详情参见 git-describe[1] 中的相应选项。

除上述内容外,对于提交和标记对象,头字段名称( treeparentobjecttypetag )可用于指定头字段名称中的值。 字段 treeparent 也可以与修饰符 :short:short=<长度> 一起使用,就像 对象名 一样。

对于提交和标记对象,特殊的 creatordatecreator 字段将与 committertagger 字段中的相应日期或姓名-电子邮件-日期元组相对应,具体取决于对象类型。 这些都是为混合使用注释标记和轻量级标记而设计的。

对于标签对象,前缀为星号 (*) 的 fieldname 会扩展为剥离对象的 fieldname 值,而不是标签对象本身的值。

以姓名-电子邮件-日期元组为值的字段( authorcommittertagger)可以后缀 nameemaildate,以提取命名组件。 对于电子邮件字段( authoremailcommitteremailtaggeremail ),可添加 :trim 以获取不带角括号的电子邮件,并添加 :localpart 以从修剪后的电子邮件中获取 @ 符号之前的部分。除此之外,还可以使用 :mailmap 选项和相应的 :mailmap,trim:mailmap,localpart(顺序并不重要),根据 .mailmap 文件或 mailmap.file 或 mailmap.blob 配置变量(参见 gitmailmap[5])中设置的文件,获取姓名和电子邮件的值。

对象中的原始数据是 raw

raw:size

对象的原始数据大小。

请注意,--format=%(raw) 不能与 --python--shell--tcl 一起使用,因为这些语言的字符串变量类型可能不支持任意二进制数据。

提交或标记对象中的信息是 contents,从中可使用 contents:<部分> 提取不同部分:

contents:size

提交或标记信息的大小(字节)。

contents:subject

信息的第一段(通常为单行)将作为提交或标记信息的 "主题"。 也可以使用字段 subject 代替 contents:subject ,以获得相同的结果。对于适合文件名的主题行,可在 subject 中添加 :sanitize

contents:body

"subject" 后的其余提交内容或标记信息。

contents:signature

tag的可选GPG签名。

contents:lines=N

信息的前 N 行。

此外,git-interpret-trailers[1] 中提到的的尾注可作为 trailers[:options] 获取(或使用历史别名 contents:trailers[:options])。有关有效的 [:option] 值,请参阅 git-log[1]trailers 部分。

为便于排序,具有数值的字段按数值顺序排序( objectsize , authordate , committerdate , creatordate , taggerdate )。 所有其他字段都按字节值顺序排序。

还有一个按版本排序的选项,可以通过使用字段名 version:refname 或其别名 v:refname 来实现。

在任何情况下,如果字段名指向的字段不适用于引用所引用的对象,都不会导致错误。 它会返回一个空字符串替代输出。

作为日期类型字段的一种特殊情况,您可以在日期格式名称后添加 : 来指定日期的格式(参见 git-rev-list[1]--date 选项的取值)。

有些原子,如 %(align) 和 %(if) 总是需要一个匹配的 %(end)。 我们称它们为 “起始原子”,有时用 %($open) 表示。

当脚本语言的特定引用生效时,顶层起始原子和与其匹配的 %(end) 之间的所有内容都会根据起始原子的语义进行评估,只有其从顶层得到的结果才会被引用。

实例

直接生成格式化文本的示例。 显示最近 3 次标记的提交:

#!/bin/sh

git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*作者名) %(*作者邮箱)
Subject: %(*主题)
Date: %(*authordate)
Ref: %(*引用名)

%(*body)
' 'refs/tags'

一个简单的示例,说明如何在输出中使用 shell eval,并演示如何使用 --shell。 列出所有文件头的前缀:

#!/bin/sh

git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
while read entry
do
	eval "$entry"
	echo `dirname $ref`
done

关于标签的报告更详细一些,表明格式可能是整个脚本:

#!/bin/sh

fmt='
	r=%(引用名)
	t=%(*对象类型)
	T=${r#refs/tags/}

	o=%(*objectname)
	n=%(*authorname)
	e=%(*authoremail)
	s=%(*subject)
	d=%(*authordate)
	b=%(*body)

	kind=Tag
	if test "z$t" = z
	then
		# could be a lightweight tag
		t=%(对象类型)
		kind="Lightweight tag"
		o=%(对象名)
		n=%(作者名)
		e=%(作者邮箱)
		s=%(主题)
		d=%(authordate)
		b=%(主体)
	fi
	echo "$kind $T points at a $t object $o"
	if test "z$t" = zcommit
	then
		echo "The commit was authored by $n $e
at $d, and titled

    $s

其信息如下:
"
		echo "$b" | sed -e "s/^/    /"
		echo
	fi
'

eval=`git for-each-ref --shell --format="$fmt" \
	--sort='*对象类型' \
	--sort=-taggerdate \
	refs/tags`
eval "$eval"

举例说明 %(if)…​%(then)…​%(else)…​%(end) 的用法。 这会给当前分支加上星号前缀。

git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/

举例说明 %(if)…​%(then)…​%(end)的用法。 如果存在授权名称,则打印该名称。

git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"

注意事项

需要注意的是,磁盘上对象的大小会被准确地报告出来,但在得出哪些记录或对象造成了磁盘使用量的结论时应小心谨慎。打包的非 delta 对象的大小可能远大于与之相对的 delta 对象的大小,但选择哪个对象为基准对象,哪个对象为 delta 对象是任意的,在重新打包时可能会发生变化。

还请注意,对象数据库中可能存在一个对象的多个副本;在这种情况下,无法确定将报告哪个副本的大小或 delta 基数。

注释

当组合多个 --contains--no-contains 过滤器时,只显示至少包含一个 --contains 的提交,并且不包含 --no-contains 的提交引用。

当结合多个 --merged--no-merged 过滤器时,只显示至少有一个 --merged 提交和没有 --no-merged 提交的引用。

GIT

属于 git[1] 文档

scroll-to-top