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

名称

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`选项中指定的任何颜色。<什么时候>`字段必须是`always、never`或`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

对象的类型（ blob ， tree ， commit ， tag ）。

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 签名的信任级别。可能的输出包括 ultimate ， fully ， marginal ， never 和 undifined。

工作目录树路径

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

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] 中的相应选项。

除上述内容外，对于提交和标记对象，头字段名称（ tree ， parent ， object ， type 和 tag ）可用于指定头字段名称中的值。 字段 tree 和 parent 也可以与修饰符 :short 和 :short=<长度> 一起使用，就像 对象名 一样。

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

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

以姓名-电子邮件-日期元组为值的字段（ author ， committer 和 tagger）可以后缀 name ， email 和 date，以提取命名组件。 对于电子邮件字段（ authoremail ， committeremail 和 taggeremail ），可添加 :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-show-ref[1]

GIT

属于 git[1] 文档

scroll-to-top