Merge branch 'jc/grep-untracked-exclude'

[git.git] / Documentation / git-for-each-ref.txt

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index eae6c0e7bcad5708442d10a7bc73eac3ec90bcbd..c872b883ba25144457eccb9967bc68003a3332ea 100644 (file)
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -9,14 +9,14 @@ SYNOPSIS
 --------
 [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.
@@ -74,15 +74,24 @@ For all objects, the following names can be used:
 
 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
@@ -92,9 +101,10 @@ 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 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`, the remaining lines
+are `contents:body` and the optional GPG signature
+is `contents:signature`.
 
 For sorting purposes, fields with numeric values sort in numeric
 order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
@@ -114,7 +124,7 @@ EXAMPLES
 --------
 
 An example directly producing formatted text.  Show the most recent
-3 tagged commits::
+3 tagged commits:
 
 ------------
 #!/bin/sh
@@ -131,7 +141,7 @@ Ref: %(*refname)
 
 
 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
 
@@ -145,7 +155,7 @@ done
 
 
 A bit more elaborate report on tags, demonstrating that the format
-may be an entire script::
+may be an entire script:
 ------------
 #!/bin/sh
 
@@ -195,3 +205,15 @@ eval=`git for-each-ref --shell --format="$fmt" \
        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