Git Reference ยท Inspecting History
git log --pretty option
Reference for git log --pretty and --format: built-in formats, every common placeholder (%H, %an, %s, %d, %C...), padding, trailers, tformat versus format, and aliases.
--pretty (and its shorthand --format) decides how each commit is printed by git log, git show and related commands. You either choose one of the built-in formats such as oneline or fuller, or write your own template in which %-placeholders stand for the commit's data.
Custom templates are the right way to feed commit data to scripts, build changelogs, or make a compact log that suits your team. Placeholders keep their meaning between releases, which is why scripts can depend on them, unlike the human-readable default output.
git log --pretty=oneline git log --pretty=format:'%h %an %s' git log --format='%C(yellow)%h%Creset %s'
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git log --pretty[=<format>] git log --format=<format>
<format> is one of the built-in names, format:<template>, tformat:<template>, or a name you defined in the pretty.<name> configuration key. A value containing a % is treated as tformat:.
Built-in formats
| Name | Shows |
|---|---|
oneline |
Full ID and subject on one line (combine with --abbrev-commit or use --oneline). |
short |
ID, author, subject. |
medium |
ID, author, date, full message. The default. |
full |
Like medium, with committer, no dates. |
fuller |
Author and committer with their dates. |
reference |
abbrev-id (subject, short-date), for citing a commit in a message. |
email |
An email-like header, as used by patches. |
raw |
The commit object as stored, with raw timestamps. |
Placeholders
| Placeholder | Meaning |
|---|---|
%H, %h |
Commit ID, full and abbreviated. |
%T, %t |
Tree ID, full and abbreviated. |
%P, %p |
Parent IDs, full and abbreviated. |
%an, %ae, %al |
Author name, email, email local part. %aN, %aE apply the mailmap. |
%cn, %ce, %cl |
Same for the committer. |
%ad, %aD, %ai, %aI, %as, %at |
Author date: default, RFC 2822, ISO-like, strict ISO 8601, short (YYYY-MM-DD), Unix timestamp. %ar is relative ("3 days ago"). Same letters with c for the committer. |
%s, %f |
Subject; subject made safe for a file name. |
%b, %B |
Body; raw message (subject and body). |
%d, %D |
Ref names, with and without the wrapping parentheses. |
%S |
The ref the commit was reached from (with --source). |
%e |
Encoding. |
%G?, %GS, %GK |
Signature status, signer, key (when signed). |
%(trailers[:options]) |
Trailers such as Signed-off-by. Options include key=, only, unfold, valueonly. |
%(describe[:options]) |
Output of git describe for the commit. |
%m |
Boundary marker: <, >, - or o. |
%n, %%, %x41 |
Newline, percent sign, a byte given in hex. |
%C(<color>), %Cred, %Creset |
Switch colors (only effective when color is on). %C(auto) follows --color. |
%<(N), %>(N), %<(N,trunc) |
Pad the next placeholder to width N, left- or right-aligned, optionally truncating. |
%w(width,indent1,indent2) |
Wrap the following text. |
Usage notes
format:versustformat::format:puts a newline between entries;tformat:puts one after each.--pretty=%hand--onelineuse the terminator style, which is what almost every script wants.- Placeholders that do not exist are printed literally, so a typo shows up as plain text instead of an error.
- Colors vanish when output is not a terminal unless
--color=alwaysis given. - Dates: the
--date=option changes%adand%cd. The%ai,%aI,%asand%atforms are not affected and are best for scripts; avoid%ar, because its text depends on today's date. - Padding counts characters, not display width, so wide characters may misalign columns.
- Define reusable formats with
git config pretty.name '<template>'and call them with--pretty=name. - Use
-zwith--format(NUL terminators) when messages may contain newlines and a script has to split records safely. - Trailers are recognized only in the last paragraph of the message, in
Key: valueform.
Related
git log,git show,git for-each-ref,git interpret-trailers- Lessons: Log and show, Aliases