Documentation/pretty-formats.txt

   1 PRETTY FORMATS
   2 --------------
   3
   4 If the commit is a merge, and if the pretty-format
   5 is not 'oneline', 'email' or 'raw', an additional line is
   6 inserted before the 'Author:' line.  This line begins with
   7 "Merge: " and the hashes of ancestral commits are printed,
   8 separated by spaces.  Note that the listed commits may not
   9 necessarily be the list of the *direct* parent commits if you
  10 have limited your view of history: for example, if you are
  11 only interested in changes related to a certain directory or
  12 file.
  13
  14 There are several built-in formats, and you can define
  15 additional formats by setting a pretty.<name>
  16 config option to either another format name, or a
  17 'format:' string, as described below (see
  18 linkgit:git-config[1]). Here are the details of the
  19 built-in formats:
  20
  21 * 'oneline'
  22
  23           <hash> <title-line>
  24 +
  25 This is designed to be as compact as possible.
  26
  27 * 'short'
  28
  29           commit <hash>
  30           Author: <author>
  31
  32               <title-line>
  33
  34 * 'medium'
  35
  36           commit <hash>
  37           Author: <author>
  38           Date:   <author-date>
  39
  40               <title-line>
  41
  42               <full-commit-message>
  43
  44 * 'full'
  45
  46           commit <hash>
  47           Author: <author>
  48           Commit: <committer>
  49
  50               <title-line>
  51
  52               <full-commit-message>
  53
  54 * 'fuller'
  55
  56           commit <hash>
  57           Author:     <author>
  58           AuthorDate: <author-date>
  59           Commit:     <committer>
  60           CommitDate: <committer-date>
  61
  62                <title-line>
  63
  64                <full-commit-message>
  65
  66 * 'reference'
  67
  68           <abbrev-hash> (<title-line>, <short-author-date>)
  69 +
  70 This format is used to refer to another commit in a commit message and
  71 is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
  72 the date is formatted with `--date=short` unless another `--date` option
  73 is explicitly specified.  As with any `format:` with format
  74 placeholders, its output is not affected by other options like
  75 `--decorate` and `--walk-reflogs`.
  76
  77 * 'email'
  78
  79           From <hash> <date>
  80           From: <author>
  81           Date: <author-date>
  82           Subject: [PATCH] <title-line>
  83
  84           <full-commit-message>
  85
  86 * 'mboxrd'
  87 +
  88 Like 'email', but lines in the commit message starting with "From "
  89 (preceded by zero or more ">") are quoted with ">" so they aren't
  90 confused as starting a new commit.
  91
  92 * 'raw'
  93 +
  94 The 'raw' format shows the entire commit exactly as
  95 stored in the commit object.  Notably, the hashes are
  96 displayed in full, regardless of whether --abbrev or
  97 --no-abbrev are used, and 'parents' information show the
  98 true parent commits, without taking grafts or history
  99 simplification into account. Note that this format affects the way
 100 commits are displayed, but not the way the diff is shown e.g. with
 101 `git log --raw`. To get full object names in a raw diff format,
 102 use `--no-abbrev`.
 103
 104 * 'format:<format-string>'
 105 +
 106 The 'format:<format-string>' format allows you to specify which information
 107 you want to show. It works a little bit like printf format,
 108 with the notable exception that you get a newline with '%n'
 109 instead of '\n'.
 110 +
 111 E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
 112 would show something like this:
 113 +
 114 -------
 115 The author of fe6e0ee was Junio C Hamano, 23 hours ago
 116 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
 117
 118 -------
 119 +
 120 The placeholders are:
 121
 122 - Placeholders that expand to a single literal character:
 123 '%n':: newline
 124 '%%':: a raw '%'
 125 '%x00':: print a byte from a hex code
 126
 127 - Placeholders that affect formatting of later placeholders:
 128 '%Cred':: switch color to red
 129 '%Cgreen':: switch color to green
 130 '%Cblue':: switch color to blue
 131 '%Creset':: reset color
 132 '%C(...)':: color specification, as described under Values in the
 133             "CONFIGURATION FILE" section of linkgit:git-config[1].  By
 134             default, colors are shown only when enabled for log output
 135             (by `color.diff`, `color.ui`, or `--color`, and respecting
 136             the `auto` settings of the former if we are going to a
 137             terminal). `%C(auto,...)` is accepted as a historical
 138             synonym for the default (e.g., `%C(auto,red)`). Specifying
 139             `%C(always,...)` will show the colors even when color is
 140             not otherwise enabled (though consider just using
 141             `--color=always` to enable color for the whole output,
 142             including this format and anything else git might color).
 143             `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
 144             on the next placeholders until the color is switched
 145             again.
 146 '%m':: left (`<`), right (`>`) or boundary (`-`) mark
 147 '%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of
 148                             linkgit:git-shortlog[1].
 149 '%<( <N> [,trunc|ltrunc|mtrunc])':: make the next placeholder take at
 150                                   least N column widths, padding spaces on
 151                                   the right if necessary.  Optionally
 152                                   truncate (with ellipsis '..') at the left (ltrunc) `..ft`,
 153                                   the middle (mtrunc) `mi..le`, or the end
 154                                   (trunc) `rig..`, if the output is longer than
 155                                   N columns.
 156                                   Note 1: that truncating
 157                                   only works correctly with N >= 2.
 158                                   Note 2: spaces around the N and M (see below)
 159                                   values are optional.
 160                                   Note 3: Emojis and other wide characters
 161                                   will take two display columns, which may
 162                                   over-run column boundaries.
 163                                   Note 4: decomposed character combining marks
 164                                   may be misplaced at padding boundaries.
 165 '%<|( <M> )':: make the next placeholder take at least until Mth
 166              display column, padding spaces on the right if necessary.
 167              Use negative M values for column positions measured
 168              from the right hand edge of the terminal window.
 169 '%>( <N> )', '%>|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' respectively,
 170                         but padding spaces on the left
 171 '%>>( <N> )', '%>>|( <M> )':: similar to '%>( <N> )', '%>|( <M> )'
 172                           respectively, except that if the next
 173                           placeholder takes more spaces than given and
 174                           there are spaces on its left, use those
 175                           spaces
 176 '%><( <N> )', '%><|( <M> )':: similar to '%<( <N> )', '%<|( <M> )'
 177                           respectively, but padding both sides
 178                           (i.e. the text is centered)
 179
 180 - Placeholders that expand to information extracted from the commit:
 181 '%H':: commit hash
 182 '%h':: abbreviated commit hash
 183 '%T':: tree hash
 184 '%t':: abbreviated tree hash
 185 '%P':: parent hashes
 186 '%p':: abbreviated parent hashes
 187 '%an':: author name
 188 '%aN':: author name (respecting .mailmap, see linkgit:git-shortlog[1]
 189         or linkgit:git-blame[1])
 190 '%ae':: author email
 191 '%aE':: author email (respecting .mailmap, see linkgit:git-shortlog[1]
 192         or linkgit:git-blame[1])
 193 '%al':: author email local-part (the part before the '@' sign)
 194 '%aL':: author local-part (see '%al') respecting .mailmap, see
 195         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 196 '%ad':: author date (format respects --date= option)
 197 '%aD':: author date, RFC2822 style
 198 '%ar':: author date, relative
 199 '%at':: author date, UNIX timestamp
 200 '%ai':: author date, ISO 8601-like format
 201 '%aI':: author date, strict ISO 8601 format
 202 '%as':: author date, short format (`YYYY-MM-DD`)
 203 '%ah':: author date, human style (like the `--date=human` option of
 204         linkgit:git-rev-list[1])
 205 '%cn':: committer name
 206 '%cN':: committer name (respecting .mailmap, see
 207         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 208 '%ce':: committer email
 209 '%cE':: committer email (respecting .mailmap, see
 210         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 211 '%cl':: committer email local-part (the part before the '@' sign)
 212 '%cL':: committer local-part (see '%cl') respecting .mailmap, see
 213         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 214 '%cd':: committer date (format respects --date= option)
 215 '%cD':: committer date, RFC2822 style
 216 '%cr':: committer date, relative
 217 '%ct':: committer date, UNIX timestamp
 218 '%ci':: committer date, ISO 8601-like format
 219 '%cI':: committer date, strict ISO 8601 format
 220 '%cs':: committer date, short format (`YYYY-MM-DD`)
 221 '%ch':: committer date, human style (like the `--date=human` option of
 222         linkgit:git-rev-list[1])
 223 '%d':: ref names, like the --decorate option of linkgit:git-log[1]
 224 '%D':: ref names without the " (", ")" wrapping.
 225 '%(describe[:options])':: human-readable name, like
 226                           linkgit:git-describe[1]; empty string for
 227                           undescribable commits.  The `describe` string
 228                           may be followed by a colon and zero or more
 229                           comma-separated options.  Descriptions can be
 230                           inconsistent when tags are added or removed at
 231                           the same time.
 232 +
 233 ** 'tags[=<bool-value>]': Instead of only considering annotated tags,
 234    consider lightweight tags as well.
 235 ** 'abbrev=<number>': Instead of using the default number of hexadecimal digits
 236    (which will vary according to the number of objects in the repository with a
 237    default of 7) of the abbreviated object name, use <number> digits, or as many
 238    digits as needed to form a unique object name.
 239 ** 'match=<pattern>': Only consider tags matching the given
 240    `glob(7)` pattern, excluding the "refs/tags/" prefix.
 241 ** 'exclude=<pattern>': Do not consider tags matching the given
 242    `glob(7)` pattern, excluding the "refs/tags/" prefix.
 243
 244 '%S':: ref name given on the command line by which the commit was reached
 245        (like `git log --source`), only works with `git log`
 246 '%e':: encoding
 247 '%s':: subject
 248 '%f':: sanitized subject line, suitable for a filename
 249 '%b':: body
 250 '%B':: raw body (unwrapped subject and body)
 251 ifndef::git-rev-list[]
 252 '%N':: commit notes
 253 endif::git-rev-list[]
 254 '%GG':: raw verification message from GPG for a signed commit
 255 '%G?':: show "G" for a good (valid) signature,
 256         "B" for a bad signature,
 257         "U" for a good signature with unknown validity,
 258         "X" for a good signature that has expired,
 259         "Y" for a good signature made by an expired key,
 260         "R" for a good signature made by a revoked key,
 261         "E" if the signature cannot be checked (e.g. missing key)
 262         and "N" for no signature
 263 '%GS':: show the name of the signer for a signed commit
 264 '%GK':: show the key used to sign a signed commit
 265 '%GF':: show the fingerprint of the key used to sign a signed commit
 266 '%GP':: show the fingerprint of the primary key whose subkey was used
 267         to sign a signed commit
 268 '%GT':: show the trust level for the key used to sign a signed commit
 269 '%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2
 270         minutes ago}`; the format follows the rules described for the
 271         `-g` option. The portion before the `@` is the refname as
 272         given on the command line (so `git log -g refs/heads/master`
 273         would yield `refs/heads/master@{0}`).
 274 '%gd':: shortened reflog selector; same as `%gD`, but the refname
 275         portion is shortened for human readability (so
 276         `refs/heads/master` becomes just `master`).
 277 '%gn':: reflog identity name
 278 '%gN':: reflog identity name (respecting .mailmap, see
 279         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 280 '%ge':: reflog identity email
 281 '%gE':: reflog identity email (respecting .mailmap, see
 282         linkgit:git-shortlog[1] or linkgit:git-blame[1])
 283 '%gs':: reflog subject
 284 '%(trailers[:options])':: display the trailers of the body as
 285                           interpreted by
 286                           linkgit:git-interpret-trailers[1]. The
 287                           `trailers` string may be followed by a colon
 288                           and zero or more comma-separated options.
 289                           If any option is provided multiple times the
 290                           last occurrence wins.
 291 +
 292 ** 'key=<key>': only show trailers with specified <key>. Matching is done
 293    case-insensitively and trailing colon is optional. If option is
 294    given multiple times trailer lines matching any of the keys are
 295    shown. This option automatically enables the `only` option so that
 296    non-trailer lines in the trailer block are hidden. If that is not
 297    desired it can be disabled with `only=false`.  E.g.,
 298    `%(trailers:key=Reviewed-by)` shows trailer lines with key
 299    `Reviewed-by`.
 300 ** 'only[=<bool>]': select whether non-trailer lines from the trailer
 301    block should be included.
 302 ** 'separator=<sep>': specify a separator inserted between trailer
 303    lines. When this option is not given each trailer line is
 304    terminated with a line feed character. The string <sep> may contain
 305    the literal formatting codes described above. To use comma as
 306    separator one must use `%x2C` as it would otherwise be parsed as
 307    next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
 308    shows all trailer lines whose key is "Ticket" separated by a comma
 309    and a space.
 310 ** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold`
 311    option was given. E.g.,
 312    `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
 313 ** 'keyonly[=<bool>]': only show the key part of the trailer.
 314 ** 'valueonly[=<bool>]': only show the value part of the trailer.
 315 ** 'key_value_separator=<sep>': specify a separator inserted between
 316    trailer lines. When this option is not given each trailer key-value
 317    pair is separated by ": ". Otherwise it shares the same semantics
 318    as 'separator=<sep>' above.
 319
 320 NOTE: Some placeholders may depend on other options given to the
 321 revision traversal engine. For example, the `%g*` reflog options will
 322 insert an empty string unless we are traversing reflog entries (e.g., by
 323 `git log -g`). The `%d` and `%D` placeholders will use the "short"
 324 decoration format if `--decorate` was not already provided on the command
 325 line.
 326
 327 The boolean options accept an optional value `[=<bool-value>]`. The values
 328 `true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
 329 sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
 330 option is given with no value, it's enabled.
 331
 332 If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
 333 is inserted immediately before the expansion if and only if the
 334 placeholder expands to a non-empty string.
 335
 336 If you add a `-` (minus sign) after '%' of a placeholder, all consecutive
 337 line-feeds immediately preceding the expansion are deleted if and only if the
 338 placeholder expands to an empty string.
 339
 340 If you add a ` ` (space) after '%' of a placeholder, a space
 341 is inserted immediately before the expansion if and only if the
 342 placeholder expands to a non-empty string.
 343
 344 * 'tformat:'
 345 +
 346 The 'tformat:' format works exactly like 'format:', except that it
 347 provides "terminator" semantics instead of "separator" semantics. In
 348 other words, each commit has the message terminator character (usually a
 349 newline) appended, rather than a separator placed between entries.
 350 This means that the final entry of a single-line format will be properly
 351 terminated with a new line, just as the "oneline" format does.
 352 For example:
 353 +
 354 ---------------------
 355 $ git log -2 --pretty=format:%h 4da45bef \
 356   | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
 357 4da45be
 358 7134973 -- NO NEWLINE
 359
 360 $ git log -2 --pretty=tformat:%h 4da45bef \
 361   | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
 362 4da45be
 363 7134973
 364 ---------------------
 365 +
 366 In addition, any unrecognized string that has a `%` in it is interpreted
 367 as if it has `tformat:` in front of it.  For example, these two are
 368 equivalent:
 369 +
 370 ---------------------
 371 $ git log -2 --pretty=tformat:%h 4da45bef
 372 $ git log -2 --pretty=%h 4da45bef
 373 ---------------------