##// END OF EJS Templates
help: fix typo in scripting documentation
Wagner Bruna -
r26027:7b7e25a8 stable
parent child Browse files
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