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

名称

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

概述

git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
		   [(--sort=<key>)…​] [--format=<format>]
		   [--include-root-refs] [--points-at=<object>]
		   [--merged[=<object>]] [--no-merged[=<object>]]
		   [--contains[=<object>]] [--no-contains[=<object>]]
		   [(--exclude=<pattern>)…​] [--start-after=<marker>]
		   [ --stdin | <pattern>... ]

描述

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

选项

<模式>…​

如果给出一个或多个模式，则只显示至少与一个模式匹配的 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=<模式>

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

--include-root-refs

列出根引用（HEAD 和伪引用），除了常规引用之外。

--start-after=<marker>

Allows paginating the output by skipping references up to and including the specified marker. When paging, it should be noted that references may be deleted, modified or added between invocations. Output will only yield those references which follow the marker lexicographically. Output begins from the first reference that would come after the marker alphabetically. Cannot be used with --sort=<key> or --stdin options, or the <pattern> argument(s) to limit the refs.

字段名

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

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

引用名

引用的名称（$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:<提交对象>

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

is-base:<committish>

在最多一行中，(<committish>) 将表示最有可能被用作产生 <committish> 分支起点的引用。这种选择是通过启发式来实现的：选择能使 <committish> 的第一父历史中的提交次数最少的引用，而不是该引用的第一父历史中的提交次数最少的引用。

例如，请看下图中几个引用的第一父本历史：

*--*--*--*--*--* refs/heads/A
\
 \
  *--*--*--* refs/heads/B
   \     \
    \     \
     *     * refs/heads/C
      \
       \
	*--* refs/heads/D

在这里，如果 A、B 和 C 是经过筛选的引用，格式字符串为 %(引用名称):%(is-base:D)，那么输出结果将是

refs/heads/A:
refs/heads/B:(D)
refs/heads/C:

这是因为 D 的第一父代历史记录与 B 和 C 的共同第一父代祖先处的已筛选引用的第一父代历史记录有最早的交集，并且在排序顺序中由最早的引用打破联系。

请注意，如果 <committish> 的父代历史记录与过滤后引用的父代历史记录不交叉，则不会出现此标记。

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 来实现。

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

As a special case for the date-type fields, you may specify a format for the date by adding : followed by date format name (see the values the --date option to git-rev-list[1] takes). If this formatting is provided in a --sort key, references will be sorted according to the byte-value of the formatted string rather than the numeric value of the underlying timestamp.

有些原子，如 %(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] 文档