Mercurial > hg
view mercurial/helptext/templates.txt @ 50745:3338c6ffdaa3 stable
rust-revlog: using constant in test
Always better
author | Georges Racinet <georges.racinet@octobus.net> |
---|---|
date | Thu, 06 Jul 2023 11:43:26 +0200 |
parents | 2e017696181f |
children |
line wrap: on
line source
Mercurial allows you to customize output of commands through templates. You can either pass in a template or select an existing template-style from the command line, via the --template option. You can customize output for any "log-like" command: log, outgoing, incoming, tip, parents, and heads. Some built-in styles are packaged with Mercurial. These can be listed with :hg:`log --template list`. Example usage:: $ hg log -r1.0::1.1 --template changelog A template is a piece of text, with markup to invoke variable expansion:: $ hg log -r1 --template "{node}\n" b56ce7b07c52de7d5fd79fb89701ea538af65746 Keywords ======== 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: .. keywordsmarker 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 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:: $ hg tip --template "{date|isodate}\n" 2008-08-21 18:22 +0000 Filters ======= List of filters: .. filtersmarker Note that a filter is nothing more than a function call, i.e. ``expr|filter`` is equivalent to ``filter(expr)``. Functions ========= In addition to filters, there are some basic built-in functions: .. functionsmarker Operators ========= We provide a limited set of infix arithmetic operations on integers:: + for addition - for subtraction * for multiplication / for floor division (division rounded to integer nearest -infinity) Division fulfills the law x = x / y + mod(x, y). Also, for any expression that returns a list, there is a list operator:: expr % "{template}" 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'...'``. The dot operator can be used as a shorthand for accessing a sub item: - ``expr.member`` is roughly equivalent to ``expr % '{member}'`` if ``expr`` returns a non-list/dict. The returned value is not stringified. - ``dict.key`` is identical to ``get(dict, 'key')``. Aliases ======= 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()``. It's also possible to specify complete template strings, using the ``templates`` section. The syntax used is the general template string syntax. For example, :: [templates] nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n" defines a template, ``nodedate``, which can be called like:: $ hg log -r . -Tnodedate A template defined in ``templates`` section can also be referenced from another template:: $ hg log -r . -T "{rev} {nodedate}" but be aware that the keywords cannot be overridden by templates. For example, a template defined as ``templates.rev`` cannot be referenced as ``{rev}``. A template defined in ``templates`` section may have sub templates which are inserted before/after/between items:: [templates] myjson = ' {dict(rev, node|short)|json}' myjson:docheader = '\{\n' myjson:docfooter = '\n}\n' myjson:separator = ',\n' Examples ======== 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" - Join the list of files ending with ".py" with a ", ":: $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n" - Separate non-empty arguments by a " ":: $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n" - Modify each line of a commit description:: $ hg log --template "{splitlines(desc) % '**** {line}\n'}" - Format date:: $ hg log -r 0 --template "{date(date, '%Y')}\n" - Display date in UTC:: $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\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" - Display the contents of the 'extra' field, one per line:: $ hg log -r 0 --template "{join(extras, '\n')}\n" - Mark the active bookmark with '*':: $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n" - Find the previous release candidate tag, the distance and changes since the tag:: $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n" - Mark the working copy parent with '@':: $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" - Show details of parent revisions:: $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}" - Show only commit descriptions that start with "template":: $ hg log --template "{startswith('template', firstline(desc))}\n" - Print the first word of each line of a commit message:: $ hg log --template "{word(0, desc)}\n"