Using Mercurial from scripts and automation
"""""""""""""""""""""""""""""""""""""""""""

    It is common for machines (as opposed to humans) to consume Mercurial.
    This help topic describes some of the considerations for interfacing
    machines with Mercurial.
    
    Choosing an Interface
    =====================
    
    Machines have a choice of several methods to interface with Mercurial.
    These include:
    
    - Executing the ``hg`` process
    - Querying a HTTP server
    - Calling out to a command server
    
    Executing ``hg`` processes is very similar to how humans interact with
    Mercurial in the shell. It should already be familiar to you.
    
    :hg:`serve` can be used to start a server. By default, this will start
    a "hgweb" HTTP server. This HTTP server has support for machine-readable
    output, such as JSON. For more, see :hg:`help hgweb`.
    
    :hg:`serve` can also start a "command server." Clients can connect
    to this server and issue Mercurial commands over a special protocol.
    For more details on the command server, including links to client
    libraries, see https://www.mercurial-scm.org/wiki/CommandServer.
    
    :hg:`serve` based interfaces (the hgweb and command servers) have the
    advantage over simple ``hg`` process invocations in that they are
    likely more efficient. This is because there is significant overhead
    to spawn new Python processes.
    
    .. tip::
    
       If you need to invoke several ``hg`` processes in short order and/or
       performance is important to you, use of a server-based interface
       is highly recommended.
    
    Environment Variables
    =====================
    
    As documented in :hg:`help environment`, various environment variables
    influence the operation of Mercurial. The following are particularly
    relevant for machines consuming Mercurial:
    
    HGPLAIN
        If not set, Mercurial's output could be influenced by configuration
        settings that impact its encoding, verbose mode, localization, etc.
    
        It is highly recommended for machines to set this variable when
        invoking ``hg`` processes.
    
    HGENCODING
        If not set, the locale used by Mercurial will be detected from the
        environment. If the determined locale does not support display of
        certain characters, Mercurial may render these character sequences
        incorrectly (often by using "?" as a placeholder for invalid
        characters in the current locale).
    
        Explicitly setting this environment variable is a good practice to
        guarantee consistent results. "utf-8" is a good choice on UNIX-like
        environments.
    
    HGRCPATH
        If not set, Mercurial will inherit config options from config files
        using the process described in :hg:`help config`. This includes
        inheriting user or system-wide config files.
    
        When utmost control over the Mercurial configuration is desired, the
        value of ``HGRCPATH`` can be set to an explicit file with known good
        configs. In rare cases, the value can be set to an empty file or the
        null device (often ``/dev/null``) to bypass loading of any user or
        system config files. Note that these approaches can have unintended
        consequences, as the user and system config files often define things
        like the username and extensions that may be required to interface
        with a repository.
    
    Consuming Command Output
    ========================
    
    It is common for machines to need to parse the output of Mercurial
    commands for relevant data. This section describes the various
    techniques for doing so.
    
    Parsing Raw Command Output
    --------------------------
    
    Likely the simplest and most effective solution for consuming command
    output is to simply invoke ``hg`` commands as you would as a user and
    parse their output.
    
    The output of many commands can easily be parsed with tools like
    ``grep``, ``sed``, and ``awk``.
    
    A potential downside with parsing command output is that the output
    of commands can change when Mercurial is upgraded. While Mercurial
    does generally strive for strong backwards compatibility, command
    output does occasionally change. Having tests for your automated
    interactions with ``hg`` commands is generally recommended, but is
    even more important when raw command output parsing is involved.
    
    Using Templates to Control Output
    ---------------------------------
    
    Many ``hg`` commands support templatized output via the
    ``-T/--template`` argument. For more, see :hg:`help templates`.
    
    Templates are useful for explicitly controlling output so that
    you get exactly the data you want formatted how you want it. For
    example, ``log -T {node}\n`` can be used to print a newline
    delimited list of changeset nodes instead of a human-tailored
    output containing authors, dates, descriptions, etc.
    
    .. tip::
    
       If parsing raw command output is too complicated, consider
       using templates to make your life easier.
    
    The ``-T/--template`` argument allows specifying pre-defined styles.
    Mercurial ships with the machine-readable styles ``json`` and ``xml``,
    which provide JSON and XML output, respectively. These are useful for
    producing output that is machine readable as-is.
    
    .. important::
    
       The ``json`` and ``xml`` styles are considered experimental. While
       they may be attractive to use for easily obtaining machine-readable
       output, their behavior may change in subsequent versions.
    
       These styles may also exhibit unexpected results when dealing with
       certain encodings. Mercurial treats things like filenames as a
       series of bytes and normalizing certain byte sequences to JSON
       or XML with certain encoding settings can lead to surprises.
    
    Command Server Output
    ---------------------
    
    If using the command server to interact with Mercurial, you are likely
    using an existing library/API that abstracts implementation details of
    the command server. If so, this interface layer may perform parsing for
    you, saving you the work of implementing it yourself.
    
    Output Verbosity
    ----------------
    
    Commands often have varying output verbosity, even when machine
    readable styles are being used (e.g. ``-T json``). Adding
    ``-v/--verbose`` and ``--debug`` to the command's arguments can
    increase the amount of data exposed by Mercurial.
    
    An alternate way to get the data you need is by explicitly specifying
    a template.
    
    Other Topics
    ============
    
    revsets
       Revisions sets is a functional query language for selecting a set
       of revisions. Think of it as SQL for Mercurial repositories. Revsets
       are useful for querying repositories for specific data.
    
       See :hg:`help revsets` for more.
    
    share extension
       The ``share`` extension provides functionality for sharing
       repository data across several working copies. It can even
       automatically "pool" storage for logically related repositories when
       cloning.
    
       Configuring the ``share`` extension can lead to significant resource
       utilization reduction, particularly around disk space and the
       network. This is especially true for continuous integration (CI)
       environments.
    
       See :hg:`help -e share` for more.