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>...)]描述
遍历所有匹配 <pattern> 的引用，并根据给定的 <key> 集排序后，按给定的 <format> 显示它们。如果给出了 <count>，则在显示该数量的引用后停止。<format> 中的插值可以选择性地在指定的宿主语言中作为字符串字面量引用，允许在该语言中直接求值。
选项
<pattern>...- 如果给出一个或多个 <pattern> 参数，则仅显示与至少一个模式匹配的引用，使用fnmatch(3) 或字面匹配，在后一种情况下完全匹配或从开头匹配到斜杠。--stdin- 模式列表从标准输入而不是从参数列表读取。--count=<count>- 在显示 <count> 个引用后停止。--sort=<key>- 按字段名 <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>]- 仅列出其提示不可从 <object>（未指定时为HEAD）可达的引用。--contains[=<object>]- 仅列出包含 <object>（未指定时为HEAD）的引用。--no-contains[=<object>]- 仅列出不包含 <object>（未指定时为HEAD）的引用。--ignore-case- 排序和过滤引用不区分大小写。--omit-empty- 不在格式扩展为空字符串的格式化引用后打印换行符。--exclude=<excluded-pattern>- 如果给出一个或多个--exclude选项，则仅显示不匹配任何 <excluded-pattern> 参数的引用。使用与上面 <pattern> 相同的规则进行匹配。--include-root-refs- 除常规引用外，还列出根引用（HEAD和伪引用）。--start-after=<marker>- 允许通过跳过直到并包括指定标记的引用来对输出进行分页。分页时，应注意引用可能在调用之间被删除、修改或添加。输出将仅产生按字典顺序跟在标记之后的那些引用。输出从标记字母顺序之后的第一个引用开始。不能与--sort=<key>或--stdin选项或 <pattern> 参数一起使用来限制引用。
字段名称
来自引用对象的结构化字段的各种值可用于插值到结果输出中，或用作排序键。
对于所有对象，可以使用以下名称：
refname- 引用的名称（$GIT_DIR/之后的部分）。对于非歧义的短引用名，附加:short。选项core.warnAmbiguousRefs用于选择严格的缩写模式。如果附加lstrip=<n>（rstrip=<n>），则从引用名的前面（后面）剥离 <n> 个斜杠分隔的路径组件。如果 <n> 是负数，则从指定端剥离尽可能多的路径组件以留下-<n>个路径组件。当引用没有足够的组件时，使用正 <n> 剥离结果变为空字符串，使用负 <n> 剥离结果变为完整的引用名。两者都不是错误。strip可用作lstrip的同义词。objecttype- 对象的类型（blob、tree、commit、tag）。objectsize- 对象的大小（与 'git cat-file -s' 报告的相同）。附加:disk以获取对象在磁盘上占用的大小（以字节为单位）。有关磁盘大小的说明，请参阅下面的"注意事项"部分。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)原子（打印 "*" 或 " "）且只想对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:<commit-ish>- 两个整数，用空格分隔，分别显示将输出引用与格式中指定的 <committish> 比较时领先和落后的提交数。is-base:<commit-ish>- 在最多一行中，(<commit-ish>)将出现以指示最有可能用作产生 <commit-ish> 的分支的起点的引用。此选择使用启发式方法：选择最小化 <commit-ish> 的第一父历史中不在引用的第一父历史中的提交数的引用。describe[:<option>,...]- 人类可读的名称，如 git-describe(1)；不可描述的提交为空字符串。describe字符串后可跟冒号和一个或多个逗号分隔的选项：tags=<bool-value>：不仅考虑带注释的标签，还考虑轻量级标签。abbrev=<number>：使用至少 <number> 个十六进制数字。match=<pattern>：仅考虑匹配glob(7) <pattern> 的标签。exclude=<pattern>：不考虑匹配glob(7) <pattern> 的标签。
除了上述之外，对于提交和标签对象，头字段名称（tree、parent、object、type 和 tag）可用于指定头字段中的值。字段 tree 和 parent 也可以像 objectname 一样使用修饰符 :short 和 :short=<length>。
对于提交和标签对象，特殊的 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:<part> 从中提取各种部分：
contents:size- 提交或标签消息的大小（以字节为单位）。contents:subject- 消息的第一段（通常为单行）被视为提交或标签消息的"主题"。除了contents: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 来完成。
在任何情况下，引用不适用于引用对象的字段名不会导致错误。它返回空字符串。
作为日期类型字段的特殊情况，您可以通过在日期格式名称后添加 : 来指定日期的格式（参见 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
git(1) 套件的一部分