English ▾ 主题 ▾ 最新版本 ▾ git-for-each-ref 最后更新于 2.47.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 (NUL)，%09 插入为 \t (TAB)，%0a 插入为 \n (LF)。

未指定时，<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>)，则从 refname 的前面（后面）剥离 <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

如果给定对象存储为增量，则这会扩展为该对象的增量基的对象名称。 否则，它将扩展为 null 对象名称（所有零）。

upstream

本地引用的名称，可以被认为是显示引用的“上游”。与上面的 refname 相同，遵守 :short、:lstrip 和 :rstrip。此外，还遵守 :track 以显示“[领先 N，落后 M]”，以及 :trackshort 以显示简短版本：“>”（领先），“<”（落后），“<>”（领先和落后），或“=”（同步）。每当遇到未知的上游引用时，:track 还会打印“[gone]”。附加 :track,nobracket 以显示不带括号的跟踪信息（即“领先 N，落后 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) 原子时非常有用，该原子会打印 "*" 或 " "，并且我们只想对 *HEAD* 引用应用 _if_ 条件。附加 ":equals=<string>" 或 ":notequals=<string>" 以比较 %(if:…​) 和 %(then) 原子之间的值与给定字符串。

symref

给定符号引用指向的引用。如果不是符号引用，则不打印任何内容。与上面的 refname 相同，遵守 :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 和 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] 中的相应选项。

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

对于提交和标签对象，特殊的 creatordate 和 creator 字段将根据对象类型对应于 committer 或 tagger 字段中的相应日期或 name-email-date 元组。这些旨在用于处理带注释和轻量级标签的混合。

对于标签对象，以星号 (*) 开头的 fieldname 会扩展到剥离对象的 fieldname 值，而不是标签对象本身的值。

具有 name-email-date 元组作为其值的字段（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

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

contents:body

提交或标签消息中，接在“主题”之后的剩余部分。

contents:signature

标签的可选 GPG 签名。

contents:lines=N

消息的前 N 行。

此外，通过 git-interpret-trailers[1] 解释的尾部（trailers）可以作为 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 的用法。 列出所有头的prefix

#!/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