diff options
Diffstat (limited to 'Documentation/pretty-formats.txt')
| -rw-r--r-- | Documentation/pretty-formats.txt | 59 |
1 files changed, 37 insertions, 22 deletions
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 3b71334459..8ee940b6a4 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -122,7 +122,9 @@ The placeholders are: - Placeholders that expand to a single literal character: '%n':: newline '%%':: a raw '%' -'%x00':: print a byte from a hex code +'%x00':: '%x' followed by two hexadecimal digits is replaced with a + byte with the hexadecimal digits' value (we will call this + "literal formatting code" in the rest of this document). - Placeholders that affect formatting of later placeholders: '%Cred':: switch color to red @@ -222,13 +224,30 @@ The placeholders are: linkgit:git-rev-list[1]) '%d':: ref names, like the --decorate option of linkgit:git-log[1] '%D':: ref names without the " (", ")" wrapping. -'%(describe[:options])':: human-readable name, like - linkgit:git-describe[1]; empty string for - undescribable commits. The `describe` string - may be followed by a colon and zero or more - comma-separated options. Descriptions can be - inconsistent when tags are added or removed at - the same time. +'%(decorate[:<options>])':: +ref names with custom decorations. The `decorate` string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (`%x2C`) and closing +parentheses (`%x29`), due to their role in the option syntax. ++ +** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`". +** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`". +** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}". +** 'pointer=<value>': Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}`->`{nbsp}". +** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}". + ++ +For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators: ++ +`%(decorate:prefix=,suffix=,tag=,separator= )` + +'%(describe[:<options>])':: +human-readable name, like linkgit:git-describe[1]; empty string for +undescribable commits. The `describe` string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time. + ** 'tags[=<bool-value>]': Instead of only considering annotated tags, consider lightweight tags as well. @@ -281,13 +300,11 @@ endif::git-rev-list[] '%gE':: reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) '%gs':: reflog subject -'%(trailers[:options])':: display the trailers of the body as - interpreted by - linkgit:git-interpret-trailers[1]. The - `trailers` string may be followed by a colon - and zero or more comma-separated options. - If any option is provided multiple times the - last occurrence wins. +'%(trailers[:<options>])':: +display the trailers of the body as interpreted by +linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins. + ** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is @@ -299,9 +316,8 @@ endif::git-rev-list[] `Reviewed-by`. ** 'only[=<bool>]': select whether non-trailer lines from the trailer block should be included. -** 'separator=<sep>': specify a separator inserted between trailer - lines. When this option is not given each trailer line is - terminated with a line feed character. The string <sep> may contain +** 'separator=<sep>': specify the separator inserted between trailer + lines. Defaults to a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` @@ -312,10 +328,9 @@ endif::git-rev-list[] `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. ** 'keyonly[=<bool>]': only show the key part of the trailer. ** 'valueonly[=<bool>]': only show the value part of the trailer. -** 'key_value_separator=<sep>': specify a separator inserted between - trailer lines. When this option is not given each trailer key-value - pair is separated by ": ". Otherwise it shares the same semantics - as 'separator=<sep>' above. +** 'key_value_separator=<sep>': specify the separator inserted between + the key and value of each trailer. Defaults to ": ". Otherwise it + shares the same semantics as 'separator=<sep>' above. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will |