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 first line of the message in a commit and tag object is subject, the remaining lines are body. The whole message is contents.

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 or :rfc2822 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"