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.txt52
1 files changed, 39 insertions, 13 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 6dcd39f6f6..2962f85a50 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -11,7 +11,7 @@ SYNOPSIS
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
[(--sort=<key>)...] [--format=<format>] [<pattern>...]
[--points-at=<object>]
- (--merged[=<object>] | --no-merged[=<object>])
+ [--merged[=<object>]] [--no-merged[=<object>]]
[--contains[=<object>]] [--no-contains[=<object>]]
DESCRIPTION
@@ -76,13 +76,11 @@ OPTIONS
--merged[=<object>]::
Only list refs whose tips are reachable from the
- specified commit (HEAD if not specified),
- incompatible with `--no-merged`.
+ 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),
- incompatible with `--merged`.
+ specified commit (HEAD if not specified).
--contains[=<object>]::
Only list refs which contain the specified commit (HEAD if not
@@ -222,6 +220,8 @@ worktreepath::
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 `tree` and `parent` can also be used with modifier `:short` and
+`:short=<length>` just like `objectname`.
For commit and tag objects, the special `creatordate` and `creator`
fields will correspond to the appropriate date or name-email-date tuple
@@ -230,14 +230,35 @@ 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.
-
-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. The optional GPG signature is `contents:signature`. The
-first `N` lines of the message is obtained using `contents:lines=N`.
+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.
+
+The message in a commit or a tag object is `contents`, from which
+`contents:<part>` can be used to extract various parts out of:
+
+contents:size::
+ The size in bytes of the commit or tag message.
+
+contents:subject::
+ The first paragraph of the message, which typically is a
+ single line, is taken as the "subject" of the commit or the
+ tag message.
+ Instead of `contents:subject`, field `subject` can also be used to
+ obtain same results. `:sanitize` can be appended to `subject` for
+ subject line suitable for filename.
+
+contents:body::
+ The remainder of the commit or the tag message that follows
+ the "subject".
+
+contents:signature::
+ The optional GPG signature of the tag.
+
+contents:lines=N::
+ The first `N` lines of the message.
+
Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
are obtained as `trailers` (or by using the historical alias
`contents:trailers`). Non-trailer lines from the trailer block can be omitted
@@ -385,6 +406,11 @@ Note also that multiple copies of an object may be present in the object
database; in this case, it is undefined which copy's size or delta base
will be reported.
+NOTES
+-----
+
+include::ref-reachability-filters.txt[]
+
SEE ALSO
--------
linkgit:git-show-ref[1]