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