Mercurial > hg
annotate mercurial/help/scripting.txt @ 42172:71d8b4d91616 stable
setup: properly package distutils in py2exe virtualenv builds
Our in-repo py2exe packaging code uses virtualenvs for managing
dependencies. An advantage of this is that packaging is more
deterministic and reproducible. Without virtualenvs, we need to
install packages in the system Python install. Packages installed
by other consumers of the system Python could leak into the Mercurial
package.
A regression from this change was that py2exe packages contained
the virtualenv's hacked distutils modules instead of the original
distutils modules. (virtualenv installs a hacked distutils module
because distutils uses relative path lookups that fail when running
from a virtualenv.)
This commit introduces a workaround so py2exe packaging uses the
original distutils modules when running from a virtualenv.
With this change, `import distutils` no longer fails from py2exe
builds produced from a virtualenv. This fixes the regression.
Furthermore, we now include all distutils modules. Before, py2exe's
module finding would only find modules there were explicitly
referenced in code. So, we now package a complete copy of distutils
instead of a partial one. This is even better than before.
# no-check-commit foo_bar function name
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Sat, 20 Apr 2019 07:29:07 -0700 |
parents | 77ef3498ceb3 |
children |
rev | line source |
---|---|
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
1 It is common for machines (as opposed to humans) to consume Mercurial. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
2 This help topic describes some of the considerations for interfacing |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
3 machines with Mercurial. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
4 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
5 Choosing an Interface |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
6 ===================== |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
7 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
8 Machines have a choice of several methods to interface with Mercurial. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
9 These include: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
10 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
11 - Executing the ``hg`` process |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
12 - Querying a HTTP server |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
13 - Calling out to a command server |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
14 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
15 Executing ``hg`` processes is very similar to how humans interact with |
25900
d14590f90cb6
help: fix typo familar -> familiar
Javi Merino <merino.jav@gmail.com>
parents:
25881
diff
changeset
|
16 Mercurial in the shell. It should already be familiar to you. |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
17 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
18 :hg:`serve` can be used to start a server. By default, this will start |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
19 a "hgweb" HTTP server. This HTTP server has support for machine-readable |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
20 output, such as JSON. For more, see :hg:`help hgweb`. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
21 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
22 :hg:`serve` can also start a "command server." Clients can connect |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
23 to this server and issue Mercurial commands over a special protocol. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
24 For more details on the command server, including links to client |
29663
7ce05671a5e3
help: update link to wiki/CommandServer
Anton Shestakov <av6@dwimlabs.net>
parents:
26174
diff
changeset
|
25 libraries, see https://www.mercurial-scm.org/wiki/CommandServer. |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
26 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
27 :hg:`serve` based interfaces (the hgweb and command servers) have the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
28 advantage over simple ``hg`` process invocations in that they are |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
29 likely more efficient. This is because there is significant overhead |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
30 to spawn new Python processes. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
31 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
32 .. tip:: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
33 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
34 If you need to invoke several ``hg`` processes in short order and/or |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
35 performance is important to you, use of a server-based interface |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
36 is highly recommended. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
37 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
38 Environment Variables |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
39 ===================== |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
40 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
41 As documented in :hg:`help environment`, various environment variables |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
42 influence the operation of Mercurial. The following are particularly |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
43 relevant for machines consuming Mercurial: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
44 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
45 HGPLAIN |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
46 If not set, Mercurial's output could be influenced by configuration |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
47 settings that impact its encoding, verbose mode, localization, etc. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
48 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
49 It is highly recommended for machines to set this variable when |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
50 invoking ``hg`` processes. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
51 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
52 HGENCODING |
26174
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
53 If not set, the locale used by Mercurial will be detected from the |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
54 environment. If the determined locale does not support display of |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
55 certain characters, Mercurial may render these character sequences |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
56 incorrectly (often by using "?" as a placeholder for invalid |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
57 characters in the current locale). |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
58 |
26174
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
59 Explicitly setting this environment variable is a good practice to |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
60 guarantee consistent results. "utf-8" is a good choice on UNIX-like |
c38afb8c7deb
help/scripting: fix HGENCODING indentation
timeless@mozdev.org
parents:
26027
diff
changeset
|
61 environments. |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
62 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
63 HGRCPATH |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
64 If not set, Mercurial will inherit config options from config files |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
65 using the process described in :hg:`help config`. This includes |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
66 inheriting user or system-wide config files. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
67 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
68 When utmost control over the Mercurial configuration is desired, the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
69 value of ``HGRCPATH`` can be set to an explicit file with known good |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
70 configs. In rare cases, the value can be set to an empty file or the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
71 null device (often ``/dev/null``) to bypass loading of any user or |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
72 system config files. Note that these approaches can have unintended |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
73 consequences, as the user and system config files often define things |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
74 like the username and extensions that may be required to interface |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
75 with a repository. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
76 |
35170
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
77 Command-line Flags |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
78 ================== |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
79 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
80 Mercurial's default command-line parser is designed for humans, and is not |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
81 robust against malicious input. For instance, you can start a debugger by |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
82 passing ``--debugger`` as an option value:: |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
83 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
84 $ REV=--debugger sh -c 'hg log -r "$REV"' |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
85 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
86 This happens because several command-line flags need to be scanned without |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
87 using a concrete command table, which may be modified while loading repository |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
88 settings and extensions. |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
89 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
90 Since Mercurial 4.4.2, the parsing of such flags may be restricted by setting |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
91 ``HGPLAIN=+strictflags``. When this feature is enabled, all early options |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
92 (e.g. ``-R/--repository``, ``--cwd``, ``--config``) must be specified first |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
93 amongst the other global options, and cannot be injected to an arbitrary |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
94 location:: |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
95 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
96 $ HGPLAIN=+strictflags hg -R "$REPO" log -r "$REV" |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
97 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
98 In earlier Mercurial versions where ``+strictflags`` isn't available, you |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
99 can mitigate the issue by concatenating an option value with its flag:: |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
100 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
101 $ hg log -r"$REV" --keyword="$KEYWORD" |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
102 |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
103 Consuming Command Output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
104 ======================== |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
105 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
106 It is common for machines to need to parse the output of Mercurial |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
107 commands for relevant data. This section describes the various |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
108 techniques for doing so. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
109 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
110 Parsing Raw Command Output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
111 -------------------------- |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
112 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
113 Likely the simplest and most effective solution for consuming command |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
114 output is to simply invoke ``hg`` commands as you would as a user and |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
115 parse their output. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
116 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
117 The output of many commands can easily be parsed with tools like |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
118 ``grep``, ``sed``, and ``awk``. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
119 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
120 A potential downside with parsing command output is that the output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
121 of commands can change when Mercurial is upgraded. While Mercurial |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
122 does generally strive for strong backwards compatibility, command |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
123 output does occasionally change. Having tests for your automated |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
124 interactions with ``hg`` commands is generally recommended, but is |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
125 even more important when raw command output parsing is involved. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
126 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
127 Using Templates to Control Output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
128 --------------------------------- |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
129 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
130 Many ``hg`` commands support templatized output via the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
131 ``-T/--template`` argument. For more, see :hg:`help templates`. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
132 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
133 Templates are useful for explicitly controlling output so that |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
134 you get exactly the data you want formatted how you want it. For |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
135 example, ``log -T {node}\n`` can be used to print a newline |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
136 delimited list of changeset nodes instead of a human-tailored |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
137 output containing authors, dates, descriptions, etc. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
138 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
139 .. tip:: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
140 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
141 If parsing raw command output is too complicated, consider |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
142 using templates to make your life easier. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
143 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
144 The ``-T/--template`` argument allows specifying pre-defined styles. |
41996
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
145 Mercurial ships with the machine-readable styles ``cbor``, ``json``, |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
146 and ``xml``, which provide CBOR, JSON, and XML output, respectively. |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
147 These are useful for producing output that is machine readable as-is. |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
148 |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
149 (Mercurial 5.0 is required for CBOR style.) |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
150 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
151 .. important:: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
152 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
153 The ``json`` and ``xml`` styles are considered experimental. While |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
154 they may be attractive to use for easily obtaining machine-readable |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
155 output, their behavior may change in subsequent versions. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
156 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
157 These styles may also exhibit unexpected results when dealing with |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
158 certain encodings. Mercurial treats things like filenames as a |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
159 series of bytes and normalizing certain byte sequences to JSON |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
160 or XML with certain encoding settings can lead to surprises. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
161 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
162 Command Server Output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
163 --------------------- |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
164 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
165 If using the command server to interact with Mercurial, you are likely |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
166 using an existing library/API that abstracts implementation details of |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
167 the command server. If so, this interface layer may perform parsing for |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
168 you, saving you the work of implementing it yourself. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
169 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
170 Output Verbosity |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
171 ---------------- |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
172 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
173 Commands often have varying output verbosity, even when machine |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
174 readable styles are being used (e.g. ``-T json``). Adding |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
175 ``-v/--verbose`` and ``--debug`` to the command's arguments can |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
176 increase the amount of data exposed by Mercurial. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
177 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
178 An alternate way to get the data you need is by explicitly specifying |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
179 a template. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
180 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
181 Other Topics |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
182 ============ |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
183 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
184 revsets |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
185 Revisions sets is a functional query language for selecting a set |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
186 of revisions. Think of it as SQL for Mercurial repositories. Revsets |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
187 are useful for querying repositories for specific data. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
188 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
189 See :hg:`help revsets` for more. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
190 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
191 share extension |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
192 The ``share`` extension provides functionality for sharing |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
193 repository data across several working copies. It can even |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
194 automatically "pool" storage for logically related repositories when |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
195 cloning. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
196 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
197 Configuring the ``share`` extension can lead to significant resource |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
198 utilization reduction, particularly around disk space and the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
199 network. This is especially true for continuous integration (CI) |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
200 environments. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
201 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
202 See :hg:`help -e share` for more. |