templates.txt
137 lines
| 3.6 KiB
| text/plain
|
TextLexer
|
r9999 | Mercurial allows you to customize output of commands through | ||
|
r21943 | templates. You can either pass in a template or select an existing | ||
template-style from the command line, via the --template option. | ||||
|
r9999 | |||
You can customize output for any "log-like" command: log, | ||||
|
r21945 | outgoing, incoming, tip, parents, and heads. | ||
|
r9999 | |||
|
r21946 | Some built-in styles are packaged with Mercurial. These can be listed | ||
with :hg:`log --template list`. Example usage:: | ||||
|
r9999 | |||
|
r21946 | $ hg log -r1.0::1.1 --template changelog | ||
|
r9999 | |||
A template is a piece of text, with markup to invoke variable | ||||
expansion:: | ||||
$ hg log -r1 --template "{node}\n" | ||||
b56ce7b07c52de7d5fd79fb89701ea538af65746 | ||||
Strings in curly braces are called keywords. The availability of | ||||
keywords depends on the exact context of the templater. These | ||||
keywords are usually available for templating a log-like command: | ||||
|
r13585 | .. keywordsmarker | ||
|
r9999 | |||
The "date" keyword does not produce human-readable output. If you | ||||
want to use a date in your output, you can use a filter to process | ||||
it. Filters are functions which return a string based on the input | ||||
|
r10759 | variable. Be sure to use the stringify filter first when you're | ||
applying a string-input filter to a list-like input variable. | ||||
You can also use a chain of filters to get the desired output:: | ||||
|
r9999 | |||
$ hg tip --template "{date|isodate}\n" | ||||
2008-08-21 18:22 +0000 | ||||
List of filters: | ||||
|
r13591 | .. filtersmarker | ||
|
r18465 | |||
Note that a filter is nothing more than a function call, i.e. | ||||
``expr|filter`` is equivalent to ``filter(expr)``. | ||||
In addition to filters, there are some basic built-in functions: | ||||
|
r18582 | - date(date[, fmt]) | ||
- fill(text[, width]) | ||||
- get(dict, key) | ||||
|
r18465 | - if(expr, then[, else]) | ||
|
r20531 | - ifcontains(expr, expr, then[, else]) | ||
|
r18465 | - ifeq(expr, expr, then[, else]) | ||
- join(list, sep) | ||||
- label(label, expr) | ||||
|
r22281 | - pad(text, width[, fillchar, right]) | ||
|
r20531 | - revset(query[, formatargs]) | ||
|
r18747 | - rstdoc(text, style) | ||
|
r20531 | - shortest(node) | ||
|
r21821 | - startswith(string, text) | ||
|
r19390 | - strip(text[, chars]) | ||
- sub(pat, repl, expr) | ||||
|
r19330 | |||
|
r21846 | - word(number, text[, separator]) | ||
|
r18465 | Also, for any expression that returns a list, there is a list operator: | ||
- expr % "{template}" | ||||
Some sample command line templates: | ||||
- Format lists, e.g. files:: | ||||
$ hg log -r 0 --template "files:\n{files % ' {file}\n'}" | ||||
- Join the list of files with a ", ":: | ||||
$ hg log -r 0 --template "files: {join(files, ', ')}\n" | ||||
|
r21820 | - Modify each line of a commit description:: | ||
$ hg log --template "{splitlines(desc) % '**** {line}\n'}" | ||||
|
r18465 | - Format date:: | ||
$ hg log -r 0 --template "{date(date, '%Y')}\n" | ||||
- Output the description set to a fill-width of 30:: | ||||
$ hg log -r 0 --template "{fill(desc, '30')}" | ||||
- Use a conditional to test for the default branch:: | ||||
$ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch', | ||||
'on branch {branch}')}\n" | ||||
- Append a newline if not empty:: | ||||
$ hg tip --template "{if(author, '{author}\n')}" | ||||
- Label the output for use with the color extension:: | ||||
$ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n" | ||||
- Invert the firstline filter, i.e. everything but the first line:: | ||||
$ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n" | ||||
|
r20016 | |||
- Display the contents of the 'extra' field, one per line:: | ||||
|
r20170 | $ hg log -r 0 --template "{join(extras, '\n')}\n" | ||
|
r20531 | |||
- Mark the current bookmark with '*':: | ||||
$ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, current, \"*\")} '}\n" | ||||
- Mark the working copy parent with '@':: | ||||
$ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" | ||||
|
r21821 | |||
- Show only commit descriptions that start with "template":: | ||||
$ hg log --template "{startswith(\"template\", firstline(desc))}\n" | ||||
|
r21846 | |||
- Print the first word of each line of a commit message:: | ||||
$ hg log --template "{word(\"0\", desc)}\n" | ||||