Template Usage
""""""""""""""

    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:
    
    :activebookmark: String. The active bookmark, if it is associated with the changeset.
    
    :author: String. The unmodified author of the changeset.
    
    :bisect: String. The changeset bisection status.
    
    :bookmarks: List of strings. Any bookmarks associated with the
      changeset. Also sets 'active', the name of the active bookmark.
    
    :branch: String. The name of the branch on which the changeset was
      committed.
    
    :branches: List of strings. The name of the branch on which the
      changeset was committed. Will be empty if the branch name was
      default. (DEPRECATED)
    
    :changessincelatesttag: Integer. All ancestors not in the latest tag.
    
    :children: List of strings. The children of the changeset.
    
    :currentbookmark: String. The active bookmark, if it is associated with the changeset.
      (DEPRECATED)
    
    :date: Date information. The date when the changeset was committed.
    
    :desc: String. The text of the changeset description.
    
    :diffstat: String. Statistics of changes with the following format:
      "modified files: +added/-removed lines"
    
    :envvars: A dictionary of environment variables. (EXPERIMENTAL)
    
    :extras: List of dicts with key, value entries of the 'extras'
      field of this changeset.
    
    :file_adds: List of strings. Files added by this changeset.
    
    :file_copies: List of strings. Files copied in this changeset with
      their sources.
    
    :file_copies_switch: List of strings. Like "file_copies" but displayed
      only if the --copied switch is set.
    
    :file_dels: List of strings. Files removed by this changeset.
    
    :file_mods: List of strings. Files modified by this changeset.
    
    :files: List of strings. All files modified, added, or removed by this
      changeset.
    
    :graphnode: String. The character representing the changeset node in an ASCII
      revision graph.
    
    :graphwidth: Integer. The width of the graph drawn by 'log --graph' or zero.
    
    :index: Integer. The current iteration of the loop. (0 indexed)
    
    :instabilities: List of strings. Evolution instabilities affecting the changeset.
      (EXPERIMENTAL)
    
    :latesttag: List of strings. The global tags on the most recent globally
      tagged ancestor of this changeset.  If no such tags exist, the list
      consists of the single string "null".
    
    :latesttagdistance: Integer. Longest path to the latest tag.
    
    :namespaces: Dict of lists. Names attached to this changeset per
      namespace.
    
    :node: String. The changeset identification hash, as a 40 hexadecimal
      digit string.
    
    :obsolete: String. Whether the changeset is obsolete. (EXPERIMENTAL)
    
    :p1node: String. The identification hash of the changeset's first parent,
      as a 40 digit hexadecimal string. If the changeset has no parents, all
      digits are 0.
    
    :p1rev: Integer. The repository-local revision number of the changeset's
      first parent, or -1 if the changeset has no parents.
    
    :p2node: String. The identification hash of the changeset's second
      parent, as a 40 digit hexadecimal string. If the changeset has no second
      parent, all digits are 0.
    
    :p2rev: Integer. The repository-local revision number of the changeset's
      second parent, or -1 if the changeset has no second parent.
    
    :parents: List of strings. The parents of the changeset in "rev:node"
      format. If the changeset has only one "natural" parent (the predecessor
      revision) nothing is shown.
    
    :peerurls: A dictionary of repository locations defined in the [paths] section
      of your configuration file.
    
    :phase: String. The changeset phase name.
    
    :phaseidx: Integer. The changeset phase index.
    
    :predecessors: Returns the list if the closest visible successors. (EXPERIMENTAL)
    
    :rev: Integer. The repository-local changeset revision number.
    
    :subrepos: List of strings. Updated subrepositories in the changeset.
    
    :successorssets: Returns a string of sets of successors for a changectx. Format used
      is: [ctx1, ctx2], [ctx3] if ctx has been splitted into ctx1 and ctx2
      while also diverged into ctx3. (EXPERIMENTAL)
    
    :succsandmarkers: Returns a list of dict for each final successor of ctx. The dict
      contains successors node id in "successors" keys and the list of
      obs-markers from ctx to the set of successors in "markers".
      (EXPERIMENTAL)
    
    :tags: List of strings. Any tags associated with the changeset.
    
    :termwidth: Integer. The width of the current terminal.
    
    :troubles: List of strings. Evolution troubles affecting the changeset.
      (DEPRECATED)
    
    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:
    
    :addbreaks: Any text. Add an XHTML "<br />" tag before the end of
      every line except the last.
    
    :age: Date. Returns a human-readable date/time difference between the
      given date/time and the current date/time.
    
    :basename: Any text. Treats the text as a path, and returns the last
      component of the path after splitting by the path separator
      (ignoring trailing separators). For example, "foo/bar/baz" becomes
      "baz" and "foo/bar//" becomes "bar".
    
    :count: List or text. Returns the length as an integer.
    
    :domain: Any text. Finds the first string that looks like an email
      address, and extracts just the domain component. Example: ``User
      <user@example.com>`` becomes ``example.com``.
    
    :email: Any text. Extracts the first string that looks like an email
      address. Example: ``User <user@example.com>`` becomes
      ``user@example.com``.
    
    :emailuser: Any text. Returns the user portion of an email address.
    
    :escape: Any text. Replaces the special XML/XHTML characters "&", "<"
      and ">" with XML entities, and filters out NUL characters.
    
    :fill68: Any text. Wraps the text to fit in 68 columns.
    
    :fill76: Any text. Wraps the text to fit in 76 columns.
    
    :firstline: Any text. Returns the first line of text.
    
    :hex: Any text. Convert a binary Mercurial node identifier into
      its long hexadecimal representation.
    
    :hgdate: Date. Returns the date as a pair of numbers: "1157407993
      25200" (Unix timestamp, timezone offset).
    
    :isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00
      +0200".
    
    :isodatesec: Date. Returns the date in ISO 8601 format, including
      seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date
      filter.
    
    :lower: Any text. Converts the text to lowercase.
    
    :nonempty: Any text. Returns '(none)' if the string is empty.
    
    :obfuscate: Any text. Returns the input text rendered as a sequence of
      XML entities.
    
    :person: Any text. Returns the name before an email address,
      interpreting it as per RFC 5322.
      
    
    :revescape: Any text. Escapes all "special" characters, except @.
      Forward slashes are escaped twice to prevent web servers from prematurely
      unescaping them. For example, "@foo bar/baz" becomes "@foo%20bar%252Fbaz".
    
    :rfc3339date: Date. Returns a date using the Internet date format
      specified in RFC 3339: "2009-08-18T13:00:13+02:00".
    
    :rfc822date: Date. Returns a date using the same format used in email
      headers: "Tue, 18 Aug 2009 13:00:13 +0200".
    
    :short: Changeset hash. Returns the short form of a changeset hash,
      i.e. a 12 hexadecimal digit string.
    
    :shortbisect: Any text. Treats `text` as a bisection status, and
      returns a single-character representing the status (G: good, B: bad,
      S: skipped, U: untested, I: ignored). Returns single space if `text`
      is not a valid bisection status.
    
    :shortdate: Date. Returns a date like "2006-09-18".
    
    :splitlines: Any text. Split text into a list of lines.
    
    :stringify: Any type. Turns the value into text by converting values into
      text and concatenating them.
    
    :stripdir: Treat the text as path and strip a directory level, if
      possible. For example, "foo" and "foo/bar" becomes "foo".
    
    :tabindent: Any text. Returns the text, with every non-empty line
      except the first starting with a tab character.
    
    :upper: Any text. Converts the text to uppercase.
    
    :urlescape: Any text. Escapes all "special" characters. For example,
      "foo bar" becomes "foo%20bar".
    
    :user: Any text. Returns a short representation of a user name or email
      address.
    
    :utf8: Any text. Converts from the local character encoding to UTF-8.
    
    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:
    
    :date(date[, fmt]): Format a date. See :hg:`help dates` for formatting
      strings. The default is a Unix date format, including the timezone:
      "Mon Sep 04 15:13:13 2006 0700".
    
    :dict([[key=]value...]): Construct a dict from key-value pairs. A key may be omitted if
      a value expression can provide an unambiguous name.
    
    :diff([includepattern [, excludepattern]]): Show a diff, optionally
      specifying files to include or exclude.
    
    :extdata(source): Show a text read from the specified extdata source. (EXPERIMENTAL)
    
    :files(pattern): All files of the current changeset matching the pattern. See
      :hg:`help patterns`.
    
    :fill(text[, width[, initialident[, hangindent]]]): Fill many
      paragraphs with optional indentation. See the "fill" filter.
    
    :formatnode(node): Obtain the preferred form of a changeset hash. (DEPRECATED)
    
    :get(dict, key): Get an attribute/key from an object. Some keywords
      are complex types. This function allows you to obtain the value of an
      attribute on these types.
    
    :if(expr, then[, else]): Conditionally execute based on the result of
      an expression.
    
    :ifcontains(needle, haystack, then[, else]): Conditionally execute based
      on whether the item "needle" is in "haystack".
    
    :ifeq(expr1, expr2, then[, else]): Conditionally execute based on
      whether 2 items are equivalent.
    
    :indent(text, indentchars[, firstline]): Indents all non-empty lines
      with the characters given in the indentchars string. An optional
      third parameter will override the indent for the first line only
      if present.
    
    :join(list, sep): Join items in a list with a delimiter.
    
    :label(label, expr): Apply a label to generated content. Content with
      a label applied can result in additional post-processing, such as
      automatic colorization.
    
    :latesttag([pattern]): The global tags matching the given pattern on the
      most recent globally tagged ancestor of this changeset.
      If no such tags exist, the "{tag}" template resolves to
      the string "null".
    
    :localdate(date[, tz]): Converts a date to the specified timezone.
      The default is local date.
    
    :max(iterable): Return the max of an iterable
    
    :min(iterable): Return the min of an iterable
    
    :mod(a, b): Calculate a mod b such that a / b + a mod b == a
    
    :obsfatedate(markers): Compute obsfate related information based on markers (EXPERIMENTAL)
    
    :obsfateoperations(markers): Compute obsfate related information based on markers (EXPERIMENTAL)
    
    :obsfateusers(markers): Compute obsfate related information based on markers (EXPERIMENTAL)
    
    :obsfateverb(successors): Compute obsfate related information based on successors (EXPERIMENTAL)
    
    :pad(text, width[, fillchar=' '[, left=False]]): Pad text with a
      fill character.
    
    :relpath(path): Convert a repository-absolute path into a filesystem path relative to
      the current working directory.
    
    :revset(query[, formatargs...]): Execute a revision set query. See
      :hg:`help revset`.
    
    :rstdoc(text, style): Format reStructuredText.
    
    :separate(sep, args): Add a separator between non-empty arguments.
    
    :shortest(node, minlength=4): Obtain the shortest representation of
      a node.
    
    :startswith(pattern, text): Returns the value from the "text" argument
      if it begins with the content from the "pattern" argument.
    
    :strip(text[, chars]): Strip characters from a string. By default,
      strips all leading and trailing whitespace.
    
    :sub(pattern, replacement, expression): Perform text substitution
      using regular expressions.
    
    :word(number, text[, separator]): Return the nth word from a string.
    
    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"