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

名称

git-for-each-ref - 输出每个 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>...)]

描述

遍历所有与 <pattern> 匹配的 ref，并根据给定的 <format> 显示它们，在根据给定的 <key> 集合排序后。如果给定了 <count>，则在显示完该数量的 ref 后停止。<format> 中的插值值可以选择性地以指定宿主语言的字符串字面量形式引用，从而允许在该语言中直接求值。

选项

<pattern>...

如果提供了一个或多个 <pattern> 参数，则只显示与至少一个模式匹配的 ref，匹配可以是使用 fnmatch(3) 或字面量匹配，后一种情况则完全匹配或从开头匹配到斜杠。

--stdin

模式列表从标准输入读取，而不是从参数列表中读取。

--count=<count>

显示 <count> 个 ref 后停止。

--sort=<key>

按字段名称 <key> 排序。前缀 - 表示按值降序排序。未指定时，默认为 refname。您可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键将成为主键。

--format[=<format>]

一个字符串，它将来自正在显示的 ref 及其指向对象的 %(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>

只列出指向给定对象的 ref。

--merged[=<object>]

仅列出其提示（tips）可从指定提交（如果未指定则为 HEAD）可达的 ref。

--no-merged[=<object>]

仅列出其提示（tips）不可从<object>（如果未指定则为 HEAD）可达的 ref。

--contains[=<object>]

仅列出包含<object>（如果未指定则为 HEAD）的 ref。

--no-contains[=<object>]

仅列出不包含<object>（如果未指定则为 HEAD）的 ref。

--ignore-case

排序和过滤 ref 时不区分大小写。

--omit-empty

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

--exclude=<excluded-pattern>

如果提供了一个或多个 --exclude 选项，则只显示不匹配任何 <excluded-pattern> 参数的 ref。匹配使用与上面 <pattern> 相同的规则进行。

--include-root-refs

列出根 ref（HEAD 和伪 ref），与普通 ref 分开。

--start-after=<marker>

允许通过跳过直到并包括指定标记的引用来分页输出。在分页时，应注意引用可能在调用之间被删除、修改或添加。输出将仅显示那些在字母顺序上跟随标记的引用。输出从在标记之后字母顺序上出现的第一个引用开始。不能与 --sort=<key> 或 --stdin 选项，或用于限制 ref 的 <pattern> 参数一起使用。

字段名称

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

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

refname

ref 的名称（$GIT_DIR/ 之后的ส่วน）。对于 ref 的非歧义短名称，追加 :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）。当 ref 没有足够的组件时，如果用正数 <n> 剥离，结果将为空字符串；如果用负数 <N> 剥离，则结果是完整的 refname。两者都不是错误。

strip 可以用作 lstrip 的同义词。

objecttype

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

objectsize

对象的大小（与 git cat-file -s 报告的大小相同）。追加 :disk 以获取对象在磁盘上占用的字节数。有关磁盘大小的说明，请参见下文的 注意事项 部分。

objectname

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

deltabase

这会扩展为给定对象的 delta 基对象的名称（如果它被存储为 delta）。否则，它会扩展为 null 对象名称（全零）。

upstream

可以被认为是相对于显示 ref 的“上游”的本地 ref 的名称。它以与 refname 相同的方式响应 :short、:lstrip 和 :rstrip。此外，它响应 :track 以显示 "[ahead N, behind M]"，以及 :trackshort 以显示简洁版本：">"（落后）、"<"（超前）、"<>"（同时落后和超前）或 "="（同步）。当遇到未知上游 ref 时，:track 还会打印 "[gone]"。 追加 :track,nobracket 可在不带括号的情况下显示跟踪信息（即 "ahead N, behind M"）。

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

如果 ref 没有与之关联的跟踪信息，则此选项无效。除 nobracket 外，所有选项都是互斥的，但如果一起使用，则最后一个选项生效。

push

代表显示 ref 的 @{push} 位置的本地 ref 的名称。它以与 upstream 相同的方式响应 :short、:lstrip、:rstrip、:track、:trackshort、:remotename 和 :remoteref 选项。如果未配置 @{push} ref，则生成空字符串。

HEAD

如果 HEAD 匹配当前 ref（已检出的分支），则为“*”，否则为“ ”。

color

更改输出颜色。后面跟着 :<colorname>，其中颜色名称在 git-config[1] 的“CONFIGURATION FILE”部分中描述。例如，%(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 ref 应用 if 条件。追加 ":equals=<string>" 或 ":notequals=<string>" 来比较 %(if:...) 和 %(then) 原子与给定字符串之间的值。

symref

给定的符号 ref 指向的 ref。如果不是符号 ref，则不打印任何内容。它以与 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

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

ahead-behind:<commit-ish>

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

is-base:<commit-ish>

最多在一行中，将出现 (<commit-ish>) 来指示最有可能用作产生 <commit-ish> 的分支起点的 ref。此选择是使用启发式方法做出的：选择最小化 <commit-ish> 的第一父提交历史中不在 ref 的第一父提交历史中的提交数量的 ref。

例如，考虑以下几个 ref 的第一父提交历史图

*--*--*--*--*--* 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 的第一父提交历史与过滤后的 ref 的第一父提交历史最早的交集在 B 和 C 的共同第一父提交祖先处，并且平局是通过排序顺序中最早的 ref 来打破的。

请注意，如果 <commit-ish> 的第一父提交历史与过滤后的 ref 的第一父提交历史不相交，则此标记将不会出现。

describe[:<option>,...]

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

tags=<bool-value>

除了仅考虑注解标签外，还考虑轻量级标签；有关详细信息，请参阅 git-describe[1] 中相应的选项。

abbrev=<number>

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

match=<pattern>

仅考虑匹配 glob(7) <pattern> 的标签，排除 refs/tags/ 前缀；有关详细信息，请参阅 git-describe[1] 中相应的选项。

exclude=<pattern>

不考虑匹配 glob(7) <pattern> 的标签，排除 refs/tags/ 前缀；有关详细信息，请参阅 git-describe[1] 中相应的选项。

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

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

对于标签对象，前面带有星号（*）的 fieldname 会扩展到剥离后的对象（peeled object）的 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:<part> 提取各种部分

contents:size

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

contents:subject

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

contents:body

提交或标签消息中位于“主题”之后的部分。

contents:signature

标签的可选 GPG 签名。

contents:lines=<n>

消息的前 <n> 行。

此外，由 git-interpret-trailers[1] 解释的尾部信息可以通过 trailers[:<option>,...]（或使用历史别名 contents:trailers[:<option>,...]）获得。对于有效的 <option> 值，请参阅 git-log[1] 的 trailers 部分。

为了排序目的，具有数字值的字段按数字顺序排序（objectsize、authordate、committerdate、creatordate、taggerdate）。所有其他字段用于按其字节值顺序排序。

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

在任何情况下，指向 ref 所引用的对象不适用的字段名称都不会导致错误。它将返回一个空字符串。

作为日期类型字段的特殊情况，您可以通过添加 : 后跟日期格式名称（请参阅 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 的用法。列出所有 heads 的前缀

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

注意事项

请注意，对象在磁盘上的大小被准确报告，但在推断哪些 ref 或对象导致磁盘使用时应谨慎。已打包的非 delta 对象的大小可能远大于对其进行 delta 的对象的大小，但哪个对象是基准对象，哪个是 delta 对象，是任意的，并且在重新打包期间可能会发生变化。

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

注意事项

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

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

另请参阅

git-show-ref[1]

GIT

Git[1] 套件的一部分