templates.txt
143 lines
| 4.1 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: | ||||
|
r24587 | .. functionsmarker | ||
|
r21846 | |||
|
r28040 | Also, for any expression that returns a list, there is a list operator:: | ||
|
r18465 | |||
|
r28040 | expr % "{template}" | ||
|
r18465 | |||
|
r28040 | As seen in the above example, ``{template}`` is interpreted as a template. | ||
To prevent it from being interpreted, you can use an escape character ``\{`` | ||||
or a raw string prefix, ``r'...'``. | ||||
|
r25596 | |||
|
r28957 | New keywords and functions can be defined in the ``templatealias`` section of | ||
a Mercurial configuration file:: | ||||
<alias> = <definition> | ||||
Arguments of the form `a1`, `a2`, etc. are substituted from the alias into | ||||
the definition. | ||||
For example, | ||||
:: | ||||
[templatealias] | ||||
r = rev | ||||
rn = "{r}:{node|short}" | ||||
leftpad(s, w) = pad(s, w, ' ', True) | ||||
defines two symbol aliases, ``r`` and ``rn``, and a function alias | ||||
``leftpad()``. | ||||
|
r18465 | 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" | ||||
|
r26128 | - Display date in UTC:: | ||
$ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n" | ||||
|
r18465 | - Output the description set to a fill-width of 30:: | ||
|
r25004 | $ hg log -r 0 --template "{fill(desc, 30)}" | ||
|
r18465 | |||
- 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 | |||
|
r25348 | - Mark the active bookmark with '*':: | ||
|
r20531 | |||
|
r25786 | $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n" | ||
|
r20531 | |||
|
r26485 | - Find the previous release candidate tag, the distance and changes since the tag:: | ||
$ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n" | ||||
|
r20531 | - Mark the working copy parent with '@':: | ||
$ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" | ||||
|
r21821 | |||
|
r26234 | - Show details of parent revisions:: | ||
$ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}" | ||||
|
r21821 | - Show only commit descriptions that start with "template":: | ||
|
r25786 | $ hg log --template "{startswith('template', firstline(desc))}\n" | ||
|
r21846 | |||
- Print the first word of each line of a commit message:: | ||||
|
r25004 | $ hg log --template "{word(0, desc)}\n" | ||