原文： https://git-scm.com/docs/git-for-each-ref

git-for-each-ref - 每个参考的输出信息

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

迭代匹配<pattern>的所有引用并根据给定的<format>显示它们，然后根据给定的<key>集对它们进行排序。如果给出<count>，则在显示许多参考后停止。 <format>中的插值可以选择引用指定主语言中的字符串文字，允许直接用该语言进行评估。

 <pattern>…​ 

如果给出一个或多个模式，则仅显示与至少一个模式匹配的refs，使用fnmatch（3）或字面意思，在后一种情况下完全匹配或从开头到斜线。

 --count=<count> 

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

 --sort=<key> 

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

 --format=<format> 

一个字符串，用于插入显示的ref及其指向的对象的%(fieldname)。如果fieldname以星号（*为前缀）并且ref指向标记对象，请使用标记对象引用的对象中的字段值（而不是标记对象中的字段）。未指定时，<format>默认为%(objectname) SPC %(objecttype) TAB %(refname)。它还将%%插入到%，%xx其中xx是十六进制数字，插入到十六进制代码xx的字符中;例如%00内插到\0（NUL），%09到\t（TAB）和%0a到\n（LF）。

 --color[=<when>] 

尊重--format选项中指定的任何颜色。 <when>字段必须是always，never或auto之一（如果<when>不存在，则表现得好像always一样）。

 --shell 

 --perl 

 --python 

 --tcl 

如果给定，则替换%(fieldname)占位符的字符串将被引用为适合指定宿主语言的字符串文字。这是为了生成一个可以直接“评估”的scriptlet。

 --points-at=<object> 

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

 --merged[=<object>] 

仅列出可从指定提交（HEAD，如果未指定）可访问的引用的refs，与--no-merged不兼容。

 --no-merged[=<object>] 

仅列出其指针无法从指定的提交（如果未指定，则为HEAD）可访问的refs，与--merged不兼容。

 --contains[=<object>] 

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

 --no-contains[=<object>] 

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

 --ignore-case 

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

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

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

 refname 

ref的名称（$ GIT_DIR /之后的部分）。对于ref附加: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/tags/foo COD17]）。当ref没有足够的组件时，如果使用正< N>进行剥离，则结果将变为空字符串，或者如果使用负< N>进行剥离，则结果将变为完整的refname。两者都不是错误。

strip可以用作lstrip的同义词。

 objecttype 

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

 objectsize 

对象的大小（与 git cat-file -s 报告相同）。附加:disk以获取对象占用磁盘的大小（以字节为单位）。请参阅下面CAVEATS部分中有关磁盘大小的说明。

 objectname 

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

 deltabase 

如果将其存储为delta，则会扩展为给定对象的delta base的对象名称。否则它会扩展为空对象名称（全为零）。

 upstream 

本地引用的名称，可以被视为显示引用的“上游”。以与上述refname相同的方式尊重:short，:lstrip和:rstrip。另外尊重:track以显示“[前N，后M]”和:trackshort以显示简洁版本：“>” （提前），“<” （后面），“<>” （前后）或“=”（同步）。每当遇到未知的上游引用时，:track也会打印“[gone]”。附加:track,nobracket以显示没有括号的跟踪信息（即“在N之前，在M之后”）。

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

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

 push 

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

 HEAD 

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

 color 

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

 align 

左，中，或右对齐％（对齐：...）和％（结束）之间的内容。 “对齐：”之后是以逗号分隔的任何顺序的width=<width>和position=<position>，其中<position>是左，右或中间，默认为左，<width>是内容的总长度对齐。为简洁起见，可以省略“width =”和/或“position =”前缀，并且< width>和< position>用来代替。例如，%(align:<width>,<position>)。如果内容长度大于宽度，则不执行对齐。如果与--quote一起使用，则引用％（align：...）和％（end）之间的所有内容，但如果嵌套，则只有最顶层执行引用。

 if 

用作％（if）...％（然后）...％（结束）或％（如果）...％（然后）...％（否则）...％（结束）。如果在％（if）之后有一个带有值或字符串文字的原子，则打印％（then）之后的所有内容，否则如果使用％（else）原子，则打印％（else）之后的所有内容。我们在％（然后）之前评估字符串时忽略空格，当我们使用打印“*”或“”的％（HEAD）原子并且我们想要仅在条件下应用_时这很有用 HEAD 参考。附加“：equals =< string>”或“：notequals =< string>”比较％（if：...）和％（then）原子与给定字符串之间的值。_

 symref 

给定符号ref引用的引用。如果不是符号引用，则不打印任何内容。以与refname相同的方式尊重:short，:lstrip和:rstrip选项。

除上述内容外，对于提交和标记对象，标题字段名称（tree，parent，object，type和tag）可用于指定标题字段中的值。

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

将name-email-date元组作为其值（author，committer和tagger）的字段可以后缀name，email和date以提取指定的组件。

提交和标记对象中的完整消息是contents。它的第一行是contents:subject，其中subject是提交消息的所有行的连接，直到第一个空行。下一行是contents:body，其中body是第一个空白行之后的所有行。可选的GPG签名是contents:signature。使用contents:lines=N获得消息的第一N行。另外，由 git-interpre-trailers [1] 解释的预告片作为trailers（或通过使用历史别名contents:trailers）获得。使用trailers:only可以省略拖车块中的非拖车线。可以从预告片中删除空格连续，以便每个预告片单独出现在一行上，其全部内容为trailers:unfold。两者可以一起用作trailers:unfold,only。

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

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

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

作为日期类型字段的特殊情况，您可以通过添加:后跟日期格式名称来指定日期的格式（请参阅 git-rev-list [1]的--date选项的值需要）。

像％（对齐）和％（如果）这样的原子总是需要匹配的％（结束）。我们称它们为“开放原子”，有时将它们表示为％（$ open）。

当特定于脚本语言的引用生效时，顶级开放原子与其匹配的％（结束）之间的所有内容都根据开放原子的语义进行评估，并且仅引用顶级开放原子的结果。

直接生成格式化文本的示例。显示最近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）...％（然后）...％（else）...％（end）的用法的示例。这为当前分支添加星号前缀。

git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/

显示％（if）...％（然后）...％（结束）的用法的示例。这将打印authorname（如果存在）。

git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"

请注意，磁盘上对象的大小是准确报告的，但应该注意得出哪些引用或对象负责磁盘使用的结论。打包的非delta对象的大小可能远大于对其增量的对象的大小，但是选择哪个对象是基础并且delta是任意的并且在重新打包期间可能会发生变化。

还要注意，对象的多个副本可能存在于对象数据库中;在这种情况下，未定义将报告哪个副本的大小或增量基数。

git-show-ref [1]

部分 git [1] 套件