Mercurial > hg
comparison mercurial/helptext/scripting.txt @ 43632:2e017696181f
help: create packages for the help text
These files need to be loaded as resources with PyOxidizer, instead of using
filesystem representations. AFAICT, the resource loading mechanisms only work
for the named package given to it, and can't reach into a subdirectory.
While here, the `help` directory is renamed to `helptext`. Without this, trying
to load external help text crashed in mercurial/help.py when importing `.i18n`,
saying there's no `mercurial.help.i18n` module.
Differential Revision: https://phab.mercurial-scm.org/D7376
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Wed, 13 Nov 2019 21:52:25 -0500 |
parents | mercurial/help/scripting.txt@77ef3498ceb3 |
children | d56a2d6f34f0 |
comparison
equal
deleted
inserted
replaced
43631:d3c4368099ed | 43632:2e017696181f |
---|---|
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 familiar 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://www.mercurial-scm.org/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 Explicitly 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 Command-line Flags | |
78 ================== | |
79 | |
80 Mercurial's default command-line parser is designed for humans, and is not | |
81 robust against malicious input. For instance, you can start a debugger by | |
82 passing ``--debugger`` as an option value:: | |
83 | |
84 $ REV=--debugger sh -c 'hg log -r "$REV"' | |
85 | |
86 This happens because several command-line flags need to be scanned without | |
87 using a concrete command table, which may be modified while loading repository | |
88 settings and extensions. | |
89 | |
90 Since Mercurial 4.4.2, the parsing of such flags may be restricted by setting | |
91 ``HGPLAIN=+strictflags``. When this feature is enabled, all early options | |
92 (e.g. ``-R/--repository``, ``--cwd``, ``--config``) must be specified first | |
93 amongst the other global options, and cannot be injected to an arbitrary | |
94 location:: | |
95 | |
96 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV" | |
97 | |
98 In earlier Mercurial versions where ``+strictflags`` isn't available, you | |
99 can mitigate the issue by concatenating an option value with its flag:: | |
100 | |
101 $ hg log -r"$REV" --keyword="$KEYWORD" | |
102 | |
103 Consuming Command Output | |
104 ======================== | |
105 | |
106 It is common for machines to need to parse the output of Mercurial | |
107 commands for relevant data. This section describes the various | |
108 techniques for doing so. | |
109 | |
110 Parsing Raw Command Output | |
111 -------------------------- | |
112 | |
113 Likely the simplest and most effective solution for consuming command | |
114 output is to simply invoke ``hg`` commands as you would as a user and | |
115 parse their output. | |
116 | |
117 The output of many commands can easily be parsed with tools like | |
118 ``grep``, ``sed``, and ``awk``. | |
119 | |
120 A potential downside with parsing command output is that the output | |
121 of commands can change when Mercurial is upgraded. While Mercurial | |
122 does generally strive for strong backwards compatibility, command | |
123 output does occasionally change. Having tests for your automated | |
124 interactions with ``hg`` commands is generally recommended, but is | |
125 even more important when raw command output parsing is involved. | |
126 | |
127 Using Templates to Control Output | |
128 --------------------------------- | |
129 | |
130 Many ``hg`` commands support templatized output via the | |
131 ``-T/--template`` argument. For more, see :hg:`help templates`. | |
132 | |
133 Templates are useful for explicitly controlling output so that | |
134 you get exactly the data you want formatted how you want it. For | |
135 example, ``log -T {node}\n`` can be used to print a newline | |
136 delimited list of changeset nodes instead of a human-tailored | |
137 output containing authors, dates, descriptions, etc. | |
138 | |
139 .. tip:: | |
140 | |
141 If parsing raw command output is too complicated, consider | |
142 using templates to make your life easier. | |
143 | |
144 The ``-T/--template`` argument allows specifying pre-defined styles. | |
145 Mercurial ships with the machine-readable styles ``cbor``, ``json``, | |
146 and ``xml``, which provide CBOR, JSON, and XML output, respectively. | |
147 These are useful for producing output that is machine readable as-is. | |
148 | |
149 (Mercurial 5.0 is required for CBOR style.) | |
150 | |
151 .. important:: | |
152 | |
153 The ``json`` and ``xml`` styles are considered experimental. While | |
154 they may be attractive to use for easily obtaining machine-readable | |
155 output, their behavior may change in subsequent versions. | |
156 | |
157 These styles may also exhibit unexpected results when dealing with | |
158 certain encodings. Mercurial treats things like filenames as a | |
159 series of bytes and normalizing certain byte sequences to JSON | |
160 or XML with certain encoding settings can lead to surprises. | |
161 | |
162 Command Server Output | |
163 --------------------- | |
164 | |
165 If using the command server to interact with Mercurial, you are likely | |
166 using an existing library/API that abstracts implementation details of | |
167 the command server. If so, this interface layer may perform parsing for | |
168 you, saving you the work of implementing it yourself. | |
169 | |
170 Output Verbosity | |
171 ---------------- | |
172 | |
173 Commands often have varying output verbosity, even when machine | |
174 readable styles are being used (e.g. ``-T json``). Adding | |
175 ``-v/--verbose`` and ``--debug`` to the command's arguments can | |
176 increase the amount of data exposed by Mercurial. | |
177 | |
178 An alternate way to get the data you need is by explicitly specifying | |
179 a template. | |
180 | |
181 Other Topics | |
182 ============ | |
183 | |
184 revsets | |
185 Revisions sets is a functional query language for selecting a set | |
186 of revisions. Think of it as SQL for Mercurial repositories. Revsets | |
187 are useful for querying repositories for specific data. | |
188 | |
189 See :hg:`help revsets` for more. | |
190 | |
191 share extension | |
192 The ``share`` extension provides functionality for sharing | |
193 repository data across several working copies. It can even | |
194 automatically "pool" storage for logically related repositories when | |
195 cloning. | |
196 | |
197 Configuring the ``share`` extension can lead to significant resource | |
198 utilization reduction, particularly around disk space and the | |
199 network. This is especially true for continuous integration (CI) | |
200 environments. | |
201 | |
202 See :hg:`help -e share` for more. |