Subject: [PATCH] Documentation: Update information about <format> in git-for-each-ref

From: Jakub Narebski <[email-masked]>
Date: Sat, 28 Oct 2006 19:30:05 +0200

Update information about value of <format> used when it is left
unspecified.  Add information about `%%` and `%xx` interpolation
(URL encoding).

Signed-off-by: Jakub Narebski <[email-masked]>
---
Could any of you review this, fix wording (if needed)?

By the way one thing missing from git-for-each-ref to use it
in gitweb without changing its output is ablility to sort on
"epoch", i.e. taggerdate for tags and committerdate for commits.
This is needed to sort heavyweight and lightweight tags together
on epoch in "summary" and "tags" views in gitweb. (It is not
needed for heads/branches, but it is the tags sorting that
cripples gitweb "summary" view performance.)

We could either add "fake" field `date` which will be `taggerdate`
for tags and `committerdate` for commits, and empty for trees
and blobs, or allow in <key> for more than one field to be
specified.

I also wish for change of %(field) to %{field}, adding %nn{field}
and %-nn{field} field width specifiers, committerepoch and
committertz fields (and equivalent for tagger and author) or
%{committer:date} like field-format specifiers. And for peace
on Earth while at it... ;-)

 Documentation/git-for-each-ref.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d5fdcef..4af1ebf 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -38,7 +38,11 @@ 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
-- 
1.4.3.3