简体中文 ▾ 主题 ▾ 最新版本 ▾ git-for-each-ref 最后更新于 2.50.0

名称

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

概要

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

描述

迭代所有匹配 <pattern> 的引用，并根据给定的 <format> 显示它们，在显示之前按给定的一组 <key> 进行排序。如果给定 <count>，则在显示这么多引用后停止。 <format> 中的插值值可以根据指定的主机语言选择性地引用为字符串字面量，允许它们在该语言中直接求值。

选项

<pattern>…​

如果给定一个或多个模式，则只显示与至少一个模式匹配的引用，匹配方式可以是 fnmatch(3) 或字面量匹配，后者可以是完全匹配或从开头到斜杠的匹配。

--stdin

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

--count=<count>

默认情况下，该命令显示所有匹配 <pattern> 的引用。此选项使其在显示这么多引用后停止。

--sort=<key>

用于排序的字段名。在值前面加上 - 可按降序排序。未指定时，使用 refname。你可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键将成为主键。

--format=<format>

一个字符串，用于插入所显示引用中的 %(fieldname) 及其指向的对象。此外，字符串字面量 %% 渲染为 %，%xx (其中 xx 是十六进制数字) 渲染为十六进制代码 xx 的字符。例如，%00 插值为 \0 (空字符)，%09 为 \t (制表符)，%0a 为 \n (换行符)。

未指定时，<format> 默认为 %(objectname) SPC %(objecttype) TAB %(refname)。

--color[=<when>]

遵循 --format 选项中指定的任何颜色。 <when> 字段必须是 always、never 或 auto 之一（如果 <when> 不存在，则行为如同给定 always）。

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

如果给出，将 %(fieldname) 占位符替换的字符串引用为适合指定主机语言的字符串字面量。这旨在生成可以直接 `eval` 的脚本片段。

--points-at=<object>

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

--merged[=<object>]

只列出其尖端可从指定提交（如果未指定，则为 HEAD）到达的引用。

--no-merged[=<object>]

只列出其尖端不可从指定提交（如果未指定，则为 HEAD）到达的引用。

--contains[=<object>]

只列出包含指定提交（如果未指定，则为 HEAD）的引用。

--no-contains[=<object>]

只列出不包含指定提交（如果未指定，则为 HEAD）的引用。

--ignore-case

排序和过滤引用时忽略大小写。

--omit-empty

在格式化引用中，如果格式扩展为空字符串，则不在其后打印换行符。

--exclude=<pattern>

如果给定一个或多个模式，则只显示不匹配任何排除模式的引用。匹配使用与上述 <pattern> 相同的规则。

--include-root-refs

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

字段名称

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

对于所有对象，可以使用以下名称

refname

引用的名称（$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 以获取对象在磁盘上占用的字节大小。请参阅下面 CAVEATS 部分中关于磁盘大小的说明。

objectname

对象名称（即 SHA-1）。对于对象名称的非模糊缩写，附加 :short。对于所需长度的对象名称缩写，附加 :short=<length>，其中最小长度为 MINIMUM_ABBREV。长度可能超出以确保对象名称的唯一性。

deltabase

如果给定对象存储为增量，则此扩展为该增量的对象名称。否则扩展为空对象名称（全零）。

upstream

可被视为显示引用的“上游”的本地引用名称。与上述 refname 相同的方式遵循 :short、:lstrip 和 :rstrip。此外还遵循 :track 以显示“[ahead N, behind M]”和 :trackshort 以显示简洁版本：“>”（领先）、“<”（落后）、“<>”（领先且落后）或“=”（同步）。:track 在遇到未知上游引用时还会打印“[gone]”。附加 :track,nobracket 以显示不带括号的跟踪信息（即“ahead N, behind M”）。

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

如果引用没有与其关联的跟踪信息，则无效。除 nobracket 外，所有选项互斥，但如果一起使用，则选择最后一个选项。

push

代表显示引用的 @{push} 位置的本地引用名称。与 upstream 一样遵循 :short、:lstrip、:rstrip、:track、:trackshort、:remotename 和 :remoteref 选项。如果没有配置 @{push} 引用，则生成一个空字符串。

HEAD

如果 HEAD 匹配当前引用（已检出的分支），则为 "*"，否则为 " "。

color

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

align

在 %(align:...) 和 %(end) 之间左对齐、居中对齐或右对齐内容。“align:” 后跟 width=<width> 和 position=<position>，顺序不限，用逗号分隔，其中 <position> 为 left、right 或 middle，默认为 left，<width> 为对齐后的内容总长度。为简洁起见，可以省略“width=”和/或“position=”前缀，直接使用裸露的 <width> 和 <position>。例如，%(align:<width>,<position>)。如果内容长度大于宽度，则不执行对齐。如果与 --quote 一起使用，则 %(align:...) 和 %(end) 之间的所有内容都会被引用，但如果嵌套，则只有顶层执行引用。

if

用作 %(if)…​%(then)…​%(end) 或 %(if)…​%(then)…​%(else)…​%(end)。如果在 %(if) 之后有一个带值或字符串字面量的原子，则打印 %(then) 之后的所有内容；否则，如果使用了 %(else) 原子，则打印 %(else) 之后的所有内容。我们在评估 %(then) 之前的字符串时忽略空格，这在使用 %(HEAD) 原子时很有用，该原子打印“*”或“ ”，并且我们只想将 if 条件应用于 HEAD 引用。附加“:equals=<string>”或“:notequals=<string>”以将 %(if:...) 和 %(then) 原子之间的值与给定字符串进行比较。

symref

给定符号引用所指向的引用。如果不是符号引用，则不打印任何内容。与上述 refname 相同的方式遵循 :short、:lstrip 和 :rstrip 选项。

signature

提交的 GPG 签名。

signature:grade

“G”表示有效（good）签名，“B”表示无效（bad）签名，“U”表示有效但未知有效性（unknown validity）的签名，“X”表示已过期（expired）的有效签名，“Y”表示由已过期密钥生成（expired key）的有效签名，“R”表示由已撤销密钥生成（revoked key）的有效签名，“E”表示无法检查签名（例如缺少密钥），“N”表示没有签名。

signature:signer

提交的 GPG 签名的签署者。

signature:key

提交的 GPG 签名的密钥。

signature:fingerprint

提交的 GPG 签名的指纹。

signature:primarykeyfingerprint

提交的 GPG 签名的主密钥指纹。

signature:trustlevel

提交的 GPG 签名的信任级别。可能的输出包括 ultimate, fully, marginal, never 和 undefined。

worktreepath

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

ahead-behind:<committish>

两个整数，用空格分隔，分别表示将输出引用与格式中指定的 <committish> 进行比较时，领先和落后的提交数量。

is-base:<committish>

最多在一行中，(<committish>) 将出现，表示最有可能用作产生 <committish> 的分支起点的引用。此选择使用启发式方法：选择使 <committish> 的第一父历史中提交数量最小且不在该引用的第一父历史中的引用。

例如，考虑下图显示了几个引用的第一父历史

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

这里，如果 A、B 和 C 是过滤后的引用，且格式字符串为 %(refname):%(is-base:D)，则输出将是

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

这是因为 D 的第一父历史与过滤引用的第一父历史的早期交集在 B 和 C 的共同第一父祖先处，并且平局由排序顺序中最早的引用打破。

请注意，如果 <committish> 的第一父历史不与过滤引用的第一父历史相交，则此标记将不会出现。

describe[:options]

一个人可读的名称，如 git-describe[1]；对于不可描述的提交，则为空字符串。describe 字符串后面可以跟一个冒号和一个或多个逗号分隔的选项。

tags=<bool-value>

除了只考虑带注释的标签外，还考虑轻量级标签；详情请参阅 git-describe[1] 中的相应选项。

abbrev=<number>

至少使用 <number> 个十六进制数字；详情请参阅 git-describe[1] 中的相应选项。

match=<pattern>

仅考虑匹配给定 glob(7) 模式的标签，不包括“refs/tags/”前缀；详情请参阅 git-describe[1] 中的相应选项。

exclude=<pattern>

不考虑匹配给定 glob(7) 模式的标签，不包括“refs/tags/”前缀；详情请参阅 git-describe[1] 中的相应选项。

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

对于提交和标签对象，特殊的 creatordate 和 creator 字段将对应于 committer 或 tagger 字段中适当的日期或姓名-电子邮件-日期元组，具体取决于对象类型。这些字段旨在用于处理注释和轻量级标签的混合情况。

对于标签对象，以星号（*）为前缀的 fieldname 扩展为剥离对象（peeled object）的 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:<part> 可用于提取其各个部分

contents:size

提交或标签消息的字节大小。

contents:subject

消息的第一段，通常是单行，被认为是提交或标签消息的“主题”。除了 contents:subject，字段 subject 也可以用于获取相同的结果。:sanitize 可以附加到 subject 以获得适合文件名的主题行。

contents:body

提交或标签消息中“主题”后面的其余部分。

contents:signature

标签的可选 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 选项接受的值）。如果此格式化在 --sort 键中提供，则引用将根据格式化字符串的字节值而不是底层时间戳的数值进行排序。

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

当脚本语言特定的引用生效时，顶层开启原子及其匹配的 %(end) 之间的所有内容都将根据开启原子的语义进行评估，并且只有顶层的结果会被引用。

示例

一个直接生成格式化文本的示例。显示最近的 3 个带标签的提交

#!/bin/sh

git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
Ref: %(*refname)

%(*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=%(refname)
	t=%(*objecttype)
	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=%(objecttype)
		kind="Lightweight tag"
		o=%(objectname)
		n=%(authorname)
		e=%(authoremail)
		s=%(subject)
		d=%(authordate)
		b=%(body)
	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

Its message reads as:
"
		echo "$b" | sed -e "s/^/    /"
		echo
	fi
'

eval=`git for-each-ref --shell --format="$fmt" \
	--sort='*objecttype' \
	--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)"

注意事项

请注意，磁盘上的对象大小报告是准确的，但应谨慎得出关于哪个引用或对象导致磁盘使用量的结论。未压缩的非增量对象的大小可能远大于以其为增量的对象的大小，但选择哪个对象是基准哪个是增量是任意的，并且在重新打包期间可能会更改。

另请注意，对象数据库中可能存在对象的多个副本；在这种情况下，报告哪个副本的大小或增量基准是未定义的。

注意事项

当组合多个 --contains 和 --no-contains 过滤器时，仅显示包含至少一个 --contains 提交且不包含任何 --no-contains 提交的引用。

当组合多个 --merged 和 --no-merged 过滤器时，只显示可从至少一个 --merged 提交到达且不可从任何 --no-merged 提交到达的引用。

另请参阅

git-show-ref[1]

GIT

Git[1] 套件的一部分

scroll-to-top