view mercurial/help/templates.txt @ 13038:670f4e98276d stable

checknlink: return False if .hgtmp file preexists (issue2517)

If os_link fails on Windows, errno is always errno.EINVAL,
so we can't really say if the testlink could not be created
because (a) the FS doesn't support hardlinks or (b) there
is a leaked .hgtmp file lying around from a previous crashed
run.

So let's err on the safe side, keep the code simple and assume
we can't detect hardlinks in both cases.

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.

:branches: String. 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"

:files: List of strings. All files modified, added, or removed by 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_mods: List of strings. Files modified by this changeset.

:file_dels: List of strings. Files removed by this changeset.

:node: String. The changeset identification hash, as a 40 hexadecimal
    digit string.

:parents: List of strings. The parents of the changeset.

:rev: Integer. The repository-local changeset revision number.

:tags: List of strings. Any tags associated with the changeset.

:latesttag: String. Most recent global tag in the ancestors of this
    changeset.

:latesttagdistance: Integer. Longest path to the latest tag.

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".

:stripdir: Treat the text as path and strip a directory level, if
    possible. For example, "foo" and "foo/bar" becomes "foo".

: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
    <[e-mail]>`` becomes ``example.com``.

:email: Any text. Extracts the first string that looks like an email
    address. Example: ``User <[e-mail]>`` becomes
    ``[e-mail]``.

:escape: Any text. Replaces the special XML/XHTML characters "&", "<"
    and ">" with XML entities.

:hex: Any text. Convert a binary Mercurial node identifier into
    its long hexadecimal representation.

: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.

:nonempty: Any text. Returns '(none)' if the string is empty.

: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.

:obfuscate: Any text. Returns the input text rendered as a sequence of
    XML entities.

:person: Any text. Returns the text before an email address.

:rfc822date: Date. Returns a date using the same format used in email
    headers: "Tue, 18 Aug 2009 13:00:13 +0200".

:rfc3339date: Date. Returns a date using the Internet date format
    specified in RFC 3339: "2009-08-18T13:00:13+02:00".

:short: Changeset hash. Returns the short form of a changeset hash,
    i.e. a 12 hexadecimal digit string.

: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.

: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 the user portion of an email address.