Show More
@@ -1,174 +1,174 b'' | |||||
1 | It is common for machines (as opposed to humans) to consume Mercurial. |
|
1 | It is common for machines (as opposed to humans) to consume Mercurial. | |
2 | This help topic describes some of the considerations for interfacing |
|
2 | This help topic describes some of the considerations for interfacing | |
3 | machines with Mercurial. |
|
3 | machines with Mercurial. | |
4 |
|
4 | |||
5 | Choosing an Interface |
|
5 | Choosing an Interface | |
6 | ===================== |
|
6 | ===================== | |
7 |
|
7 | |||
8 | Machines have a choice of several methods to interface with Mercurial. |
|
8 | Machines have a choice of several methods to interface with Mercurial. | |
9 | These include: |
|
9 | These include: | |
10 |
|
10 | |||
11 | - Executing the ``hg`` process |
|
11 | - Executing the ``hg`` process | |
12 | - Querying a HTTP server |
|
12 | - Querying a HTTP server | |
13 | - Calling out to a command server |
|
13 | - Calling out to a command server | |
14 |
|
14 | |||
15 | Executing ``hg`` processes is very similar to how humans interact with |
|
15 | Executing ``hg`` processes is very similar to how humans interact with | |
16 | Mercurial in the shell. It should already be familiar to you. |
|
16 | Mercurial in the shell. It should already be familiar to you. | |
17 |
|
17 | |||
18 | :hg:`serve` can be used to start a server. By default, this will start |
|
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 |
|
19 | a "hgweb" HTTP server. This HTTP server has support for machine-readable | |
20 | output, such as JSON. For more, see :hg:`help hgweb`. |
|
20 | output, such as JSON. For more, see :hg:`help hgweb`. | |
21 |
|
21 | |||
22 | :hg:`serve` can also start a "command server." Clients can connect |
|
22 | :hg:`serve` can also start a "command server." Clients can connect | |
23 | to this server and issue Mercurial commands over a special protocol. |
|
23 | to this server and issue Mercurial commands over a special protocol. | |
24 | For more details on the command server, including links to client |
|
24 | For more details on the command server, including links to client | |
25 | libraries, see https://mercurial.selenic.com/wiki/CommandServer. |
|
25 | libraries, see https://mercurial.selenic.com/wiki/CommandServer. | |
26 |
|
26 | |||
27 | :hg:`serve` based interfaces (the hgweb and command servers) have the |
|
27 | :hg:`serve` based interfaces (the hgweb and command servers) have the | |
28 | advantage over simple ``hg`` process invocations in that they are |
|
28 | advantage over simple ``hg`` process invocations in that they are | |
29 | likely more efficient. This is because there is significant overhead |
|
29 | likely more efficient. This is because there is significant overhead | |
30 | to spawn new Python processes. |
|
30 | to spawn new Python processes. | |
31 |
|
31 | |||
32 | .. tip:: |
|
32 | .. tip:: | |
33 |
|
33 | |||
34 | If you need to invoke several ``hg`` processes in short order and/or |
|
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 |
|
35 | performance is important to you, use of a server-based interface | |
36 | is highly recommended. |
|
36 | is highly recommended. | |
37 |
|
37 | |||
38 | Environment Variables |
|
38 | Environment Variables | |
39 | ===================== |
|
39 | ===================== | |
40 |
|
40 | |||
41 | As documented in :hg:`help environment`, various environment variables |
|
41 | As documented in :hg:`help environment`, various environment variables | |
42 | influence the operation of Mercurial. The following are particularly |
|
42 | influence the operation of Mercurial. The following are particularly | |
43 | relevant for machines consuming Mercurial: |
|
43 | relevant for machines consuming Mercurial: | |
44 |
|
44 | |||
45 | HGPLAIN |
|
45 | HGPLAIN | |
46 | If not set, Mercurial's output could be influenced by configuration |
|
46 | If not set, Mercurial's output could be influenced by configuration | |
47 | settings that impact its encoding, verbose mode, localization, etc. |
|
47 | settings that impact its encoding, verbose mode, localization, etc. | |
48 |
|
48 | |||
49 | It is highly recommended for machines to set this variable when |
|
49 | It is highly recommended for machines to set this variable when | |
50 | invoking ``hg`` processes. |
|
50 | invoking ``hg`` processes. | |
51 |
|
51 | |||
52 | HGENCODING |
|
52 | HGENCODING | |
53 | If not set, the locale used by Mercurial will be detected from the |
|
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 |
|
54 | environment. If the determined locale does not support display of | |
55 | certain characters, Mercurial may render these character sequences |
|
55 | certain characters, Mercurial may render these character sequences | |
56 | incorrectly (often by using "?" as a placeholder for invalid |
|
56 | incorrectly (often by using "?" as a placeholder for invalid | |
57 | characters in the current locale). |
|
57 | characters in the current locale). | |
58 |
|
58 | |||
59 | Explcitly setting this environment variable is a good practice to |
|
59 | Explicitly setting this environment variable is a good practice to | |
60 | guarantee consistent results. "utf-8" is a good choice on UNIX-like |
|
60 | guarantee consistent results. "utf-8" is a good choice on UNIX-like | |
61 | environments. |
|
61 | environments. | |
62 |
|
62 | |||
63 | HGRCPATH |
|
63 | HGRCPATH | |
64 | If not set, Mercurial will inherit config options from config files |
|
64 | If not set, Mercurial will inherit config options from config files | |
65 | using the process described in :hg:`help config`. This includes |
|
65 | using the process described in :hg:`help config`. This includes | |
66 | inheriting user or system-wide config files. |
|
66 | inheriting user or system-wide config files. | |
67 |
|
67 | |||
68 | When utmost control over the Mercurial configuration is desired, the |
|
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 |
|
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 |
|
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 |
|
71 | null device (often ``/dev/null``) to bypass loading of any user or | |
72 | system config files. Note that these approaches can have unintended |
|
72 | system config files. Note that these approaches can have unintended | |
73 | consequences, as the user and system config files often define things |
|
73 | consequences, as the user and system config files often define things | |
74 | like the username and extensions that may be required to interface |
|
74 | like the username and extensions that may be required to interface | |
75 | with a repository. |
|
75 | with a repository. | |
76 |
|
76 | |||
77 | Consuming Command Output |
|
77 | Consuming Command Output | |
78 | ======================== |
|
78 | ======================== | |
79 |
|
79 | |||
80 | It is common for machines to need to parse the output of Mercurial |
|
80 | It is common for machines to need to parse the output of Mercurial | |
81 | commands for relevant data. This section describes the various |
|
81 | commands for relevant data. This section describes the various | |
82 | techniques for doing so. |
|
82 | techniques for doing so. | |
83 |
|
83 | |||
84 | Parsing Raw Command Output |
|
84 | Parsing Raw Command Output | |
85 | -------------------------- |
|
85 | -------------------------- | |
86 |
|
86 | |||
87 | Likely the simplest and most effective solution for consuming command |
|
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 |
|
88 | output is to simply invoke ``hg`` commands as you would as a user and | |
89 | parse their output. |
|
89 | parse their output. | |
90 |
|
90 | |||
91 | The output of many commands can easily be parsed with tools like |
|
91 | The output of many commands can easily be parsed with tools like | |
92 | ``grep``, ``sed``, and ``awk``. |
|
92 | ``grep``, ``sed``, and ``awk``. | |
93 |
|
93 | |||
94 | A potential downside with parsing command output is that the output |
|
94 | A potential downside with parsing command output is that the output | |
95 | of commands can change when Mercurial is upgraded. While Mercurial |
|
95 | of commands can change when Mercurial is upgraded. While Mercurial | |
96 | does generally strive for strong backwards compatibility, command |
|
96 | does generally strive for strong backwards compatibility, command | |
97 | output does occasionally change. Having tests for your automated |
|
97 | output does occasionally change. Having tests for your automated | |
98 | interactions with ``hg`` commands is generally recommended, but is |
|
98 | interactions with ``hg`` commands is generally recommended, but is | |
99 | even more important when raw command output parsing is involved. |
|
99 | even more important when raw command output parsing is involved. | |
100 |
|
100 | |||
101 | Using Templates to Control Output |
|
101 | Using Templates to Control Output | |
102 | --------------------------------- |
|
102 | --------------------------------- | |
103 |
|
103 | |||
104 | Many ``hg`` commands support templatized output via the |
|
104 | Many ``hg`` commands support templatized output via the | |
105 | ``-T/--template`` argument. For more, see :hg:`help templates`. |
|
105 | ``-T/--template`` argument. For more, see :hg:`help templates`. | |
106 |
|
106 | |||
107 | Templates are useful for explicitly controlling output so that |
|
107 | Templates are useful for explicitly controlling output so that | |
108 | you get exactly the data you want formatted how you want it. For |
|
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 |
|
109 | example, ``log -T {node}\n`` can be used to print a newline | |
110 | delimited list of changeset nodes instead of a human-tailored |
|
110 | delimited list of changeset nodes instead of a human-tailored | |
111 | output containing authors, dates, descriptions, etc. |
|
111 | output containing authors, dates, descriptions, etc. | |
112 |
|
112 | |||
113 | .. tip:: |
|
113 | .. tip:: | |
114 |
|
114 | |||
115 | If parsing raw command output is too complicated, consider |
|
115 | If parsing raw command output is too complicated, consider | |
116 | using templates to make your life easier. |
|
116 | using templates to make your life easier. | |
117 |
|
117 | |||
118 | The ``-T/--template`` argument allows specifying pre-defined styles. |
|
118 | The ``-T/--template`` argument allows specifying pre-defined styles. | |
119 | Mercurial ships with the machine-readable styles ``json`` and ``xml``, |
|
119 | Mercurial ships with the machine-readable styles ``json`` and ``xml``, | |
120 | which provide JSON and XML output, respectively. These are useful for |
|
120 | which provide JSON and XML output, respectively. These are useful for | |
121 | producing output that is machine readable as-is. |
|
121 | producing output that is machine readable as-is. | |
122 |
|
122 | |||
123 | .. important:: |
|
123 | .. important:: | |
124 |
|
124 | |||
125 | The ``json`` and ``xml`` styles are considered experimental. While |
|
125 | The ``json`` and ``xml`` styles are considered experimental. While | |
126 | they may be attractive to use for easily obtaining machine-readable |
|
126 | they may be attractive to use for easily obtaining machine-readable | |
127 | output, their behavior may change in subsequent versions. |
|
127 | output, their behavior may change in subsequent versions. | |
128 |
|
128 | |||
129 | These styles may also exhibit unexpected results when dealing with |
|
129 | These styles may also exhibit unexpected results when dealing with | |
130 | certain encodings. Mercurial treats things like filenames as a |
|
130 | certain encodings. Mercurial treats things like filenames as a | |
131 | series of bytes and normalizing certain byte sequences to JSON |
|
131 | series of bytes and normalizing certain byte sequences to JSON | |
132 | or XML with certain encoding settings can lead to surprises. |
|
132 | or XML with certain encoding settings can lead to surprises. | |
133 |
|
133 | |||
134 | Command Server Output |
|
134 | Command Server Output | |
135 | --------------------- |
|
135 | --------------------- | |
136 |
|
136 | |||
137 | If using the command server to interact with Mercurial, you are likely |
|
137 | If using the command server to interact with Mercurial, you are likely | |
138 | using an existing library/API that abstracts implementation details of |
|
138 | using an existing library/API that abstracts implementation details of | |
139 | the command server. If so, this interface layer may perform parsing for |
|
139 | the command server. If so, this interface layer may perform parsing for | |
140 | you, saving you the work of implementing it yourself. |
|
140 | you, saving you the work of implementing it yourself. | |
141 |
|
141 | |||
142 | Output Verbosity |
|
142 | Output Verbosity | |
143 | ---------------- |
|
143 | ---------------- | |
144 |
|
144 | |||
145 | Commands often have varying output verbosity, even when machine |
|
145 | Commands often have varying output verbosity, even when machine | |
146 | readable styles are being used (e.g. ``-T json``). Adding |
|
146 | readable styles are being used (e.g. ``-T json``). Adding | |
147 | ``-v/--verbose`` and ``--debug`` to the command's arguments can |
|
147 | ``-v/--verbose`` and ``--debug`` to the command's arguments can | |
148 | increase the amount of data exposed by Mercurial. |
|
148 | increase the amount of data exposed by Mercurial. | |
149 |
|
149 | |||
150 | An alternate way to get the data you need is by explicitly specifying |
|
150 | An alternate way to get the data you need is by explicitly specifying | |
151 | a template. |
|
151 | a template. | |
152 |
|
152 | |||
153 | Other Topics |
|
153 | Other Topics | |
154 | ============ |
|
154 | ============ | |
155 |
|
155 | |||
156 | revsets |
|
156 | revsets | |
157 | Revisions sets is a functional query language for selecting a set |
|
157 | Revisions sets is a functional query language for selecting a set | |
158 | of revisions. Think of it as SQL for Mercurial repositories. Revsets |
|
158 | of revisions. Think of it as SQL for Mercurial repositories. Revsets | |
159 | are useful for querying repositories for specific data. |
|
159 | are useful for querying repositories for specific data. | |
160 |
|
160 | |||
161 | See :hg:`help revsets` for more. |
|
161 | See :hg:`help revsets` for more. | |
162 |
|
162 | |||
163 | share extension |
|
163 | share extension | |
164 | The ``share`` extension provides functionality for sharing |
|
164 | The ``share`` extension provides functionality for sharing | |
165 | repository data across several working copies. It can even |
|
165 | repository data across several working copies. It can even | |
166 | automatically "pool" storage for logically related repositories when |
|
166 | automatically "pool" storage for logically related repositories when | |
167 | cloning. |
|
167 | cloning. | |
168 |
|
168 | |||
169 | Configuring the ``share`` extension can lead to significant resource |
|
169 | Configuring the ``share`` extension can lead to significant resource | |
170 | utilization reduction, particularly around disk space and the |
|
170 | utilization reduction, particularly around disk space and the | |
171 | network. This is especially true for continuous integration (CI) |
|
171 | network. This is especially true for continuous integration (CI) | |
172 | environments. |
|
172 | environments. | |
173 |
|
173 | |||
174 | See :hg:`help -e share` for more. |
|
174 | See :hg:`help -e share` for more. |
General Comments 0
You need to be logged in to leave comments.
Login now