Mercurial > hg
annotate mercurial/helptext/scripting.txt @ 46139:3ca5ca380a34
filemerge: add support for the new "mergediff" marker style to premerge
This adds support for the new "mergediff" conflict marker style to
"merge-tools.<tool>.premerge" (the new value is called
"keep-mergediff").
Differential Revision: https://phab.mercurial-scm.org/D9606
author | Martin von Zweigbergk <martinvonz@google.com> |
---|---|
date | Mon, 14 Dec 2020 18:09:37 -0800 |
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. |