[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
[(--sort=<key>)...] [--format=<format>] [<pattern>...]
+ [--points-at <object>] [(--merged | --no-merged) [<object>]]
+ [--contains [<object>]]
DESCRIPTION
-----------
the specified host language. This is meant to produce
a scriptlet that can directly be `eval`ed.
+--points-at <object>::
+ Only list refs which points at the given object.
+
+--merged [<object>]::
+ Only list refs whose tips are reachable from the
+ specified commit (HEAD if not specified).
+
+--no-merged [<object>]::
+ Only list refs whose tips are not reachable from the
+ specified commit (HEAD if not specified).
+
+--contains [<object>]::
+ Only list refs which contain the specified commit (HEAD if not
+ specified).
FIELD NAMES
-----------
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.
+ abbreviation mode. If `strip=<N>` is appended, strips `<N>`
+ slash-separated path components from the front of the refname
+ (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`.
+ `<N>` must be a positive integer. If a displayed ref has fewer
+ components than `<N>`, the command aborts with an error.
objecttype::
The type of the object (`blob`, `tree`, `commit`, `tag`).
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.
+ `refname` above. Additionally respects `:track` to show
+ "[ahead N, behind M]" and `:trackshort` to show the terse
+ version: ">" (ahead), "<" (behind), "<>" (ahead and behind),
+ or "=" (in sync). Has no effect if the ref does not have
+ tracking information associated with it.
+
+push::
+ The name of a local ref which represents the `@{push}` location
+ for the displayed ref. Respects `:short`, `:track`, and
+ `:trackshort` options as `upstream` does. Produces an empty
+ string if no `@{push}` ref is configured.
+
+HEAD::
+ '*' if HEAD matches current ref (the checked out branch), ' '
+ otherwise.
+
+color::
+ Change output color. Followed by `:<colorname>`, where names
+ are described in `color.branch.*`.
+
+align::
+ Left-, middle-, or right-align the content between
+ %(align:...) and %(end). The "align:" is followed by
+ `width=<width>` and `position=<position>` in any order
+ separated by a comma, where the `<position>` is either left,
+ right or middle, default being left and `<width>` is the total
+ length of the content with alignment. For brevity, the
+ "width=" and/or "position=" prefixes may be omitted, and bare
+ <width> and <position> used instead. For instance,
+ `%(align:<width>,<position>)`. If the contents length is more
+ than the width then no alignment is performed. If used with
+ `--quote` everything in between %(align:...) and %(end) is
+ quoted, but if nested then only the topmost level performs
+ quoting.
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.
+For commit and tag objects, the special `creatordate` and `creator`
+fields will correspond to the appropriate date or name-email-date tuple
+from the `committer` or `tagger` fields depending on the object type.
+These are intended for working on a mix of annotated and lightweight tags.
+
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.
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`.
+blank line. The optional GPG signature is `contents:signature`. The
+first `N` lines of the message is obtained using `contents:lines=N`.
-For sorting purposes, fields with numeric values sort in numeric
-order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
+For sorting purposes, fields with numeric values sort in numeric order
+(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
All other fields are used to sort in their byte-value order.
+There is also an option to sort by versions, this can be done by using
+the fieldname `version:refname` or its alias `v:refname`.
+
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)`.
+the date by adding `:` followed by date format name (see the
+values the `--date` option to linkgit:git-rev-list[1] takes).
EXAMPLES
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>.
+SEE ALSO
+--------
+linkgit:git-show-ref[1]
GIT
---
projects / platform / upstream / git.git / blobdiff