summaryrefslogtreecommitdiff
path: root/Documentation/git-for-each-ref.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-for-each-ref.txt')
-rw-r--r--Documentation/git-for-each-ref.txt121
1 files changed, 105 insertions, 16 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 2ae2478..c1dd12b 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -9,10 +9,12 @@ SYNOPSIS
--------
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
- [(--sort=<key>)...] [--format=<format>] [<pattern>...]
+ [(--sort=<key>)...] [--format=<format>]
+ [--include-root-refs] [ --stdin | <pattern>... ]
[--points-at=<object>]
[--merged[=<object>]] [--no-merged[=<object>]]
[--contains[=<object>]] [--no-contains[=<object>]]
+ [--exclude=<pattern> ...]
DESCRIPTION
-----------
@@ -32,6 +34,10 @@ OPTIONS
literally, in the latter case matching completely or from the
beginning up to a slash.
+--stdin::
+ If `--stdin` is supplied, then the list of patterns is read from
+ standard input instead of from the argument list.
+
--count=<count>::
By default the command shows all refs that match
`<pattern>`. This option makes it stop after showing
@@ -45,17 +51,14 @@ OPTIONS
key.
--format=<format>::
- A string that interpolates `%(fieldname)` from a ref being shown
- and the object it points at. If `fieldname`
- is prefixed with an asterisk (`*`) and the ref points
- at a tag object, use the value for the field in the object
- which the tag object refers to (instead of the field in the tag object).
- When unspecified, `<format>` defaults to
- `%(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).
+ A string that interpolates `%(fieldname)` from a ref being shown and
+ the object it points at. In addition, the string literal `%%`
+ renders as `%` and `%xx` - where `xx` are hex digits - renders as
+ the character with hex code `xx`. For example, `%00` interpolates to
+ `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
++
+When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
+TAB %(refname)`.
--color[=<when>]::
Respect any colors specified in the `--format` option. The
@@ -93,6 +96,18 @@ OPTIONS
--ignore-case::
Sorting and filtering refs are case insensitive.
+--omit-empty::
+ Do not print a newline after formatted refs where the format expands
+ to the empty string.
+
+--exclude=<pattern>::
+ If one or more patterns are given, only refs which do not match
+ any excluded pattern(s) are shown. Matching is done using the
+ same rules as `<pattern>` above.
+
+--include-root-refs::
+ List root refs (HEAD and pseudorefs) apart from regular refs.
+
FIELD NAMES
-----------
@@ -212,11 +227,66 @@ symref::
`:lstrip` and `:rstrip` options in the same way as `refname`
above.
+signature::
+ The GPG signature of a commit.
+
+signature:grade::
+ Show "G" for a good (valid) signature, "B" for a bad
+ signature, "U" for a good signature with unknown validity, "X"
+ for a good signature that has expired, "Y" for a good
+ signature made by an expired key, "R" for a good signature
+ made by a revoked key, "E" if the signature cannot be
+ checked (e.g. missing key) and "N" for no signature.
+
+signature:signer::
+ The signer of the GPG signature of a commit.
+
+signature:key::
+ The key of the GPG signature of a commit.
+
+signature:fingerprint::
+ The fingerprint of the GPG signature of a commit.
+
+signature:primarykeyfingerprint::
+ The primary key fingerprint of the GPG signature of a commit.
+
+signature:trustlevel::
+ The trust level of the GPG signature of a commit. Possible
+ outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.
+
worktreepath::
The absolute path to the worktree in which the ref is checked
out, if it is checked out in any linked worktree. Empty string
otherwise.
+ahead-behind:<committish>::
+ Two integers, separated by a space, demonstrating the number of
+ commits ahead and behind, respectively, when comparing the output
+ ref to the `<committish>` specified in the format.
+
+describe[:options]::
+ A human-readable name, like linkgit:git-describe[1];
+ empty string for undescribable commits. The `describe` string may
+ be followed by a colon and one or more comma-separated options.
++
+--
+tags=<bool-value>;;
+ Instead of only considering annotated tags, consider
+ lightweight tags as well; see the corresponding option in
+ linkgit:git-describe[1] for details.
+abbrev=<number>;;
+ Use at least <number> hexadecimal digits; see the corresponding
+ option in linkgit:git-describe[1] for details.
+match=<pattern>;;
+ Only consider tags matching the given `glob(7)` pattern,
+ excluding the "refs/tags/" prefix; see the corresponding option
+ in linkgit:git-describe[1] for details.
+exclude=<pattern>;;
+ Do not consider tags matching the given `glob(7)` pattern,
+ excluding the "refs/tags/" prefix; see the corresponding option
+ in linkgit:git-describe[1] for details.
+--
+
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.
@@ -228,12 +298,29 @@ 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.
+For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to
+the `fieldname` value of the peeled object, rather than that of the tag
+object itself.
+
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. For email fields (`authoremail`,
`committeremail` and `taggeremail`), `:trim` can be appended to get the email
without angle brackets, and `:localpart` to get the part before the `@` symbol
-out of the trimmed email.
+out of the trimmed email. In addition to these, the `:mailmap` option and the
+corresponding `:mailmap,trim` and `:mailmap,localpart` can be used (order does
+not matter) to get values of the name and email according to the .mailmap file
+or according to the file set in the mailmap.file or mailmap.blob configuration
+variable (see linkgit:gitmailmap[5]).
+
+The raw data in an object is `raw`.
+
+raw:size::
+ The raw data size of the object.
+
+Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
+because such language may not support arbitrary binary data in their string
+variable type.
The message in a commit or a tag object is `contents`, from which
`contents:<part>` can be used to extract various parts out of:
@@ -275,9 +362,11 @@ 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 `:` followed by date format name (see the
-values the `--date` option to linkgit:git-rev-list[1] takes).
+As a special case for the date-type fields, you may specify a format for the
+date by adding `:` followed by date format name (see the values the `--date`
+option to linkgit:git-rev-list[1] takes). If this formatting is provided in
+a `--sort` key, references will be sorted according to the byte-value of the
+formatted string rather than the numeric value of the underlying timestamp.
Some atoms like %(align) and %(if) always require a matching %(end).
We call them "opening atoms" and sometimes denote them as %($open).