Skip to content

Commit 42977bf

Browse files
gitstergitster
committed
Merge branch 'aw/pretty-trailers'
The %(trailers) formatter in "git log --format=..." now allows to optionally pick trailers selectively by keyword, show only values, etc. * aw/pretty-trailers: pretty: add support for separator option in %(trailers) strbuf: separate callback for strbuf_expand:ing literals pretty: add support for "valueonly" option in %(trailers) pretty: allow showing specific trailers pretty: single return path in %(trailers) handling pretty: allow %(trailers) options with explicit value doc: group pretty-format.txt placeholders descriptions
2 parents 54b469b + 0b691d8 commit 42977bf

File tree

7 files changed

+417
-135
lines changed

7 files changed

+417
-135
lines changed

‎Documentation/pretty-formats.txt

Lines changed: 152 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -102,120 +102,160 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
102102
+
103103
The placeholders are:
104104

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
112-
- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1]
113-
or linkgit:git-blame[1])
114-
- '%ae': author email
115-
- '%aE': author email (respecting .mailmap, see
116-
linkgit:git-shortlog[1] or linkgit:git-blame[1])
117-
- '%ad': author date (format respects --date= option)
118-
- '%aD': author date, RFC2822 style
119-
- '%ar': author date, relative
120-
- '%at': author date, UNIX timestamp
121-
- '%ai': author date, ISO 8601-like format
122-
- '%aI': author date, strict ISO 8601 format
123-
- '%cn': committer name
124-
- '%cN': committer name (respecting .mailmap, see
125-
linkgit:git-shortlog[1] or linkgit:git-blame[1])
126-
- '%ce': committer email
127-
- '%cE': committer email (respecting .mailmap, see
128-
linkgit:git-shortlog[1] or linkgit:git-blame[1])
129-
- '%cd': committer date (format respects --date= option)
130-
- '%cD': committer date, RFC2822 style
131-
- '%cr': committer date, relative
132-
- '%ct': committer date, UNIX timestamp
133-
- '%ci': committer date, ISO 8601-like format
134-
- '%cI': committer date, strict ISO 8601 format
135-
- '%d': ref names, like the --decorate option of linkgit:git-log[1]
136-
- '%D': ref names without the " (", ")" wrapping.
137-
- '%S': ref name given on the command line by which the commit was reached
138-
(like `git log --source`), only works with `git log`
139-
- '%e': encoding
140-
- '%s': subject
141-
- '%f': sanitized subject line, suitable for a filename
142-
- '%b': body
143-
- '%B': raw body (unwrapped subject and body)
105+
- Placeholders that expand to a single literal character:
106+
'%n':: newline
107+
'%%':: a raw '%'
108+
'%x00':: print a byte from a hex code
109+
110+
- Placeholders that affect formatting of later placeholders:
111+
'%Cred':: switch color to red
112+
'%Cgreen':: switch color to green
113+
'%Cblue':: switch color to blue
114+
'%Creset':: reset color
115+
'%C(...)':: color specification, as described under Values in the
116+
"CONFIGURATION FILE" section of linkgit:git-config[1]. By
117+
default, colors are shown only when enabled for log output
118+
(by `color.diff`, `color.ui`, or `--color`, and respecting
119+
the `auto` settings of the former if we are going to a
120+
terminal). `%C(auto,...)` is accepted as a historical
121+
synonym for the default (e.g., `%C(auto,red)`). Specifying
122+
`%C(always,...)` will show the colors even when color is
123+
not otherwise enabled (though consider just using
124+
`--color=always` to enable color for the whole output,
125+
including this format and anything else git might color).
126+
`auto` alone (i.e. `%C(auto)`) will turn on auto coloring
127+
on the next placeholders until the color is switched
128+
again.
129+
'%m':: left (`<`), right (`>`) or boundary (`-`) mark
130+
'%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of
131+
linkgit:git-shortlog[1].
132+
'%<(<N>[,trunc|ltrunc|mtrunc])':: make the next placeholder take at
133+
least N columns, padding spaces on
134+
the right if necessary. Optionally
135+
truncate at the beginning (ltrunc),
136+
the middle (mtrunc) or the end
137+
(trunc) if the output is longer than
138+
N columns. Note that truncating
139+
only works correctly with N >= 2.
140+
'%<|(<N>)':: make the next placeholder take at least until Nth
141+
columns, padding spaces on the right if necessary
142+
'%>(<N>)', '%>|(<N>)':: similar to '%<(<N>)', '%<|(<N>)' respectively,
143+
but padding spaces on the left
144+
'%>>(<N>)', '%>>|(<N>)':: similar to '%>(<N>)', '%>|(<N>)'
145+
respectively, except that if the next
146+
placeholder takes more spaces than given and
147+
there are spaces on its left, use those
148+
spaces
149+
'%><(<N>)', '%><|(<N>)':: similar to '%<(<N>)', '%<|(<N>)'
150+
respectively, but padding both sides
151+
(i.e. the text is centered)
152+
153+
- Placeholders that expand to information extracted from the commit:
154+
'%H':: commit hash
155+
'%h':: abbreviated commit hash
156+
'%T':: tree hash
157+
'%t':: abbreviated tree hash
158+
'%P':: parent hashes
159+
'%p':: abbreviated parent hashes
160+
'%an':: author name
161+
'%aN':: author name (respecting .mailmap, see linkgit:git-shortlog[1]
162+
or linkgit:git-blame[1])
163+
'%ae':: author email
164+
'%aE':: author email (respecting .mailmap, see linkgit:git-shortlog[1]
165+
or linkgit:git-blame[1])
166+
'%ad':: author date (format respects --date= option)
167+
'%aD':: author date, RFC2822 style
168+
'%ar':: author date, relative
169+
'%at':: author date, UNIX timestamp
170+
'%ai':: author date, ISO 8601-like format
171+
'%aI':: author date, strict ISO 8601 format
172+
'%cn':: committer name
173+
'%cN':: committer name (respecting .mailmap, see
174+
linkgit:git-shortlog[1] or linkgit:git-blame[1])
175+
'%ce':: committer email
176+
'%cE':: committer email (respecting .mailmap, see
177+
linkgit:git-shortlog[1] or linkgit:git-blame[1])
178+
'%cd':: committer date (format respects --date= option)
179+
'%cD':: committer date, RFC2822 style
180+
'%cr':: committer date, relative
181+
'%ct':: committer date, UNIX timestamp
182+
'%ci':: committer date, ISO 8601-like format
183+
'%cI':: committer date, strict ISO 8601 format
184+
'%d':: ref names, like the --decorate option of linkgit:git-log[1]
185+
'%D':: ref names without the " (", ")" wrapping.
186+
'%S':: ref name given on the command line by which the commit was reached
187+
(like `git log --source`), only works with `git log`
188+
'%e':: encoding
189+
'%s':: subject
190+
'%f':: sanitized subject line, suitable for a filename
191+
'%b':: body
192+
'%B':: raw body (unwrapped subject and body)
144193
ifndef::git-rev-list[]
145-
- '%N': commit notes
194+
'%N':: commit notes
146195
endif::git-rev-list[]
147-
- '%GG': raw verification message from GPG for a signed commit
148-
- '%G?': show "G" for a good (valid) signature,
149-
"B" for a bad signature,
150-
"U" for a good signature with unknown validity,
151-
"X" for a good signature that has expired,
152-
"Y" for a good signature made by an expired key,
153-
"R" for a good signature made by a revoked key,
154-
"E" if the signature cannot be checked (e.g. missing key)
155-
and "N" for no signature
156-
- '%GS': show the name of the signer for a signed commit
157-
- '%GK': show the key used to sign a signed commit
158-
- '%GF': show the fingerprint of the key used to sign a signed commit
159-
- '%GP': show the fingerprint of the primary key whose subkey was used
160-
to sign a signed commit
161-
- '%gD': reflog selector, e.g., `refs/stash@{1}` or
162-
`refs/stash@{2 minutes ago`}; the format follows the rules described
163-
for the `-g` option. The portion before the `@` is the refname as
164-
given on the command line (so `git log -g refs/heads/master` would
165-
yield `refs/heads/master@{0}`).
166-
- '%gd': shortened reflog selector; same as `%gD`, but the refname
167-
portion is shortened for human readability (so `refs/heads/master`
168-
becomes just `master`).
169-
- '%gn': reflog identity name
170-
- '%gN': reflog identity name (respecting .mailmap, see
171-
linkgit:git-shortlog[1] or linkgit:git-blame[1])
172-
- '%ge': reflog identity email
173-
- '%gE': reflog identity email (respecting .mailmap, see
174-
linkgit:git-shortlog[1] or linkgit:git-blame[1])
175-
- '%gs': reflog subject
176-
- '%Cred': switch color to red
177-
- '%Cgreen': switch color to green
178-
- '%Cblue': switch color to blue
179-
- '%Creset': reset color
180-
- '%C(...)': color specification, as described under Values in the
181-
"CONFIGURATION FILE" section of linkgit:git-config[1].
182-
By default, colors are shown only when enabled for log output (by
183-
`color.diff`, `color.ui`, or `--color`, and respecting the `auto`
184-
settings of the former if we are going to a terminal). `%C(auto,...)`
185-
is accepted as a historical synonym for the default (e.g.,
186-
`%C(auto,red)`). Specifying `%C(always,...)` will show the colors
187-
even when color is not otherwise enabled (though consider
188-
just using `--color=always` to enable color for the whole output,
189-
including this format and anything else git might color). `auto`
190-
alone (i.e. `%C(auto)`) will turn on auto coloring on the next
191-
placeholders until the color is switched again.
192-
- '%m': left (`<`), right (`>`) or boundary (`-`) mark
193-
- '%n': newline
194-
- '%%': a raw '%'
195-
- '%x00': print a byte from a hex code
196-
- '%w([<w>[,<i1>[,<i2>]]])': switch line wrapping, like the -w option of
197-
linkgit:git-shortlog[1].
198-
- '%<(<N>[,trunc|ltrunc|mtrunc])': make the next placeholder take at
199-
least N columns, padding spaces on the right if necessary.
200-
Optionally truncate at the beginning (ltrunc), the middle (mtrunc)
201-
or the end (trunc) if the output is longer than N columns.
202-
Note that truncating only works correctly with N >= 2.
203-
- '%<|(<N>)': make the next placeholder take at least until Nth
204-
columns, padding spaces on the right if necessary
205-
- '%>(<N>)', '%>|(<N>)': similar to '%<(<N>)', '%<|(<N>)'
206-
respectively, but padding spaces on the left
207-
- '%>>(<N>)', '%>>|(<N>)': similar to '%>(<N>)', '%>|(<N>)'
208-
respectively, except that if the next placeholder takes more spaces
209-
than given and there are spaces on its left, use those spaces
210-
- '%><(<N>)', '%><|(<N>)': similar to '%<(<N>)', '%<|(<N>)'
211-
respectively, but padding both sides (i.e. the text is centered)
212-
- %(trailers[:options]): display the trailers of the body as interpreted
213-
by linkgit:git-interpret-trailers[1]. The `trailers` string may be
214-
followed by a colon and zero or more comma-separated options. If the
215-
`only` option is given, omit non-trailer lines from the trailer block.
216-
If the `unfold` option is given, behave as if interpret-trailer's
217-
`--unfold` option was given. E.g., `%(trailers:only,unfold)` to do
218-
both.
196+
'%GG':: raw verification message from GPG for a signed commit
197+
'%G?':: show "G" for a good (valid) signature,
198+
"B" for a bad signature,
199+
"U" for a good signature with unknown validity,
200+
"X" for a good signature that has expired,
201+
"Y" for a good signature made by an expired key,
202+
"R" for a good signature made by a revoked key,
203+
"E" if the signature cannot be checked (e.g. missing key)
204+
and "N" for no signature
205+
'%GS':: show the name of the signer for a signed commit
206+
'%GK':: show the key used to sign a signed commit
207+
'%GF':: show the fingerprint of the key used to sign a signed commit
208+
'%GP':: show the fingerprint of the primary key whose subkey was used
209+
to sign a signed commit
210+
'%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2
211+
minutes ago`}; the format follows the rules described for the
212+
`-g` option. The portion before the `@` is the refname as
213+
given on the command line (so `git log -g refs/heads/master`
214+
would yield `refs/heads/master@{0}`).
215+
'%gd':: shortened reflog selector; same as `%gD`, but the refname
216+
portion is shortened for human readability (so
217+
`refs/heads/master` becomes just `master`).
218+
'%gn':: reflog identity name
219+
'%gN':: reflog identity name (respecting .mailmap, see
220+
linkgit:git-shortlog[1] or linkgit:git-blame[1])
221+
'%ge':: reflog identity email
222+
'%gE':: reflog identity email (respecting .mailmap, see
223+
linkgit:git-shortlog[1] or linkgit:git-blame[1])
224+
'%gs':: reflog subject
225+
'%(trailers[:options])':: display the trailers of the body as
226+
interpreted by
227+
linkgit:git-interpret-trailers[1]. The
228+
`trailers` string may be followed by a colon
229+
and zero or more comma-separated options:
230+
** 'key=<K>': only show trailers with specified key. Matching is done
231+
case-insensitively and trailing colon is optional. If option is
232+
given multiple times trailer lines matching any of the keys are
233+
shown. This option automatically enables the `only` option so that
234+
non-trailer lines in the trailer block are hidden. If that is not
235+
desired it can be disabled with `only=false`. E.g.,
236+
`%(trailers:key=Reviewed-by)` shows trailer lines with key
237+
`Reviewed-by`.
238+
** 'only[=val]': select whether non-trailer lines from the trailer
239+
block should be included. The `only` keyword may optionally be
240+
followed by an equal sign and one of `true`, `on`, `yes` to omit or
241+
`false`, `off`, `no` to show the non-trailer lines. If option is
242+
given without value it is enabled. If given multiple times the last
243+
value is used.
244+
** 'separator=<SEP>': specify a separator inserted between trailer
245+
lines. When this option is not given each trailer line is
246+
terminated with a line feed character. The string SEP may contain
247+
the literal formatting codes described above. To use comma as
248+
separator one must use `%x2C` as it would otherwise be parsed as
249+
next option. If separator option is given multiple times only the
250+
last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )`
251+
shows all trailer lines whose key is "Ticket" separated by a comma
252+
and a space.
253+
** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold`
254+
option was given. In same way as to for `only` it can be followed
255+
by an equal sign and explicit value. E.g.,
256+
`%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
257+
** 'valueonly[=val]': skip over the key part of the trailer line and only
258+
show the value part. Also this optionally allows explicit value.
219259

220260
NOTE: Some placeholders may depend on other options given to the
221261
revision traversal engine. For example, the `%g*` reflog options will

0 commit comments

Comments
 (0)