--------
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
- [
--sort=<key>]\* [--format=<format>] [<pattern>...]
+ [
(--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 `<max>` is given, stop after
+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.
<pattern>...::
If one or more patterns are given, only refs are shown that
- match againt at least one pattern, either using fnmatch(3) or
+ 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.
refname::
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).
+ For a non-ambiguous abbreviation of the object name append `:short`.
+
+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
`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`.
+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`).
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.
+`:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g.
`%(taggerdate:relative)`.
--------
An example directly producing formatted text. Show the most recent
-3 tagged commits::
+3 tagged commits:
------------
#!/bin/sh
A simple example showing the use of shell eval on the output,
-demonstrating the use of --shell. List the prefixes of all heads::
+demonstrating the use of --shell. List the prefixes of all heads:
------------
#!/bin/sh
A bit more elaborate report on tags, demonstrating that the format
-may be an entire script::
+may be an entire script:
------------
#!/bin/sh
refs/tags`
eval "$eval"
------------
+
+Author
+------
+Written by Junio C Hamano <gitster@pobox.com>.
+
+Documentation
+-------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite