Mercurial > hg
annotate mercurial/helptext/scripting.txt @ 45849:731ea8fa1f11 stable
chg: show debug message for each fd to be closed
It helps debugging. The number of file descriptors should be small in most
cases, so the console output wouldn't get bloated even with CHG_DEBUG=1.
author | Yuya Nishihara <yuya@tcha.org> |
---|---|
date | Tue, 03 Nov 2020 11:12:25 +0900 |
parents | d56a2d6f34f0 |
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 |
44124
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
77 HGRCSKIPREPO |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
78 When set, the .hg/hgrc from repositories are not read. |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
79 |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
80 Note that not reading the repository's configuration can have |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
81 unintended consequences, as the repository config files can define |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
82 things like extensions that are required for access to the |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
83 repository. |
d56a2d6f34f0
hgrc: introduce HGRCSKIPREPO to skip reading the repository's hgrc
Pierre-Yves David <pierre-yves.david@octobus.net>
parents:
43632
diff
changeset
|
84 |
35170
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
85 Command-line Flags |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
86 ================== |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
87 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
88 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
|
89 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
|
90 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
|
91 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
92 $ 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
|
93 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
94 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
|
95 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
|
96 settings and extensions. |
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 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
|
99 ``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
|
100 (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
|
101 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
|
102 location:: |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
103 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
104 $ 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
|
105 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
106 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
|
107 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
|
108 |
c9740b69b9b7
dispatch: add HGPLAIN=+strictflags to restrict early parsing of global options
Yuya Nishihara <yuya@tcha.org>
parents:
29663
diff
changeset
|
109 $ 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
|
110 |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
111 Consuming Command Output |
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 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
114 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
|
115 commands for relevant data. This section describes the various |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
116 techniques for doing so. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
117 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
118 Parsing Raw Command Output |
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 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
121 Likely the simplest and most effective solution for consuming command |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
122 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
|
123 parse their output. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
124 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
125 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
|
126 ``grep``, ``sed``, and ``awk``. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
127 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
128 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
|
129 of commands can change when Mercurial is upgraded. While Mercurial |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
130 does generally strive for strong backwards compatibility, command |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
131 output does occasionally change. Having tests for your automated |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
132 interactions with ``hg`` commands is generally recommended, but is |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
133 even more important when raw command output parsing is involved. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
134 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
135 Using Templates to Control Output |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
136 --------------------------------- |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
137 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
138 Many ``hg`` commands support templatized output via the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
139 ``-T/--template`` argument. For more, see :hg:`help templates`. |
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 Templates are useful for explicitly controlling output so that |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
142 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
|
143 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
|
144 delimited list of changeset nodes instead of a human-tailored |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
145 output containing authors, dates, descriptions, etc. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
146 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
147 .. tip:: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
148 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
149 If parsing raw command output is too complicated, consider |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
150 using templates to make your life easier. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
151 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
152 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
|
153 Mercurial ships with the machine-readable styles ``cbor``, ``json``, |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
154 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
|
155 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
|
156 |
77ef3498ceb3
template: add CBOR output format
Yuya Nishihara <yuya@tcha.org>
parents:
35170
diff
changeset
|
157 (Mercurial 5.0 is required for CBOR style.) |
25881
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
158 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
159 .. important:: |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
160 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
161 The ``json`` and ``xml`` styles are considered experimental. While |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
162 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
|
163 output, their behavior may change in subsequent versions. |
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 These styles may also exhibit unexpected results when dealing with |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
166 certain encodings. Mercurial treats things like filenames as a |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
167 series of bytes and normalizing certain byte sequences to JSON |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
168 or XML with certain encoding settings can lead to surprises. |
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 Command Server Output |
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 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
|
174 using an existing library/API that abstracts implementation details of |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
175 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
|
176 you, saving you the work of implementing it yourself. |
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 Output Verbosity |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
179 ---------------- |
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 Commands often have varying output verbosity, even when machine |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
182 readable styles are being used (e.g. ``-T json``). Adding |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
183 ``-v/--verbose`` and ``--debug`` to the command's arguments can |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
184 increase the amount of data exposed by Mercurial. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
185 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
186 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
|
187 a template. |
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 Other Topics |
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 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
192 revsets |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
193 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
|
194 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
|
195 are useful for querying repositories for specific data. |
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 See :hg:`help revsets` for more. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
198 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
199 share extension |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
200 The ``share`` extension provides functionality for sharing |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
201 repository data across several working copies. It can even |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
202 automatically "pool" storage for logically related repositories when |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
203 cloning. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
204 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
205 Configuring the ``share`` extension can lead to significant resource |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
206 utilization reduction, particularly around disk space and the |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
207 network. This is especially true for continuous integration (CI) |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
208 environments. |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
209 |
9de443515f1d
help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
210 See :hg:`help -e share` for more. |