diff options
Diffstat (limited to 'Documentation/pretty-formats.txt')
| -rw-r--r-- | Documentation/pretty-formats.txt | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt new file mode 100644 index 0000000000..d433d50f81 --- /dev/null +++ b/Documentation/pretty-formats.txt @@ -0,0 +1,261 @@ +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 or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +`git log --raw`. To get full object names in a raw diff format, +use `--no-abbrev`. + +* '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-like format +- '%aI': author date, strict 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 (format respects --date= option) +- '%cD': committer date, RFC2822 style +- '%cr': committer date, relative +- '%ct': committer date, UNIX timestamp +- '%ci': committer date, ISO 8601-like format +- '%cI': committer date, strict ISO 8601 format +- '%d': ref names, like the --decorate option of linkgit:git-log[1] +- '%D': ref names without the " (", ")" wrapping. +- '%e': encoding +- '%s': subject +- '%f': sanitized subject line, suitable for a filename +- '%b': body +- '%B': raw body (unwrapped subject and body) +ifndef::git-rev-list[] +- '%N': commit notes +endif::git-rev-list[] +- '%GG': raw verification message from GPG for a signed commit +- '%G?': show "G" for a good (valid) signature, + "B" for a bad signature, + "U" for a good signature with unknown validity, + "X" for a good signature that has expired, + "Y" for a good signature made by an expired key, + "R" for a good signature made by a revoked key, + "E" if the signature cannot be checked (e.g. missing key) + 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}` or + `refs/stash@{2 minutes ago`}; the format follows the rules described + for the `-g` option. The portion before the `@` is the refname as + given on the command line (so `git log -g refs/heads/master` would + yield `refs/heads/master@{0}`). +- '%gd': shortened reflog selector; same as `%gD`, but the refname + portion is shortened for human readability (so `refs/heads/master` + becomes just `master`). +- '%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 under Values in the + "CONFIGURATION FILE" section of linkgit:git-config[1]. + By default, colors are shown only when 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). `%C(auto,...)` + is accepted as a historical synonym for the default (e.g., + `%C(auto,red)`). Specifying `%C(always,...) will show the colors + even when color is not otherwise enabled (though consider + just using `--color=always` to enable color for the whole output, + including this format and anything else git might color). `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) +- %(trailers): display the trailers of the body as interpreted by + linkgit:git-interpret-trailers[1]. If the `:only` option is given, + omit non-trailer lines from the trailer block. If the `:unfold` + option is given, behave as if interpret-trailer's `--unfold` option + was given. E.g., `%(trailers:only:unfold)` to do both. + +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` and `%D` placeholders 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, all consecutive +line-feeds immediately preceding 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 +--------------------- |