Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git log --pretty=oneline
git log --pretty=format:'%h %an %s'
git log --format='%C(yellow)%h%Creset %s'

Try it

Bash Built-in formats and common placeholders

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.

Bash Padding, colors, format versus tformat and aliases

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

Terminal
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: versus tformat:: format: puts a newline between entries; tformat: puts one after each. --pretty=%h and --oneline use 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=always is given.
  • Dates: the --date= option changes %ad and %cd. The %ai, %aI, %as and %at forms 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 -z with --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: value form.