Re: [PATCH v3 0/5] Pretty formats for reflog data

[Jeff King <peff@peff.net>]

On Fri, Oct 16, 2009 at 04:20:32PM +0200, Thomas Rast wrote:

> I tried for some time, but all attempts at interrupting the lists
> ended up terminating it again, so that the %g family list would not
> line up with the rest of the parameters.  Having the note there would
> be nice, but I think keeping the list together optically is more
> important.  However, AFAICS it really is the first character that only
> works with certain options (%m makes little sense without A...B, but
> still expands to >).

Another example is "%d", but there we load decorations on the fly the
first time it is used. I don't think that's a good idea here, since
using "%gd" shouldn't automatically imply "-g", which drastically
changes the nature of the command.

The "%m" behavior does what I would expect. If you haven't done any
limiting, then there can be no "left" or "boundary" entries.

I am tempted to do a note like the one below, but maybe the behavior is
obvious enough to users that it isn't necessary.

> Looking at it did make me notice that @{1} is invalid asciidoc and
> needs to be spelled @\{1\} though :-)

Thanks. I am often very guilty of not actually building documentation
when reviewing patches, because it is so tedious to build and examine.

---
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 6359272..43192af 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -135,6 +135,12 @@ The placeholders are:
 - '%n': newline
 - '%x00': print a byte from a hex code
 
+NOTE: Some placeholders may depend on other options given to the
+revision traversal engine. For example, the `%g*` reflog options will
+insert an empty string unless we are traversing reflog entries (e.g., by
+`git log -g`). The `%d` placeholder will use the "short" decoration
+format if `--decorate` was not already provided on the command line.
+
 * 'tformat:'
 +
 The 'tformat:' format works exactly like 'format:', except that it