diff options
Diffstat (limited to 'Documentation/pretty-formats.adoc')
| -rw-r--r-- | Documentation/pretty-formats.adoc | 391 |
1 files changed, 391 insertions, 0 deletions
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc new file mode 100644 index 0000000000..9ed0417fc8 --- /dev/null +++ b/Documentation/pretty-formats.adoc @@ -0,0 +1,391 @@ +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 hashes 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` + + <hash> <title-line> ++ +This is designed to be as compact as possible. + +* `short` + + commit <hash> + Author: <author> + + <title-line> + +* `medium` + + commit <hash> + Author: <author> + Date: <author-date> + + <title-line> + + <full-commit-message> + +* `full` + + commit <hash> + Author: <author> + Commit: <committer> + + <title-line> + + <full-commit-message> + +* `fuller` + + commit <hash> + Author: <author> + AuthorDate: <author-date> + Commit: <committer> + CommitDate: <committer-date> + + <title-line> + + <full-commit-message> + +* `reference` + + <abbrev-hash> (<title-line>, <short-author-date>) ++ +This format is used to refer to another commit in a commit message and +is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default, +the date is formatted with `--date=short` unless another `--date` option +is explicitly specified. As with any `format:` with format +placeholders, its output is not affected by other options like +`--decorate` and `--walk-reflogs`. + +* `email` + + From <hash> <date> + From: <author> + Date: <author-date> + Subject: [PATCH] <title-line> + + <full-commit-message> + +* `mboxrd` ++ +Like `email`, but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren't +confused as starting a new commit. + +* `raw` ++ +The `raw` format shows the entire commit exactly as +stored in the commit object. Notably, the hashes 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:<format-string>` ++ +The `format:<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: + +- Placeholders that expand to a single literal character: +++%n++:: newline +++%%++:: a raw ++%++ +++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a + byte with the hexadecimal digits' value (we will call this + "literal formatting code" in the rest of this document). + +- Placeholders that affect formatting of later placeholders: +++%Cred++:: switch color to red +++%Cgreen++:: switch color to green +++%Cblue++:: switch color to blue +++%Creset++:: reset color +++%C(++_<spec>_++)++:: 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,++_<spec>_++)++ is accepted as a historical + synonym for the default (e.g., ++%C(auto,red)++). Specifying + ++%C(always,++_<spec>_++)++ 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 +++%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 column widths, padding spaces on + the right if necessary. Optionally + truncate (with ellipsis `..`) at the left (ltrunc) `..ft`, + the middle (mtrunc) `mi..le`, or the end + (trunc) `rig..`, if the output is longer than + _<n>_ columns. + Note 1: that truncating + only works correctly with _<n>_ >= 2. + Note 2: spaces around the _<n>_ and _<m>_ (see below) + values are optional. + Note 3: Emojis and other wide characters + will take two display columns, which may + over-run column boundaries. + Note 4: decomposed character combining marks + may be misplaced at padding boundaries. +++%<|(++_<m>_ ++)++:: make the next placeholder take at least until _<m>_ th + display column, padding spaces on the right if necessary. + Use negative _<m>_ values for column positions measured + from the right hand edge of the terminal window. +++%>(++_<n>_++)++:: +++%>|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++ respectively, + but padding spaces on the left +++%>>(++_<n>_++)++:: +++%>>|(++_<m>_++)++:: similar to ++%>(++_<n>_++)++, ++%>|(++_<m>_++)++ + respectively, except that if the next + placeholder takes more spaces than given and + there are spaces on its left, use those + spaces +++%><(++_<n>_++)++:: +++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++ + respectively, but padding both sides + (i.e. the text is centered) + +- Placeholders that expand to information extracted from the commit: ++%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]) ++%al+:: author email local-part (the part before the `@` sign) ++%aL+:: author local-part (see +%al+) 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 ++%as+:: author date, short format (`YYYY-MM-DD`) ++%ah+:: author date, human style (like the `--date=human` option of + linkgit:git-rev-list[1]) ++%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]) ++%cl+:: committer email local-part (the part before the `@` sign) ++%cL+:: committer local-part (see +%cl+) 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 ++%cs+:: committer date, short format (`YYYY-MM-DD`) ++%ch+:: committer date, human style (like the `--date=human` option of + linkgit:git-rev-list[1]) ++%d+:: ref names, like the --decorate option of linkgit:git-log[1] ++%D+:: ref names without the " (", ")" wrapping. +++%(decorate++`[:<option>,...]`++)++:: +ref names with custom decorations. The `decorate` string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (`%x2C`) and closing +parentheses (`%x29`), due to their role in the option syntax. ++ +** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+". +** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+". +** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}". +** `pointer=<value>`: Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}+->+{nbsp}". +** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}". + ++ +For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators: ++ +++%(decorate:prefix=,suffix=,tag=,separator= )++ + +++%(describe++`[:<option>,...]`++)++:: +human-readable name, like linkgit:git-describe[1]; empty string for +undescribable commits. The `describe` string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time. ++ +** `tags[=<bool-value>]`: Instead of only considering annotated tags, + consider lightweight tags as well. +** `abbrev=<number>`: Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. +** `match=<pattern>`: Only consider tags matching the given + `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix. +** `exclude=<pattern>`: Do not consider tags matching the given + `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix. + ++%S+:: ref name given on the command line by which the commit was reached + (like `git log --source`), only works with `git log` ++%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 ++%GF+:: show the fingerprint of the key used to sign a signed commit ++%GP+:: show the fingerprint of the primary key whose subkey was used + to sign a signed commit ++%GT+:: show the trust level for 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 +++%(trailers++`[:<option>,...]`++)++:: +display the trailers of the body as interpreted by +linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins. ++ +** `key=<key>`: only show trailers with specified <key>. Matching is done + case-insensitively and trailing colon is optional. If option is + given multiple times trailer lines matching any of the keys are + shown. This option automatically enables the `only` option so that + non-trailer lines in the trailer block are hidden. If that is not + desired it can be disabled with `only=false`. E.g., + +%(trailers:key=Reviewed-by)+ shows trailer lines with key + `Reviewed-by`. +** `only[=<bool>]`: select whether non-trailer lines from the trailer + block should be included. +** `separator=<sep>`: specify the separator inserted between trailer + lines. Defaults to a line feed character. The string <sep> may contain + the literal formatting codes described above. To use comma as + separator one must use `%x2C` as it would otherwise be parsed as + next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+ + shows all trailer lines whose key is "Ticket" separated by a comma + and a space. +** `unfold[=<bool>]`: make it behave as if interpret-trailer's `--unfold` + option was given. E.g., + +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines. +** `keyonly[=<bool>]`: only show the key part of the trailer. +** `valueonly[=<bool>]`: only show the value part of the trailer. +** `key_value_separator=<sep>`: specify the separator inserted between + the key and value of each trailer. Defaults to ": ". Otherwise it + shares the same semantics as `separator=<sep>` above. + +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. + +The boolean options accept an optional value `[=<bool-value>]`. The +values taken by `--type=bool` linkgit:git-config[1], like `yes` and `off`, +are all accepted. Giving a boolean option without `=<value>` is +equivalent to giving it with `=true`. + +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 +--------------------- |