docs/Development-Case

Help: templating

Template Usage

    Mercurial allows you to customize output of commands through templates.
    You can either pass in a template from the command line, via the
    --template option, or select an existing template-style (--style).

    You can customize output for any "log-like" command: log, outgoing,
    incoming, tip, parents, heads and glog.

    Four styles are packaged with Mercurial: default (the style used when no
    explicit preference is passed), compact, changelog, and xml. Usage:

      $ hg log -r1 --style changelog

    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:

    author        String. The unmodified author of the changeset.
    bisect        String. The changeset bisection status.
    bookmarks     List of strings. Any bookmarks associated with the
                  changeset.
    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.
    children      List of strings. The children of the changeset.
    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"
    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.
    latesttag     String. Most recent global tag in the ancestors of this
                  changeset.
    latesttagdistance
                  Integer. Longest path to the latest tag.
    node          String. The changeset identification hash, as a 40
                  hexadecimal digit string.
    phase         String. The changeset phase name.
    phaseidx      Integer. The changeset phase index.
    rev           Integer. The repository-local changeset revision number.
    tags          List of strings. Any tags associated with the changeset.

    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

    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".
    date          Date. Returns a date in a Unix date format, including the
                  timezone: "Mon Sep 04 15:13:13 2006 0700".
    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.
    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.
    localdate     Date. Converts a date to local date.
    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.
    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".
    stringify     Any type. Turns the value into text by converting values
                  into text and concatenating them.
    strip         Any text. Strips all leading and trailing whitespace.
    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 line except the first
                  starting with a tab character.
    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.