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>]]

描述

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

选项

<pattern>…​

如果给出了一个或多个模式，则只显示与至少一个模式相匹配的引用，或者使用fnmatch（3）或从字面上匹配，在后一种情况下完全匹配或从开始直到斜杠。

--count=<count>

默认情况下，该命令显示所有匹配的参考<pattern>。该选项会在显示多个参考文件后停止。

--sort=<key>

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

--format=<format>

一个字符串，%(fieldname)从显示的ref和它指向的对象中插入。如果fieldname前缀为asterisk（*）并且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)占位符的字符串将被引用为适用于指定主机语言的字符串文字。这是为了产生一个可以直接eval编辑的scriptlet 。

--points-at=<object>

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

--merged=<object>

只列出其提示可从指定提交（HEAD，如果未指定）可访问的ref，与不兼容--no-merged。

--no-merged=<object>

只列出其提示无法从指定提交（HEAD，如果未指定）到达的ref，与之不兼容--merged。

--contains=<object>

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

--no-contains=<object>

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

--ignore-case

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

字段名称

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

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

refname

参考名称（$ GIT_DIR /之后的部分）。对于ref的append不含糊不清的短名称:short。选项core.warnAmbiguousRefs用于选择严格的缩写模式。如果lstrip=<N>（rstrip=<N>）将被附加，条<N>斜线分隔径分量从refname的前部（背面）（例如%(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可以作为synomym来使用lstrip。

objecttype

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

objectsize

对象的大小（与git cat-file -s报告相同）。

objectname

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

upstream

显示的参考文献中可以考虑为“上游”的本地参考文献的名称。尊重:short，:lstrip并:rstrip以与refname上述相同的方式。此外，:track还要显示“前N，后M”并:trackshort显示简短版本：“>”（前面），“<”（后面），“<>”（前后）或“=”（同步） 。:track当遇到未知的上游参考时也打印“消失”。追加:track,nobracket显示无括号的追踪信息（即“前N，后M”）。如果裁判没有跟踪信息，则不起作用。所有选项除外nobracket是互斥的，但如果一起使用，则选择最后一个选项。

push

代表@{push}所显示文献位置的本地参考文献的名称。尊重:short，:lstrip，:rstrip，:track，和:trackshort选项upstream呢。如果未@{push}配置ref，则生成一个空字符串。

HEAD

* 如果HEAD与当前参考（已签出的分支）匹配，则返回“否则”。

color

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

align

将％（align：...）和％（end）之间的内容左对齐，中对齐或右对齐。该“对齐”之后width=<width>和position=<position>在用逗号，其中所分离的任何次序<position>要么左，右或中间，被留默认和<width>与对准的内容的总长度。为简洁起见，可以省略“width =”和/或“position =”前缀，而使用<width>和<位置>。例如，%(align:<width>,<position>)。如果内容长度大于宽度，则不执行对齐。如果使用--quote％（align：...）和％（end）之间的所有内容进行引用，但是如果嵌套，则只有最顶层执行引用。

if

用作％（if）...％（then）...％（end）或％（if）...％（then）...％（else）...％（end）。如果在％（if）之后有值或字符串的原子，则％（then）后面的所有内容都将被打印，否则如果使用％（else）原子，则打印％（else）后的所有内容。当在％（then）之前评估字符串时，我们会忽略空格，当我们使用打印“*”或“”的％（HEAD）原子时，这很有用，我们只想将该if条件应用于HEADref。追加“：等于= <字符串>”或“：notequals = <字符串>”以比较％（如果......）和％（然后）原子与给定字符串之间的值。

symref

给定的符号ref引用的ref。如果不是符号参考，则不会打印任何内容。尊重:short，:lstrip并:rstrip在为同样的方式选择refname以上。

除了上述之外，用于提交和标签对象，报头字段名（tree，parent，object，type，和tag）可以被用来指定在报头字段中的值。

对于提交和标记对象，特殊字段creatordate和creator字段将根据对象类型与committer或tagger字段中的相应日期或名称 - 电子邮件日期元组相对应。这些旨在用于混合使用注释和轻量级标签。

有名字的电子邮件最新的元组作为其值的字段（author，committer，和tagger）可以与后缀name，email以及date提取命名组件。

提交和标签对象中的完整消息是contents。它的第一行是contents:subject，主题是提交消息的所有行连接到第一个空白行。接下来的一行是contents:body，body是第一个空白行之后的所有行。可选的GPG签名是contents:signature。N消息的第一行是使用获得的contents:lines=N。此外，由git-interpret-trailers [1]解释的预告片也可以获得contents:trailers。

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

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

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

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

像％（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)"