SYNOPSIS
--------
-'git-for-each-ref' [--count=<count>]* [--shell|--perl|--python] [--sort=<key>]* [--format=<format>] [<pattern>]
+[verse]
+'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>`s. If `<max>` is given, stop after
-showing that many refs. The interporated values in `<format>`
+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.
+host language allowing their direct evaluation in that language.
OPTIONS
-------
<key>::
A field name to sort on. Prefix `-` to sort in
descending order of the value. When unspecified,
- `refname` is used. More than one sort keys can be
- given.
+ `refname` is used. You may use the --sort=<key> option
+ multiple times, in which case the last key becomes the primary
+ key.
<format>::
A string that interpolates `%(fieldname)` from the
is prefixed with an asterisk (`*`) and the ref points
at a tag object, the value for the field in the object
tag refers is used. When unspecified, defaults to
- `%(refname)`.
-
-<pattern>::
- If given, the name of the ref is matched against this
- using fnmatch(3). Refs that do not match the pattern
- are not shown.
-
---shell, --perl, --python::
+ `%(objectname) SPC %(objecttype) TAB %(refname)`.
+ It also interpolates `%%` to `%`, and `%xx` where `xx`
+ are hex digits interpolates to character with hex code
+ `xx`; for example `%00` interpolates to `\0` (NUL),
+ `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
+
+<pattern>...::
+ If one or more patterns are given, only refs are shown that
+ match against at least one pattern, either using fnmatch(3) or
+ literally, in the latter case matching completely or from the
+ beginning up to a slash.
+
+--shell::
+--perl::
+--python::
+--tcl::
If given, strings that substitute `%(fieldname)`
placeholders are quoted as string literals suitable for
the specified host language. This is meant to produce
For all objects, the following names can be used:
refname::
- The name of the ref (the part after $GIT_DIR/refs/).
+ The name of the ref (the part after $GIT_DIR/).
+ For a non-ambiguous short name of the ref append `:short`.
+ The option core.warnAmbiguousRefs is used to select the strict
+ abbreviation mode.
objecttype::
The type of the object (`blob`, `tree`, `commit`, `tag`).
objectsize::
- The size of the object (the same as `git-cat-file -s` reports).
+ The size of the object (the same as 'git cat-file -s' reports).
objectname::
The object name (aka SHA-1).
+upstream::
+ The name of a local ref which can be considered ``upstream''
+ from the displayed ref. Respects `:short` in the same way as
+ `refname` above.
+
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.
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
--------
-Show the most recent 3 tagged commits::
+An example directly producing formatted text. Show the most recent
+3 tagged commits::
------------
#!/bin/sh
-git-for-each-ref --count=3 --sort='-*authordate' \
+git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
' 'refs/tags'
------------
-A bit more elaborate report on 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
fi
'
-eval=`git-for-each-ref -s --format="$fmt" \
+eval=`git for-each-ref --shell --format="$fmt" \
--sort='*objecttype' \
--sort=-taggerdate \
refs/tags`