NAME¶

git-for-each-ref - Output information on each ref

SYNOPSIS¶

git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]


                   [(--sort=<key>)...] [--format=<format>] [<pattern>...]

DESCRIPTION¶

Iterate over all refs that match <pattern> and show them according to the given <format>, after sorting them according to the given set of <key>. If <count> is given, stop after showing that many refs. The interpolated values in <format> can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language.

OPTIONS¶

<count>

<key>

<format>

<pattern>...

--shell, --perl, --python, --tcl

FIELD NAMES¶

Various values from structured fields in referenced objects can be used to interpolate into the resulting output, or as sort keys.

For all objects, the following names can be used:

refname

objecttype

objectsize

objectname

upstream

In addition to the above, for commit and tag objects, the header field names (tree, parent, object, type, and tag) can be used to specify the value in the header field.

Fields that have name-email-date tuple as its value (author, committer, and tagger) can be suffixed with name, email, and date to extract the named component.

The complete message in a commit and tag object is contents. Its first line is contents:subject, where subject is the concatenation of all lines of the commit message up to the first blank line. The next line is contents:body, where body is all of the lines after the first blank line. Finally, the optional GPG signature is contents:signature.

For sorting purposes, fields with numeric values sort in numeric order (objectsize, authordate, committerdate, taggerdate). All other fields are used to sort in their byte-value order.

In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead.

As a special case for the date-type fields, you may specify a format for the date by adding one of :default, :relative, :short, :local, :iso8601, :rfc2822 or :raw to the end of the fieldname; e.g. %(taggerdate:relative).

EXAMPLES¶

An example directly producing formatted text. Show the most recent 3 tagged commits:

#!/bin/sh
git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
Ref: %(*refname)
%(*body)
' 'refs/tags'

A simple example showing the use of shell eval on the output, demonstrating the use of --shell. List the prefixes of all heads:

#!/bin/sh
git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
while read entry
do


        eval "$entry"


        echo `dirname $ref`
done

A bit more elaborate report on tags, demonstrating that the format may be an entire script:

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

AUTHOR¶

Written by Junio C Hamano <gitster@pobox.com[1]>.

DOCUMENTATION¶

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org[2]>.

GIT¶

Part of the git(1) suite

NOTES¶

1.

gitster@pobox.com

2.

git@vger.kernel.org