1 It is common for machines (as opposed to humans) to consume Mercurial.

     2 This help topic describes some of the considerations for interfacing

     3 machines with Mercurial.

     4 

     5 Choosing an Interface

     6 =====================

     7 

     8 Machines have a choice of several methods to interface with Mercurial.

     9 These include:

    10 

    11 - Executing the ``hg`` process

    12 - Querying a HTTP server

    13 - Calling out to a command server

    14 

    15 Executing ``hg`` processes is very similar to how humans interact with

    16 Mercurial in the shell. It should already be familar to you.

    17 

    18 :hg:`serve` can be used to start a server. By default, this will start

    19 a "hgweb" HTTP server. This HTTP server has support for machine-readable

    20 output, such as JSON. For more, see :hg:`help hgweb`.

    21 

    22 :hg:`serve` can also start a "command server." Clients can connect

    23 to this server and issue Mercurial commands over a special protocol.

    24 For more details on the command server, including links to client

    25 libraries, see https://mercurial.selenic.com/wiki/CommandServer.

    26 

    27 :hg:`serve` based interfaces (the hgweb and command servers) have the

    28 advantage over simple ``hg`` process invocations in that they are

    29 likely more efficient. This is because there is significant overhead

    30 to spawn new Python processes.

    31 

    32 .. tip::

    33 

    34    If you need to invoke several ``hg`` processes in short order and/or

    35    performance is important to you, use of a server-based interface

    36    is highly recommended.

    37 

    38 Environment Variables

    39 =====================

    40 

    41 As documented in :hg:`help environment`, various environment variables

    42 influence the operation of Mercurial. The following are particularly

    43 relevant for machines consuming Mercurial:

    44 

    45 HGPLAIN

    46     If not set, Mercurial's output could be influenced by configuration

    47     settings that impact its encoding, verbose mode, localization, etc.

    48 

    49     It is highly recommended for machines to set this variable when

    50     invoking ``hg`` processes.

    51 

    52 HGENCODING

    53    If not set, the locale used by Mercurial will be detected from the

    54    environment. If the determined locale does not support display of

    55    certain characters, Mercurial may render these character sequences

    56    incorrectly (often by using "?" as a placeholder for invalid

    57    characters in the current locale).

    58 

    59    Explcitly setting this environment variable is a good practice to

    60    guarantee consistent results. "utf-8" is a good choice on UNIX-like

    61    environments.

    62 

    63 HGRCPATH

    64     If not set, Mercurial will inherit config options from config files

    65     using the process described in :hg:`help config`. This includes

    66     inheriting user or system-wide config files.

    67 

    68     When utmost control over the Mercurial configuration is desired, the

    69     value of ``HGRCPATH`` can be set to an explicit file with known good

    70     configs. In rare cases, the value can be set to an empty file or the

    71     null device (often ``/dev/null``) to bypass loading of any user or

    72     system config files. Note that these approaches can have unintended

    73     consequences, as the user and system config files often define things

    74     like the username and extensions that may be required to interface

    75     with a repository.

    76 

    77 Consuming Command Output

    78 ========================

    79 

    80 It is common for machines to need to parse the output of Mercurial

    81 commands for relevant data. This section describes the various

    82 techniques for doing so.

    83 

    84 Parsing Raw Command Output

    85 --------------------------

    86 

    87 Likely the simplest and most effective solution for consuming command

    88 output is to simply invoke ``hg`` commands as you would as a user and

    89 parse their output.

    90 

    91 The output of many commands can easily be parsed with tools like

    92 ``grep``, ``sed``, and ``awk``.

    93 

    94 A potential downside with parsing command output is that the output

    95 of commands can change when Mercurial is upgraded. While Mercurial

    96 does generally strive for strong backwards compatibility, command

    97 output does occasionally change. Having tests for your automated

    98 interactions with ``hg`` commands is generally recommended, but is

    99 even more important when raw command output parsing is involved.

   100 

   101 Using Templates to Control Output

   102 ---------------------------------

   103 

   104 Many ``hg`` commands support templatized output via the

   105 ``-T/--template`` argument. For more, see :hg:`help templates`.

   106 

   107 Templates are useful for explicitly controlling output so that

   108 you get exactly the data you want formatted how you want it. For

   109 example, ``log -T {node}\n`` can be used to print a newline

   110 delimited list of changeset nodes instead of a human-tailored

   111 output containing authors, dates, descriptions, etc.

   112 

   113 .. tip::

   114 

   115    If parsing raw command output is too complicated, consider

   116    using templates to make your life easier.

   117 

   118 The ``-T/--template`` argument allows specifying pre-defined styles.

   119 Mercurial ships with the machine-readable styles ``json`` and ``xml``,

   120 which provide JSON and XML output, respectively. These are useful for

   121 producing output that is machine readable as-is.

   122 

   123 .. important::

   124 

   125    The ``json`` and ``xml`` styles are considered experimental. While

   126    they may be attractive to use for easily obtaining machine-readable

   127    output, their behavior may change in subsequent versions.

   128 

   129    These styles may also exhibit unexpected results when dealing with

   130    certain encodings. Mercurial treats things like filenames as a

   131    series of bytes and normalizing certain byte sequences to JSON

   132    or XML with certain encoding settings can lead to surprises.

   133 

   134 Command Server Output

   135 ---------------------

   136 

   137 If using the command server to interact with Mercurial, you are likely

   138 using an existing library/API that abstracts implementation details of

   139 the command server. If so, this interface layer may perform parsing for

   140 you, saving you the work of implementing it yourself.

   141 

   142 Output Verbosity

   143 ----------------

   144 

   145 Commands often have varying output verbosity, even when machine

   146 readable styles are being used (e.g. ``-T json``). Adding

   147 ``-v/--verbose`` and ``--debug`` to the command's arguments can

   148 increase the amount of data exposed by Mercurial.

   149 

   150 An alternate way to get the data you need is by explicitly specifying

   151 a template.

   152 

   153 Other Topics

   154 ============

   155 

   156 revsets

   157    Revisions sets is a functional query language for selecting a set

   158    of revisions. Think of it as SQL for Mercurial repositories. Revsets

   159    are useful for querying repositories for specific data.

   160 

   161    See :hg:`help revsets` for more.

   162 

   163 share extension

   164    The ``share`` extension provides functionality for sharing

   165    repository data across several working copies. It can even

   166    automatically "pool" storage for logically related repositories when

   167    cloning.

   168 

   169    Configuring the ``share`` extension can lead to significant resource

   170    utilization reduction, particularly around disk space and the

   171    network. This is especially true for continuous integration (CI)

   172    environments.

   173 

   174    See :hg:`help -e share` for more.