mirror of
https://github.com/git/git
synced 2024-11-05 18:59:29 +00:00
e52e6f79cc
pretty-printing body of the commit that is stored in non UTF-8 encoding did not work well. The early part of this series fixes it. And then it adds %C(auto) specifier that turns the coloring on when we are emitting to the terminal, and adds column-aligning format directives. * nd/pretty-formats: pretty: support %>> that steal trailing spaces pretty: support truncating in %>, %< and %>< pretty: support padding placeholders, %< %> and %>< pretty: add %C(auto) for auto-coloring pretty: split color parsing into a separate function pretty: two phase conversion for non utf-8 commits utf8.c: add reencode_string_len() that can handle NULs in string utf8.c: add utf8_strnwidth() with the ability to skip ansi sequences utf8.c: move display_mode_esc_sequence_len() for use by other functions pretty: share code between format_decoration and show_decorations pretty-formats.txt: wrap long lines pretty: get the correct encoding for --pretty:format=%e pretty: save commit encoding from logmsg_reencode if the caller needs it
229 lines
7.6 KiB
Text
229 lines
7.6 KiB
Text
PRETTY FORMATS
|
|
--------------
|
|
|
|
If the commit is a merge, and if the pretty-format
|
|
is not 'oneline', 'email' or 'raw', an additional line is
|
|
inserted before the 'Author:' line. This line begins with
|
|
"Merge: " and the sha1s of ancestral commits are printed,
|
|
separated by spaces. Note that the listed commits may not
|
|
necessarily be the list of the *direct* parent commits if you
|
|
have limited your view of history: for example, if you are
|
|
only interested in changes related to a certain directory or
|
|
file.
|
|
|
|
There are several built-in formats, and you can define
|
|
additional formats by setting a pretty.<name>
|
|
config option to either another format name, or a
|
|
'format:' string, as described below (see
|
|
linkgit:git-config[1]). Here are the details of the
|
|
built-in formats:
|
|
|
|
* 'oneline'
|
|
|
|
<sha1> <title line>
|
|
+
|
|
This is designed to be as compact as possible.
|
|
|
|
* 'short'
|
|
|
|
commit <sha1>
|
|
Author: <author>
|
|
|
|
<title line>
|
|
|
|
* 'medium'
|
|
|
|
commit <sha1>
|
|
Author: <author>
|
|
Date: <author date>
|
|
|
|
<title line>
|
|
|
|
<full commit message>
|
|
|
|
* 'full'
|
|
|
|
commit <sha1>
|
|
Author: <author>
|
|
Commit: <committer>
|
|
|
|
<title line>
|
|
|
|
<full commit message>
|
|
|
|
* 'fuller'
|
|
|
|
commit <sha1>
|
|
Author: <author>
|
|
AuthorDate: <author date>
|
|
Commit: <committer>
|
|
CommitDate: <committer date>
|
|
|
|
<title line>
|
|
|
|
<full commit message>
|
|
|
|
* 'email'
|
|
|
|
From <sha1> <date>
|
|
From: <author>
|
|
Date: <author date>
|
|
Subject: [PATCH] <title line>
|
|
|
|
<full commit message>
|
|
|
|
* 'raw'
|
|
+
|
|
The 'raw' format shows the entire commit exactly as
|
|
stored in the commit object. Notably, the SHA-1s are
|
|
displayed in full, regardless of whether --abbrev or
|
|
--no-abbrev are used, and 'parents' information show the
|
|
true parent commits, without taking grafts nor history
|
|
simplification into account.
|
|
|
|
* 'format:<string>'
|
|
+
|
|
The 'format:<string>' format allows you to specify which information
|
|
you want to show. It works a little bit like printf format,
|
|
with the notable exception that you get a newline with '%n'
|
|
instead of '\n'.
|
|
+
|
|
E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
|
|
would show something like this:
|
|
+
|
|
-------
|
|
The author of fe6e0ee was Junio C Hamano, 23 hours ago
|
|
The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
|
|
|
|
--------
|
|
+
|
|
The placeholders are:
|
|
|
|
- '%H': commit hash
|
|
- '%h': abbreviated commit hash
|
|
- '%T': tree hash
|
|
- '%t': abbreviated tree hash
|
|
- '%P': parent hashes
|
|
- '%p': abbreviated parent hashes
|
|
- '%an': author name
|
|
- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1]
|
|
or linkgit:git-blame[1])
|
|
- '%ae': author email
|
|
- '%aE': author email (respecting .mailmap, see
|
|
linkgit:git-shortlog[1] or linkgit:git-blame[1])
|
|
- '%ad': author date (format respects --date= option)
|
|
- '%aD': author date, RFC2822 style
|
|
- '%ar': author date, relative
|
|
- '%at': author date, UNIX timestamp
|
|
- '%ai': author date, ISO 8601 format
|
|
- '%cn': committer name
|
|
- '%cN': committer name (respecting .mailmap, see
|
|
linkgit:git-shortlog[1] or linkgit:git-blame[1])
|
|
- '%ce': committer email
|
|
- '%cE': committer email (respecting .mailmap, see
|
|
linkgit:git-shortlog[1] or linkgit:git-blame[1])
|
|
- '%cd': committer date
|
|
- '%cD': committer date, RFC2822 style
|
|
- '%cr': committer date, relative
|
|
- '%ct': committer date, UNIX timestamp
|
|
- '%ci': committer date, ISO 8601 format
|
|
- '%d': ref names, like the --decorate option of linkgit:git-log[1]
|
|
- '%e': encoding
|
|
- '%s': subject
|
|
- '%f': sanitized subject line, suitable for a filename
|
|
- '%b': body
|
|
- '%B': raw body (unwrapped subject and body)
|
|
- '%N': commit notes
|
|
- '%GG': raw verification message from GPG for a signed commit
|
|
- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good,
|
|
untrusted signature and "N" for no signature
|
|
- '%GS': show the name of the signer for a signed commit
|
|
- '%GK': show the key used to sign a signed commit
|
|
- '%gD': reflog selector, e.g., `refs/stash@{1}`
|
|
- '%gd': shortened reflog selector, e.g., `stash@{1}`
|
|
- '%gn': reflog identity name
|
|
- '%gN': reflog identity name (respecting .mailmap, see
|
|
linkgit:git-shortlog[1] or linkgit:git-blame[1])
|
|
- '%ge': reflog identity email
|
|
- '%gE': reflog identity email (respecting .mailmap, see
|
|
linkgit:git-shortlog[1] or linkgit:git-blame[1])
|
|
- '%gs': reflog subject
|
|
- '%Cred': switch color to red
|
|
- '%Cgreen': switch color to green
|
|
- '%Cblue': switch color to blue
|
|
- '%Creset': reset color
|
|
- '%C(...)': color specification, as described in color.branch.* config option;
|
|
adding `auto,` at the beginning will emit color only when colors are
|
|
enabled for log output (by `color.diff`, `color.ui`, or `--color`, and
|
|
respecting the `auto` settings of the former if we are going to a
|
|
terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
|
|
on the next placeholders until the color is switched again.
|
|
- '%m': left, right or boundary mark
|
|
- '%n': newline
|
|
- '%%': a raw '%'
|
|
- '%x00': print a byte from a hex code
|
|
- '%w([<w>[,<i1>[,<i2>]]])': switch line wrapping, like the -w option of
|
|
linkgit:git-shortlog[1].
|
|
- '%<(<N>[,trunc|ltrunc|mtrunc])': make the next placeholder take at
|
|
least N columns, padding spaces on the right if necessary.
|
|
Optionally truncate at the beginning (ltrunc), the middle (mtrunc)
|
|
or the end (trunc) if the output is longer than N columns.
|
|
Note that truncating only works correctly with N >= 2.
|
|
- '%<|(<N>)': make the next placeholder take at least until Nth
|
|
columns, padding spaces on the right if necessary
|
|
- '%>(<N>)', '%>|(<N>)': similar to '%<(<N>)', '%<|(<N>)'
|
|
respectively, but padding spaces on the left
|
|
- '%>>(<N>)', '%>>|(<N>)': similar to '%>(<N>)', '%>|(<N>)'
|
|
respectively, except that if the next placeholder takes more spaces
|
|
than given and there are spaces on its left, use those spaces
|
|
- '%><(<N>)', '%><|(<N>)': similar to '% <(<N>)', '%<|(<N>)'
|
|
respectively, but padding both sides (i.e. the text is centered)
|
|
|
|
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.
|
|
|
|
If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
|
|
is inserted immediately before the expansion if and only if the
|
|
placeholder expands to a non-empty string.
|
|
|
|
If you add a `-` (minus sign) after '%' of a placeholder, line-feeds that
|
|
immediately precede the expansion are deleted if and only if the
|
|
placeholder expands to an empty string.
|
|
|
|
If you add a ` ` (space) after '%' of a placeholder, a space
|
|
is inserted immediately before the expansion if and only if the
|
|
placeholder expands to a non-empty string.
|
|
|
|
* 'tformat:'
|
|
+
|
|
The 'tformat:' format works exactly like 'format:', except that it
|
|
provides "terminator" semantics instead of "separator" semantics. In
|
|
other words, each commit has the message terminator character (usually a
|
|
newline) appended, rather than a separator placed between entries.
|
|
This means that the final entry of a single-line format will be properly
|
|
terminated with a new line, just as the "oneline" format does.
|
|
For example:
|
|
+
|
|
---------------------
|
|
$ git log -2 --pretty=format:%h 4da45bef \
|
|
| perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
|
|
4da45be
|
|
7134973 -- NO NEWLINE
|
|
|
|
$ git log -2 --pretty=tformat:%h 4da45bef \
|
|
| perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
|
|
4da45be
|
|
7134973
|
|
---------------------
|
|
+
|
|
In addition, any unrecognized string that has a `%` in it is interpreted
|
|
as if it has `tformat:` in front of it. For example, these two are
|
|
equivalent:
|
|
+
|
|
---------------------
|
|
$ git log -2 --pretty=tformat:%h 4da45bef
|
|
$ git log -2 --pretty=%h 4da45bef
|
|
---------------------
|