annotate mercurial/helptext/scripting.txt @ 46336:4f17773fc6b5

share: rename share-safe warning config Config introduced in previous patch was `share.source-safe-mismatch`. Let's rename the warn as `share.source-safe-mismatch.warn`. While we are here, made sure we have different configs for upgrade and downgrade. Differential Revision: https://phab.mercurial-scm.org/D9786
author Pulkit Goyal <7895pulkit@gmail.com>
date Fri, 15 Jan 2021 12:08:07 +0530
parents d56a2d6f34f0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.