X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-for-each-ref.txt;h=f49b0d944c613a9d5f4a6c5b6713d5c556f0390e;hb=9debc3241b5d54891600c839b4df4f48b2daa60c;hp=6649f795e8714d9f084a5f4db18bf3a1d405d46a;hpb=244a0ae114824c8ca29bdc2148b98caaae39cac2;p=git.git

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 6649f795e..f49b0d944 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -7,17 +7,17 @@ git-for-each-ref - Output information on each ref
 
 SYNOPSIS
 --------
-'git-for-each-ref' [--count=<count>]* [--shell|--perl|--python] [--sort=<key>]* [--format=<format>] [<pattern>]
+'git-for-each-ref' [--count=<count>]\* [--shell|--perl|--python|--tcl] [--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>`s.  If `<max>` is given, stop after
-showing that many refs.  The interporated values in `<format>`
+to the given set of `<key>`.  If `<max>` 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.
+host language allowing their direct evaluation in that language.
 
 OPTIONS
 -------
@@ -38,14 +38,18 @@ OPTIONS
 	is prefixed with an asterisk (`*`) and the ref points
 	at a tag object, the value for the field in the object
 	tag refers is used.  When unspecified, defaults to
-	`%(refname)`.
+	`%(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).
 
 <pattern>::
 	If given, the name of the ref is matched against this
 	using fnmatch(3).  Refs that do not match the pattern
 	are not shown.
 
---shell, --perl, --python::
+--shell, --perl, --python, --tcl::
 	If given, strings that substitute `%(fieldname)`
 	placeholders are quoted as string literals suitable for
 	the specified host language.  This is meant to produce
@@ -62,7 +66,7 @@ keys.
 For all objects, the following names can be used:
 
 refname::
-	The name of the ref (the part after $GIT_DIR/refs/).
+	The name of the ref (the part after $GIT_DIR/).
 
 objecttype::
 	The type of the object (`blob`, `tree`, `commit`, `tag`).
@@ -97,7 +101,8 @@ returns an empty string instead.
 EXAMPLES
 --------
 
-Show the most recent 3 tagged commits::
+An example directly producing formatted text.  Show the most recent
+3 tagged commits::
 
 ------------
 #!/bin/sh
@@ -112,7 +117,23 @@ Ref: %(*refname)
 ' 'refs/tags'
 ------------
 
-A bit more elaborate report on tags::
+
+A simple example showing the use of shell eval on the output,
+demonstrating the use of --shell.  List the prefixes of all heads::
+------------
+#!/bin/sh
+
+git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \
+while read entry
+do
+	eval "$entry"
+	echo `dirname $ref`
+done
+------------
+
+
+A bit more elaborate report on tags, demonstrating that the format
+may be an entire script::
 ------------
 #!/bin/sh
 
@@ -156,7 +177,7 @@ Its message reads as:
 	fi
 '
 
-eval=`git-for-each-ref -s --format="$fmt" \
+eval=`git-for-each-ref --shell --format="$fmt" \
 	--sort='*objecttype' \
 	--sort=-taggerdate \
 	refs/tags`