Merge branch 'ah/doc-gitattributes-empty-index' into maint
[git/git.git] / Documentation / pretty-formats.txt
CommitLineData
331b51d2
JN
1PRETTY FORMATS
2--------------
3
4If the commit is a merge, and if the pretty-format
5is not 'oneline', 'email' or 'raw', an additional line is
6inserted before the 'Author:' line. This line begins with
7"Merge: " and the sha1s of ancestral commits are printed,
8separated by spaces. Note that the listed commits may not
9necessarily be the list of the *direct* parent commits if you
10have limited your view of history: for example, if you are
11only interested in changes related to a certain directory or
12file.
13
8028184e
WP
14There are several built-in formats, and you can define
15additional formats by setting a pretty.<name>
16config option to either another format name, or a
17'format:' string, as described below (see
18linkgit:git-config[1]). Here are the details of the
19built-in formats:
331b51d2
JN
20
21* 'oneline'
5d1faf87
CR
22
23 <sha1> <title line>
24+
25This is designed to be as compact as possible.
26
331b51d2 27* 'short'
5d1faf87
CR
28
29 commit <sha1>
30 Author: <author>
31
32 <title line>
33
331b51d2 34* 'medium'
5d1faf87
CR
35
36 commit <sha1>
37 Author: <author>
ec9f0ea3 38 Date: <author date>
5d1faf87
CR
39
40 <title line>
41
42 <full commit message>
43
331b51d2 44* 'full'
5d1faf87
CR
45
46 commit <sha1>
47 Author: <author>
48 Commit: <committer>
49
50 <title line>
51
52 <full commit message>
53
331b51d2 54* 'fuller'
5d1faf87
CR
55
56 commit <sha1>
ec9f0ea3 57 Author: <author>
2b2da684 58 AuthorDate: <author date>
ec9f0ea3 59 Commit: <committer>
2b2da684 60 CommitDate: <committer date>
5d1faf87
CR
61
62 <title line>
63
64 <full commit message>
65
331b51d2 66* 'email'
5d1faf87
CR
67
68 From <sha1> <date>
69 From: <author>
2b2da684 70 Date: <author date>
5d1faf87
CR
71 Subject: [PATCH] <title line>
72
331b51d2 73 <full commit message>
5d1faf87 74
331b51d2 75* 'raw'
5d1faf87
CR
76+
77The 'raw' format shows the entire commit exactly as
d5fa1f1a 78stored in the commit object. Notably, the SHA-1s are
5d1faf87
CR
79displayed in full, regardless of whether --abbrev or
80--no-abbrev are used, and 'parents' information show the
a58088ab 81true parent commits, without taking grafts or history
92de9217
MM
82simplification into account. Note that this format affects the way
83commits are displayed, but not the way the diff is shown e.g. with
84`git log --raw`. To get full object names in a raw diff format,
85use `--no-abbrev`.
7cbcf4d5 86
41e4d69f 87* 'format:<string>'
e52a5de4 88+
41e4d69f 89The 'format:<string>' format allows you to specify which information
e52a5de4
JS
90you want to show. It works a little bit like printf format,
91with the notable exception that you get a newline with '%n'
92instead of '\n'.
331b51d2
JN
93+
94E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
e52a5de4 95would show something like this:
331b51d2
JN
96+
97-------
e52a5de4
JS
98The author of fe6e0ee was Junio C Hamano, 23 hours ago
99The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
100
c30c43c0 101-------
331b51d2 102+
e52a5de4
JS
103The placeholders are:
104
105- '%H': commit hash
106- '%h': abbreviated commit hash
107- '%T': tree hash
108- '%t': abbreviated tree hash
109- '%P': parent hashes
110- '%p': abbreviated parent hashes
111- '%an': author name
d2ea4afb
NTND
112- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1]
113 or linkgit:git-blame[1])
e52a5de4 114- '%ae': author email
d2ea4afb
NTND
115- '%aE': author email (respecting .mailmap, see
116 linkgit:git-shortlog[1] or linkgit:git-blame[1])
d36f8679 117- '%ad': author date (format respects --date= option)
e52a5de4
JS
118- '%aD': author date, RFC2822 style
119- '%ar': author date, relative
120- '%at': author date, UNIX timestamp
466fb674
BB
121- '%ai': author date, ISO 8601-like format
122- '%aI': author date, strict ISO 8601 format
e52a5de4 123- '%cn': committer name
d2ea4afb
NTND
124- '%cN': committer name (respecting .mailmap, see
125 linkgit:git-shortlog[1] or linkgit:git-blame[1])
e52a5de4 126- '%ce': committer email
d2ea4afb
NTND
127- '%cE': committer email (respecting .mailmap, see
128 linkgit:git-shortlog[1] or linkgit:git-blame[1])
dddecc5b 129- '%cd': committer date (format respects --date= option)
e52a5de4
JS
130- '%cD': committer date, RFC2822 style
131- '%cr': committer date, relative
132- '%ct': committer date, UNIX timestamp
466fb674
BB
133- '%ci': committer date, ISO 8601-like format
134- '%cI': committer date, strict ISO 8601 format
3b3d443f 135- '%d': ref names, like the --decorate option of linkgit:git-log[1]
9271095c 136- '%D': ref names without the " (", ")" wrapping.
e52a5de4
JS
137- '%e': encoding
138- '%s': subject
46d164b0 139- '%f': sanitized subject line, suitable for a filename
e52a5de4 140- '%b': body
1367b12a 141- '%B': raw body (unwrapped subject and body)
2aea7a51 142ifndef::git-rev-list[]
8b208f02 143- '%N': commit notes
2aea7a51 144endif::git-rev-list[]
f2fef7b5 145- '%GG': raw verification message from GPG for a signed commit
661a1806
MG
146- '%G?': show "G" for a good (valid) signature,
147 "B" for a bad signature,
148 "U" for a good signature with unknown validity,
149 "X" for a good signature that has expired,
150 "Y" for a good signature made by an expired key,
151 "R" for a good signature made by a revoked key,
152 "E" if the signature cannot be checked (e.g. missing key)
153 and "N" for no signature
f2fef7b5 154- '%GS': show the name of the signer for a signed commit
0174eeaa 155- '%GK': show the key used to sign a signed commit
522259dc
JK
156- '%gD': reflog selector, e.g., `refs/stash@{1}` or
157 `refs/stash@{2 minutes ago`}; the format follows the rules described
d38c7b2c
JK
158 for the `-g` option. The portion before the `@` is the refname as
159 given on the command line (so `git log -g refs/heads/master` would
160 yield `refs/heads/master@{0}`).
161- '%gd': shortened reflog selector; same as `%gD`, but the refname
162 portion is shortened for human readability (so `refs/heads/master`
163 becomes just `master`).
cd1957f5 164- '%gn': reflog identity name
d2ea4afb
NTND
165- '%gN': reflog identity name (respecting .mailmap, see
166 linkgit:git-shortlog[1] or linkgit:git-blame[1])
cd1957f5 167- '%ge': reflog identity email
d2ea4afb
NTND
168- '%gE': reflog identity email (respecting .mailmap, see
169 linkgit:git-shortlog[1] or linkgit:git-blame[1])
8f8f5476 170- '%gs': reflog subject
e52a5de4
JS
171- '%Cred': switch color to red
172- '%Cgreen': switch color to green
173- '%Cblue': switch color to blue
174- '%Creset': reset color
30cfe72d
RS
175- '%C(...)': color specification, as described under Values in the
176 "CONFIGURATION FILE" section of linkgit:git-config[1];
30825178
JH
177 adding `auto,` at the beginning will emit color only when colors are
178 enabled for log output (by `color.diff`, `color.ui`, or `--color`, and
179 respecting the `auto` settings of the former if we are going to a
a95f067e
NTND
180 terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
181 on the next placeholders until the color is switched again.
c6eff44d 182- '%m': left (`<`), right (`>`) or boundary (`-`) mark
e52a5de4 183- '%n': newline
0a0416a3 184- '%%': a raw '%'
42c8c74c 185- '%x00': print a byte from a hex code
3288f201 186- '%w([<w>[,<i1>[,<i2>]]])': switch line wrapping, like the -w option of
8a3c63e0 187 linkgit:git-shortlog[1].
a7f01c6b
NTND
188- '%<(<N>[,trunc|ltrunc|mtrunc])': make the next placeholder take at
189 least N columns, padding spaces on the right if necessary.
190 Optionally truncate at the beginning (ltrunc), the middle (mtrunc)
191 or the end (trunc) if the output is longer than N columns.
192 Note that truncating only works correctly with N >= 2.
a5752342
NTND
193- '%<|(<N>)': make the next placeholder take at least until Nth
194 columns, padding spaces on the right if necessary
195- '%>(<N>)', '%>|(<N>)': similar to '%<(<N>)', '%<|(<N>)'
196 respectively, but padding spaces on the left
1640632b
NTND
197- '%>>(<N>)', '%>>|(<N>)': similar to '%>(<N>)', '%>|(<N>)'
198 respectively, except that if the next placeholder takes more spaces
199 than given and there are spaces on its left, use those spaces
200- '%><(<N>)', '%><|(<N>)': similar to '% <(<N>)', '%<|(<N>)'
a5752342 201 respectively, but padding both sides (i.e. the text is centered)
fc7a5edb 202- %(trailers): display the trailers of the body as interpreted by
d9f31fbf 203 linkgit:git-interpret-trailers[1]
fa5b4f37 204
8f8f5476
TR
205NOTE: Some placeholders may depend on other options given to the
206revision traversal engine. For example, the `%g*` reflog options will
207insert an empty string unless we are traversing reflog entries (e.g., by
9271095c
HJ
208`git log -g`). The `%d` and `%D` placeholders will use the "short"
209decoration format if `--decorate` was not already provided on the command
210line.
8f8f5476 211
6cf378f0 212If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
9fa708da
JH
213is inserted immediately before the expansion if and only if the
214placeholder expands to a non-empty string.
215
8abc09c0
SG
216If you add a `-` (minus sign) after '%' of a placeholder, all consecutive
217line-feeds immediately preceding the expansion are deleted if and only if the
9fa708da
JH
218placeholder expands to an empty string.
219
7b88176e
MG
220If you add a ` ` (space) after '%' of a placeholder, a space
221is inserted immediately before the expansion if and only if the
222placeholder expands to a non-empty string.
223
fa5b4f37
JK
224* 'tformat:'
225+
226The 'tformat:' format works exactly like 'format:', except that it
227provides "terminator" semantics instead of "separator" semantics. In
228other words, each commit has the message terminator character (usually a
229newline) appended, rather than a separator placed between entries.
230This means that the final entry of a single-line format will be properly
231terminated with a new line, just as the "oneline" format does.
232For example:
233+
234---------------------
235$ git log -2 --pretty=format:%h 4da45bef \
236 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
2374da45be
2387134973 -- NO NEWLINE
239
240$ git log -2 --pretty=tformat:%h 4da45bef \
241 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
2424da45be
2437134973
244---------------------
36407548
NS
245+
246In addition, any unrecognized string that has a `%` in it is interpreted
247as if it has `tformat:` in front of it. For example, these two are
248equivalent:
249+
250---------------------
251$ git log -2 --pretty=tformat:%h 4da45bef
252$ git log -2 --pretty=%h 4da45bef
253---------------------