| rev |
line source |
|
bos@559
|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
|
|
bos@559
|
2
|
|
bos@559
|
3 <chapter id="chap:hgext">
|
|
bos@572
|
4 <?dbhtml filename="adding-functionality-with-extensions.html"?>
|
|
bos@559
|
5 <title>Adding functionality with extensions</title>
|
|
bos@559
|
6
|
|
bos@584
|
7 <para id="x_4fe">While the core of Mercurial is quite complete from a
|
|
bos@559
|
8 functionality standpoint, it's deliberately shorn of fancy
|
|
bos@559
|
9 features. This approach of preserving simplicity keeps the
|
|
bos@559
|
10 software easy to deal with for both maintainers and users.</para>
|
|
bos@559
|
11
|
|
bos@584
|
12 <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
|
|
bos@559
|
13 command set: you can add features to it as
|
|
bos@559
|
14 <emphasis>extensions</emphasis> (sometimes known as
|
|
bos@559
|
15 <emphasis>plugins</emphasis>). We've already discussed a few of
|
|
bos@559
|
16 these extensions in earlier chapters.</para>
|
|
bos@559
|
17 <itemizedlist>
|
|
bos@592
|
18 <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
|
|
bos@559
|
19 covers the <literal role="hg-ext">fetch</literal> extension;
|
|
bos@559
|
20 this combines pulling new changes and merging them with local
|
|
bos@559
|
21 changes into a single command, <command
|
|
bos@559
|
22 role="hg-ext-fetch">fetch</command>.</para>
|
|
bos@559
|
23 </listitem>
|
|
bos@592
|
24 <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
|
|
bos@559
|
25 several extensions that are useful for hook-related
|
|
bos@559
|
26 functionality: <literal role="hg-ext">acl</literal> adds
|
|
bos@559
|
27 access control lists; <literal
|
|
bos@559
|
28 role="hg-ext">bugzilla</literal> adds integration with the
|
|
bos@559
|
29 Bugzilla bug tracking system; and <literal
|
|
bos@559
|
30 role="hg-ext">notify</literal> sends notification emails on
|
|
bos@559
|
31 new changes.</para>
|
|
bos@559
|
32 </listitem>
|
|
bos@584
|
33 <listitem><para id="x_502">The Mercurial Queues patch management extension is
|
|
bos@559
|
34 so invaluable that it merits two chapters and an appendix all
|
|
bos@592
|
35 to itself. <xref linkend="chap:mq"/> covers the
|
|
bos@592
|
36 basics; <xref
|
|
bos@559
|
37 linkend="chap:mq-collab"/> discusses advanced topics;
|
|
bos@592
|
38 and <xref linkend="chap:mqref"/> goes into detail on
|
|
bos@559
|
39 each
|
|
bos@559
|
40 command.</para>
|
|
bos@559
|
41 </listitem></itemizedlist>
|
|
bos@559
|
42
|
|
bos@584
|
43 <para id="x_503">In this chapter, we'll cover some of the other extensions that
|
|
bos@559
|
44 are available for Mercurial, and briefly touch on some of the
|
|
bos@559
|
45 machinery you'll need to know about if you want to write an
|
|
bos@559
|
46 extension of your own.</para>
|
|
bos@559
|
47 <itemizedlist>
|
|
bos@592
|
48 <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
|
|
bos@559
|
49 we'll discuss the possibility of <emphasis>huge</emphasis>
|
|
bos@559
|
50 performance improvements using the <literal
|
|
bos@559
|
51 role="hg-ext">inotify</literal> extension.</para>
|
|
bos@559
|
52 </listitem></itemizedlist>
|
|
bos@559
|
53
|
|
bos@559
|
54 <sect1 id="sec:hgext:inotify">
|
|
bos@559
|
55 <title>Improve performance with the <literal
|
|
bos@559
|
56 role="hg-ext">inotify</literal> extension</title>
|
|
bos@559
|
57
|
|
bos@584
|
58 <para id="x_505">Are you interested in having some of the most common
|
|
bos@559
|
59 Mercurial operations run as much as a hundred times faster?
|
|
bos@559
|
60 Read on!</para>
|
|
bos@559
|
61
|
|
bos@584
|
62 <para id="x_506">Mercurial has great performance under normal circumstances.
|
|
bos@559
|
63 For example, when you run the <command role="hg-cmd">hg
|
|
bos@559
|
64 status</command> command, Mercurial has to scan almost every
|
|
bos@559
|
65 directory and file in your repository so that it can display
|
|
bos@559
|
66 file status. Many other Mercurial commands need to do the same
|
|
bos@559
|
67 work behind the scenes; for example, the <command
|
|
bos@559
|
68 role="hg-cmd">hg diff</command> command uses the status
|
|
bos@559
|
69 machinery to avoid doing an expensive comparison operation on
|
|
bos@559
|
70 files that obviously haven't changed.</para>
|
|
bos@559
|
71
|
|
bos@584
|
72 <para id="x_507">Because obtaining file status is crucial to good
|
|
bos@559
|
73 performance, the authors of Mercurial have optimised this code
|
|
bos@559
|
74 to within an inch of its life. However, there's no avoiding the
|
|
bos@559
|
75 fact that when you run <command role="hg-cmd">hg
|
|
bos@559
|
76 status</command>, Mercurial is going to have to perform at
|
|
bos@559
|
77 least one expensive system call for each managed file to
|
|
bos@559
|
78 determine whether it's changed since the last time Mercurial
|
|
bos@559
|
79 checked. For a sufficiently large repository, this can take a
|
|
bos@559
|
80 long time.</para>
|
|
bos@559
|
81
|
|
bos@584
|
82 <para id="x_508">To put a number on the magnitude of this effect, I created a
|
|
bos@559
|
83 repository containing 150,000 managed files. I timed <command
|
|
bos@559
|
84 role="hg-cmd">hg status</command> as taking ten seconds to
|
|
bos@559
|
85 run, even when <emphasis>none</emphasis> of those files had been
|
|
bos@559
|
86 modified.</para>
|
|
bos@559
|
87
|
|
bos@584
|
88 <para id="x_509">Many modern operating systems contain a file notification
|
|
bos@559
|
89 facility. If a program signs up to an appropriate service, the
|
|
bos@559
|
90 operating system will notify it every time a file of interest is
|
|
bos@559
|
91 created, modified, or deleted. On Linux systems, the kernel
|
|
bos@559
|
92 component that does this is called
|
|
bos@559
|
93 <literal>inotify</literal>.</para>
|
|
bos@559
|
94
|
|
bos@584
|
95 <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal>
|
|
bos@559
|
96 extension talks to the kernel's <literal>inotify</literal>
|
|
bos@559
|
97 component to optimise <command role="hg-cmd">hg status</command>
|
|
bos@559
|
98 commands. The extension has two components. A daemon sits in
|
|
bos@559
|
99 the background and receives notifications from the
|
|
bos@559
|
100 <literal>inotify</literal> subsystem. It also listens for
|
|
bos@559
|
101 connections from a regular Mercurial command. The extension
|
|
bos@672
|
102 modifies Mercurial's behavior so that instead of scanning the
|
|
bos@559
|
103 filesystem, it queries the daemon. Since the daemon has perfect
|
|
bos@559
|
104 information about the state of the repository, it can respond
|
|
bos@559
|
105 with a result instantaneously, avoiding the need to scan every
|
|
bos@559
|
106 directory and file in the repository.</para>
|
|
bos@559
|
107
|
|
bos@584
|
108 <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
|
|
bos@559
|
109 taking to run <command role="hg-cmd">hg status</command> on a
|
|
bos@559
|
110 150,000 file repository. With the <literal
|
|
bos@559
|
111 role="hg-ext">inotify</literal> extension enabled, the time
|
|
bos@559
|
112 dropped to 0.1 seconds, a factor of <emphasis>one
|
|
bos@559
|
113 hundred</emphasis> faster.</para>
|
|
bos@559
|
114
|
|
bos@584
|
115 <para id="x_50c">Before we continue, please pay attention to some
|
|
bos@559
|
116 caveats.</para>
|
|
bos@559
|
117 <itemizedlist>
|
|
bos@584
|
118 <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal>
|
|
bos@559
|
119 extension is Linux-specific. Because it interfaces directly
|
|
bos@559
|
120 to the Linux kernel's <literal>inotify</literal> subsystem,
|
|
bos@559
|
121 it does not work on other operating systems.</para>
|
|
bos@559
|
122 </listitem>
|
|
bos@584
|
123 <listitem><para id="x_50e">It should work on any Linux distribution that
|
|
bos@559
|
124 was released after early 2005. Older distributions are
|
|
bos@559
|
125 likely to have a kernel that lacks
|
|
bos@559
|
126 <literal>inotify</literal>, or a version of
|
|
bos@559
|
127 <literal>glibc</literal> that does not have the necessary
|
|
bos@559
|
128 interfacing support.</para>
|
|
bos@559
|
129 </listitem>
|
|
bos@584
|
130 <listitem><para id="x_50f">Not all filesystems are suitable for use with
|
|
bos@559
|
131 the <literal role="hg-ext">inotify</literal> extension.
|
|
bos@559
|
132 Network filesystems such as NFS are a non-starter, for
|
|
bos@559
|
133 example, particularly if you're running Mercurial on several
|
|
bos@559
|
134 systems, all mounting the same network filesystem. The
|
|
bos@559
|
135 kernel's <literal>inotify</literal> system has no way of
|
|
bos@559
|
136 knowing about changes made on another system. Most local
|
|
bos@559
|
137 filesystems (e.g. ext3, XFS, ReiserFS) should work
|
|
bos@559
|
138 fine.</para>
|
|
bos@559
|
139 </listitem></itemizedlist>
|
|
bos@559
|
140
|
|
bos@584
|
141 <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is
|
|
bos@559
|
142 not yet shipped with Mercurial as of May 2007, so it's a little
|
|
bos@559
|
143 more involved to set up than other extensions. But the
|
|
bos@559
|
144 performance improvement is worth it!</para>
|
|
bos@559
|
145
|
|
bos@584
|
146 <para id="x_511">The extension currently comes in two parts: a set of patches
|
|
bos@559
|
147 to the Mercurial source code, and a library of Python bindings
|
|
bos@559
|
148 to the <literal>inotify</literal> subsystem.</para>
|
|
bos@559
|
149 <note>
|
|
bos@584
|
150 <para id="x_512"> There are <emphasis>two</emphasis> Python
|
|
bos@559
|
151 <literal>inotify</literal> binding libraries. One of them is
|
|
bos@559
|
152 called <literal>pyinotify</literal>, and is packaged by some
|
|
bos@559
|
153 Linux distributions as <literal>python-inotify</literal>.
|
|
bos@559
|
154 This is <emphasis>not</emphasis> the one you'll need, as it is
|
|
bos@559
|
155 too buggy and inefficient to be practical.</para>
|
|
bos@559
|
156 </note>
|
|
bos@584
|
157 <para id="x_513">To get going, it's best to already have a functioning copy
|
|
bos@559
|
158 of Mercurial installed.</para>
|
|
bos@559
|
159 <note>
|
|
bos@584
|
160 <para id="x_514"> If you follow the instructions below, you'll be
|
|
bos@559
|
161 <emphasis>replacing</emphasis> and overwriting any existing
|
|
bos@559
|
162 installation of Mercurial that you might already have, using
|
|
bos@559
|
163 the latest <quote>bleeding edge</quote> Mercurial code. Don't
|
|
bos@559
|
164 say you weren't warned!</para>
|
|
bos@559
|
165 </note>
|
|
bos@559
|
166 <orderedlist>
|
|
bos@584
|
167 <listitem><para id="x_515">Clone the Python <literal>inotify</literal>
|
|
bos@559
|
168 binding repository. Build and install it.</para>
|
|
bos@580
|
169 <programlisting>hg clone http://hg.kublai.com/python/inotify
|
|
bos@580
|
170 cd inotify
|
|
bos@580
|
171 python setup.py build --force
|
|
bos@580
|
172 sudo python setup.py install --skip-build</programlisting>
|
|
bos@559
|
173 </listitem>
|
|
bos@584
|
174 <listitem><para id="x_516">Clone the <filename
|
|
bos@559
|
175 class="directory">crew</filename> Mercurial repository.
|
|
bos@559
|
176 Clone the <literal role="hg-ext">inotify</literal> patch
|
|
bos@559
|
177 repository so that Mercurial Queues will be able to apply
|
|
bos@559
|
178 patches to your cope of the <filename
|
|
bos@559
|
179 class="directory">crew</filename> repository.</para>
|
|
bos@580
|
180 <programlisting>hg clone http://hg.intevation.org/mercurial/crew
|
|
bos@580
|
181 hg clone crew inotify
|
|
bos@580
|
182 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
|
|
bos@559
|
183 </listitem>
|
|
bos@584
|
184 <listitem><para id="x_517">Make sure that you have the Mercurial Queues
|
|
bos@559
|
185 extension, <literal role="hg-ext">mq</literal>, enabled. If
|
|
bos@592
|
186 you've never used MQ, read <xref
|
|
bos@559
|
187 linkend="sec:mq:start"/> to get started
|
|
bos@559
|
188 quickly.</para>
|
|
bos@559
|
189 </listitem>
|
|
bos@584
|
190 <listitem><para id="x_518">Go into the <filename
|
|
bos@559
|
191 class="directory">inotify</filename> repo, and apply all
|
|
bos@559
|
192 of the <literal role="hg-ext">inotify</literal> patches
|
|
bos@559
|
193 using the <option role="hg-ext-mq-cmd-qpush-opt">hg
|
|
bos@559
|
194 -a</option> option to the <command
|
|
bos@559
|
195 role="hg-ext-mq">qpush</command> command.</para>
|
|
bos@580
|
196 <programlisting>cd inotify
|
|
bos@580
|
197 hg qpush -a</programlisting>
|
|
bos@559
|
198 </listitem>
|
|
bos@584
|
199 <listitem><para id="x_519"> If you get an error message from <command
|
|
bos@559
|
200 role="hg-ext-mq">qpush</command>, you should not continue.
|
|
bos@559
|
201 Instead, ask for help.</para>
|
|
bos@559
|
202 </listitem>
|
|
bos@584
|
203 <listitem><para id="x_51a">Build and install the patched version of
|
|
bos@559
|
204 Mercurial.</para>
|
|
bos@580
|
205 <programlisting>python setup.py build --force
|
|
bos@580
|
206 sudo python setup.py install --skip-build</programlisting>
|
|
bos@559
|
207 </listitem>
|
|
bos@559
|
208 </orderedlist>
|
|
bos@584
|
209 <para id="x_51b">Once you've build a suitably patched version of Mercurial,
|
|
bos@559
|
210 all you need to do to enable the <literal
|
|
bos@559
|
211 role="hg-ext">inotify</literal> extension is add an entry to
|
|
bos@580
|
212 your <filename role="special">~/.hgrc</filename>.</para>
|
|
bos@559
|
213 <programlisting>[extensions] inotify =</programlisting>
|
|
bos@584
|
214 <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension
|
|
bos@559
|
215 is enabled, Mercurial will automatically and transparently start
|
|
bos@559
|
216 the status daemon the first time you run a command that needs
|
|
bos@559
|
217 status in a repository. It runs one status daemon per
|
|
bos@559
|
218 repository.</para>
|
|
bos@559
|
219
|
|
bos@584
|
220 <para id="x_51d">The status daemon is started silently, and runs in the
|
|
bos@559
|
221 background. If you look at a list of running processes after
|
|
bos@559
|
222 you've enabled the <literal role="hg-ext">inotify</literal>
|
|
bos@559
|
223 extension and run a few commands in different repositories,
|
|
bos@559
|
224 you'll thus see a few <literal>hg</literal> processes sitting
|
|
bos@559
|
225 around, waiting for updates from the kernel and queries from
|
|
bos@559
|
226 Mercurial.</para>
|
|
bos@559
|
227
|
|
bos@584
|
228 <para id="x_51e">The first time you run a Mercurial command in a repository
|
|
bos@559
|
229 when you have the <literal role="hg-ext">inotify</literal>
|
|
bos@559
|
230 extension enabled, it will run with about the same performance
|
|
bos@559
|
231 as a normal Mercurial command. This is because the status
|
|
bos@559
|
232 daemon needs to perform a normal status scan so that it has a
|
|
bos@559
|
233 baseline against which to apply later updates from the kernel.
|
|
bos@559
|
234 However, <emphasis>every</emphasis> subsequent command that does
|
|
bos@559
|
235 any kind of status check should be noticeably faster on
|
|
bos@559
|
236 repositories of even fairly modest size. Better yet, the bigger
|
|
bos@559
|
237 your repository is, the greater a performance advantage you'll
|
|
bos@559
|
238 see. The <literal role="hg-ext">inotify</literal> daemon makes
|
|
bos@559
|
239 status operations almost instantaneous on repositories of all
|
|
bos@559
|
240 sizes!</para>
|
|
bos@559
|
241
|
|
bos@584
|
242 <para id="x_51f">If you like, you can manually start a status daemon using
|
|
bos@559
|
243 the <command role="hg-ext-inotify">inserve</command> command.
|
|
bos@559
|
244 This gives you slightly finer control over how the daemon ought
|
|
bos@559
|
245 to run. This command will of course only be available when the
|
|
bos@559
|
246 <literal role="hg-ext">inotify</literal> extension is
|
|
bos@559
|
247 enabled.</para>
|
|
bos@559
|
248
|
|
bos@584
|
249 <para id="x_520">When you're using the <literal
|
|
bos@559
|
250 role="hg-ext">inotify</literal> extension, you should notice
|
|
bos@559
|
251 <emphasis>no difference at all</emphasis> in Mercurial's
|
|
bos@672
|
252 behavior, with the sole exception of status-related commands
|
|
bos@559
|
253 running a whole lot faster than they used to. You should
|
|
bos@559
|
254 specifically expect that commands will not print different
|
|
bos@559
|
255 output; neither should they give different results. If either of
|
|
bos@559
|
256 these situations occurs, please report a bug.</para>
|
|
bos@559
|
257
|
|
bos@559
|
258 </sect1>
|
|
bos@559
|
259 <sect1 id="sec:hgext:extdiff">
|
|
bos@559
|
260 <title>Flexible diff support with the <literal
|
|
bos@559
|
261 role="hg-ext">extdiff</literal> extension</title>
|
|
bos@559
|
262
|
|
bos@584
|
263 <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg
|
|
bos@567
|
264 diff</command> command outputs plaintext unified diffs.</para>
|
|
bos@567
|
265
|
|
bos@567
|
266 &interaction.extdiff.diff;
|
|
bos@567
|
267
|
|
bos@584
|
268 <para id="x_522">If you would like to use an external tool to display
|
|
bos@567
|
269 modifications, you'll want to use the <literal
|
|
bos@567
|
270 role="hg-ext">extdiff</literal> extension. This will let you
|
|
bos@567
|
271 use, for example, a graphical diff tool.</para>
|
|
bos@559
|
272
|
|
bos@584
|
273 <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is
|
|
bos@559
|
274 bundled with Mercurial, so it's easy to set up. In the <literal
|
|
bos@559
|
275 role="rc-extensions">extensions</literal> section of your
|
|
bos@580
|
276 <filename role="special">~/.hgrc</filename>, simply add a
|
|
bos@559
|
277 one-line entry to enable the extension.</para>
|
|
bos@580
|
278 <programlisting>[extensions]
|
|
bos@580
|
279 extdiff =</programlisting>
|
|
bos@584
|
280 <para id="x_524">This introduces a command named <command
|
|
bos@559
|
281 role="hg-ext-extdiff">extdiff</command>, which by default uses
|
|
bos@559
|
282 your system's <command>diff</command> command to generate a
|
|
bos@559
|
283 unified diff in the same form as the built-in <command
|
|
bos@567
|
284 role="hg-cmd">hg diff</command> command.</para>
|
|
bos@567
|
285
|
|
bos@567
|
286 &interaction.extdiff.extdiff;
|
|
bos@567
|
287
|
|
bos@584
|
288 <para id="x_525">The result won't be exactly the same as with the built-in
|
|
bos@567
|
289 <command role="hg-cmd">hg diff</command> variations, because the
|
|
bos@567
|
290 output of <command>diff</command> varies from one system to
|
|
bos@567
|
291 another, even when passed the same options.</para>
|
|
bos@559
|
292
|
|
bos@584
|
293 <para id="x_526">As the <quote><literal>making snapshot</literal></quote>
|
|
bos@559
|
294 lines of output above imply, the <command
|
|
bos@559
|
295 role="hg-ext-extdiff">extdiff</command> command works by
|
|
bos@559
|
296 creating two snapshots of your source tree. The first snapshot
|
|
bos@559
|
297 is of the source revision; the second, of the target revision or
|
|
bos@559
|
298 working directory. The <command
|
|
bos@559
|
299 role="hg-ext-extdiff">extdiff</command> command generates
|
|
bos@559
|
300 these snapshots in a temporary directory, passes the name of
|
|
bos@559
|
301 each directory to an external diff viewer, then deletes the
|
|
bos@559
|
302 temporary directory. For efficiency, it only snapshots the
|
|
bos@559
|
303 directories and files that have changed between the two
|
|
bos@559
|
304 revisions.</para>
|
|
bos@559
|
305
|
|
bos@584
|
306 <para id="x_527">Snapshot directory names have the same base name as your
|
|
bos@559
|
307 repository. If your repository path is <filename
|
|
bos@559
|
308 class="directory">/quux/bar/foo</filename>, then <filename
|
|
bos@559
|
309 class="directory">foo</filename> will be the name of each
|
|
bos@559
|
310 snapshot directory. Each snapshot directory name has its
|
|
bos@559
|
311 changeset ID appended, if appropriate. If a snapshot is of
|
|
bos@559
|
312 revision <literal>a631aca1083f</literal>, the directory will be
|
|
bos@559
|
313 named <filename class="directory">foo.a631aca1083f</filename>.
|
|
bos@559
|
314 A snapshot of the working directory won't have a changeset ID
|
|
bos@559
|
315 appended, so it would just be <filename
|
|
bos@559
|
316 class="directory">foo</filename> in this example. To see what
|
|
bos@559
|
317 this looks like in practice, look again at the <command
|
|
bos@559
|
318 role="hg-ext-extdiff">extdiff</command> example above. Notice
|
|
bos@559
|
319 that the diff has the snapshot directory names embedded in its
|
|
bos@559
|
320 header.</para>
|
|
bos@559
|
321
|
|
bos@584
|
322 <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command
|
|
bos@559
|
323 accepts two important options. The <option
|
|
bos@559
|
324 role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
|
|
bos@559
|
325 lets you choose a program to view differences with, instead of
|
|
bos@559
|
326 <command>diff</command>. With the <option
|
|
bos@559
|
327 role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
|
|
bos@559
|
328 you can change the options that <command
|
|
bos@559
|
329 role="hg-ext-extdiff">extdiff</command> passes to the program
|
|
bos@559
|
330 (by default, these options are
|
|
bos@559
|
331 <quote><literal>-Npru</literal></quote>, which only make sense
|
|
bos@559
|
332 if you're running <command>diff</command>). In other respects,
|
|
bos@559
|
333 the <command role="hg-ext-extdiff">extdiff</command> command
|
|
bos@559
|
334 acts similarly to the built-in <command role="hg-cmd">hg
|
|
bos@559
|
335 diff</command> command: you use the same option names, syntax,
|
|
bos@559
|
336 and arguments to specify the revisions you want, the files you
|
|
bos@559
|
337 want, and so on.</para>
|
|
bos@559
|
338
|
|
bos@584
|
339 <para id="x_529">As an example, here's how to run the normal system
|
|
bos@559
|
340 <command>diff</command> command, getting it to generate context
|
|
bos@559
|
341 diffs (using the <option role="cmd-opt-diff">-c</option> option)
|
|
bos@559
|
342 instead of unified diffs, and five lines of context instead of
|
|
bos@559
|
343 the default three (passing <literal>5</literal> as the argument
|
|
bos@567
|
344 to the <option role="cmd-opt-diff">-C</option> option).</para>
|
|
bos@567
|
345
|
|
bos@567
|
346 &interaction.extdiff.extdiff-ctx;
|
|
bos@559
|
347
|
|
bos@584
|
348 <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to
|
|
bos@559
|
349 launch the <command>kdiff3</command> viewer.</para>
|
|
bos@559
|
350 <programlisting>hg extdiff -p kdiff3 -o</programlisting>
|
|
bos@559
|
351
|
|
bos@584
|
352 <para id="x_52b">If your diff viewing command can't deal with directories,
|
|
bos@559
|
353 you can easily work around this with a little scripting. For an
|
|
bos@559
|
354 example of such scripting in action with the <literal
|
|
bos@559
|
355 role="hg-ext">mq</literal> extension and the
|
|
bos@592
|
356 <command>interdiff</command> command, see <xref
|
|
bos@559
|
357 linkend="mq-collab:tips:interdiff"/>.</para>
|
|
bos@559
|
358
|
|
bos@559
|
359 <sect2>
|
|
bos@559
|
360 <title>Defining command aliases</title>
|
|
bos@559
|
361
|
|
bos@584
|
362 <para id="x_52c">It can be cumbersome to remember the options to both the
|
|
bos@559
|
363 <command role="hg-ext-extdiff">extdiff</command> command and
|
|
bos@559
|
364 the diff viewer you want to use, so the <literal
|
|
bos@559
|
365 role="hg-ext">extdiff</literal> extension lets you define
|
|
bos@559
|
366 <emphasis>new</emphasis> commands that will invoke your diff
|
|
bos@559
|
367 viewer with exactly the right options.</para>
|
|
bos@559
|
368
|
|
bos@584
|
369 <para id="x_52d">All you need to do is edit your <filename
|
|
bos@580
|
370 role="special">~/.hgrc</filename>, and add a section named
|
|
bos@580
|
371 <literal role="rc-extdiff">extdiff</literal>. Inside this
|
|
bos@580
|
372 section, you can define multiple commands. Here's how to add
|
|
bos@580
|
373 a <literal>kdiff3</literal> command. Once you've defined
|
|
bos@580
|
374 this, you can type <quote><literal>hg kdiff3</literal></quote>
|
|
bos@580
|
375 and the <literal role="hg-ext">extdiff</literal> extension
|
|
bos@580
|
376 will run <command>kdiff3</command> for you.</para>
|
|
bos@580
|
377 <programlisting>[extdiff]
|
|
bos@580
|
378 cmd.kdiff3 =</programlisting>
|
|
bos@584
|
379 <para id="x_52e">If you leave the right hand side of the definition empty,
|
|
bos@559
|
380 as above, the <literal role="hg-ext">extdiff</literal>
|
|
bos@559
|
381 extension uses the name of the command you defined as the name
|
|
bos@559
|
382 of the external program to run. But these names don't have to
|
|
bos@559
|
383 be the same. Here, we define a command named
|
|
bos@559
|
384 <quote><literal>hg wibble</literal></quote>, which runs
|
|
bos@559
|
385 <command>kdiff3</command>.</para>
|
|
bos@580
|
386 <programlisting>[extdiff]
|
|
bos@580
|
387 cmd.wibble = kdiff3</programlisting>
|
|
bos@559
|
388
|
|
bos@584
|
389 <para id="x_52f">You can also specify the default options that you want to
|
|
bos@559
|
390 invoke your diff viewing program with. The prefix to use is
|
|
bos@559
|
391 <quote><literal>opts.</literal></quote>, followed by the name
|
|
bos@559
|
392 of the command to which the options apply. This example
|
|
bos@559
|
393 defines a <quote><literal>hg vimdiff</literal></quote> command
|
|
bos@559
|
394 that runs the <command>vim</command> editor's
|
|
bos@559
|
395 <literal>DirDiff</literal> extension.</para>
|
|
bos@580
|
396 <programlisting>[extdiff]
|
|
bos@580
|
397 cmd.vimdiff = vim
|
|
bos@580
|
398 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
|
|
bos@559
|
399
|
|
bos@559
|
400 </sect2>
|
|
bos@559
|
401 </sect1>
|
|
bos@559
|
402 <sect1 id="sec:hgext:transplant">
|
|
bos@559
|
403 <title>Cherrypicking changes with the <literal
|
|
bos@559
|
404 role="hg-ext">transplant</literal> extension</title>
|
|
bos@559
|
405
|
|
bos@584
|
406 <para id="x_530">Need to have a long chat with Brendan about this.</para>
|
|
bos@559
|
407
|
|
bos@559
|
408 </sect1>
|
|
bos@559
|
409 <sect1 id="sec:hgext:patchbomb">
|
|
bos@559
|
410 <title>Send changes via email with the <literal
|
|
bos@559
|
411 role="hg-ext">patchbomb</literal> extension</title>
|
|
bos@559
|
412
|
|
bos@584
|
413 <para id="x_531">Many projects have a culture of <quote>change
|
|
bos@559
|
414 review</quote>, in which people send their modifications to a
|
|
bos@559
|
415 mailing list for others to read and comment on before they
|
|
bos@559
|
416 commit the final version to a shared repository. Some projects
|
|
bos@559
|
417 have people who act as gatekeepers; they apply changes from
|
|
bos@559
|
418 other people to a repository to which those others don't have
|
|
bos@559
|
419 access.</para>
|
|
bos@559
|
420
|
|
bos@584
|
421 <para id="x_532">Mercurial makes it easy to send changes over email for
|
|
bos@559
|
422 review or application, via its <literal
|
|
bos@559
|
423 role="hg-ext">patchbomb</literal> extension. The extension is
|
|
ori@561
|
424 so named because changes are formatted as patches, and it's usual
|
|
bos@559
|
425 to send one changeset per email message. Sending a long series
|
|
bos@559
|
426 of changes by email is thus much like <quote>bombing</quote> the
|
|
bos@559
|
427 recipient's inbox, hence <quote>patchbomb</quote>.</para>
|
|
bos@559
|
428
|
|
bos@584
|
429 <para id="x_533">As usual, the basic configuration of the <literal
|
|
bos@559
|
430 role="hg-ext">patchbomb</literal> extension takes just one or
|
|
bos@559
|
431 two lines in your <filename role="special">
|
|
bos@559
|
432 /.hgrc</filename>.</para>
|
|
bos@580
|
433 <programlisting>[extensions]
|
|
bos@580
|
434 patchbomb =</programlisting>
|
|
bos@584
|
435 <para id="x_534">Once you've enabled the extension, you will have a new
|
|
bos@559
|
436 command available, named <command
|
|
bos@559
|
437 role="hg-ext-patchbomb">email</command>.</para>
|
|
bos@559
|
438
|
|
bos@584
|
439 <para id="x_535">The safest and best way to invoke the <command
|
|
bos@559
|
440 role="hg-ext-patchbomb">email</command> command is to
|
|
bos@559
|
441 <emphasis>always</emphasis> run it first with the <option
|
|
bos@559
|
442 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
|
|
bos@559
|
443 This will show you what the command <emphasis>would</emphasis>
|
|
bos@559
|
444 send, without actually sending anything. Once you've had a
|
|
bos@559
|
445 quick glance over the changes and verified that you are sending
|
|
bos@559
|
446 the right ones, you can rerun the same command, with the <option
|
|
bos@559
|
447 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
|
|
bos@559
|
448 removed.</para>
|
|
bos@559
|
449
|
|
bos@584
|
450 <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command
|
|
bos@559
|
451 accepts the same kind of revision syntax as every other
|
|
bos@559
|
452 Mercurial command. For example, this command will send every
|
|
bos@559
|
453 revision between 7 and <literal>tip</literal>, inclusive.</para>
|
|
bos@559
|
454 <programlisting>hg email -n 7:tip</programlisting>
|
|
bos@584
|
455 <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
|
|
bos@559
|
456 compare with. If you provide a repository but no revisions, the
|
|
bos@559
|
457 <command role="hg-ext-patchbomb">email</command> command will
|
|
bos@559
|
458 send all revisions in the local repository that are not present
|
|
bos@559
|
459 in the remote repository. If you additionally specify revisions
|
|
bos@559
|
460 or a branch name (the latter using the <option
|
|
bos@559
|
461 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
|
|
bos@559
|
462 this will constrain the revisions sent.</para>
|
|
bos@559
|
463
|
|
bos@584
|
464 <para id="x_538">It's perfectly safe to run the <command
|
|
bos@559
|
465 role="hg-ext-patchbomb">email</command> command without the
|
|
bos@559
|
466 names of the people you want to send to: if you do this, it will
|
|
bos@559
|
467 just prompt you for those values interactively. (If you're
|
|
bos@559
|
468 using a Linux or Unix-like system, you should have enhanced
|
|
bos@559
|
469 <literal>readline</literal>-style editing capabilities when
|
|
bos@559
|
470 entering those headers, too, which is useful.)</para>
|
|
bos@559
|
471
|
|
bos@584
|
472 <para id="x_539">When you are sending just one revision, the <command
|
|
bos@559
|
473 role="hg-ext-patchbomb">email</command> command will by
|
|
bos@559
|
474 default use the first line of the changeset description as the
|
|
bos@559
|
475 subject of the single email message it sends.</para>
|
|
bos@559
|
476
|
|
bos@584
|
477 <para id="x_53a">If you send multiple revisions, the <command
|
|
bos@559
|
478 role="hg-ext-patchbomb">email</command> command will usually
|
|
bos@559
|
479 send one message per changeset. It will preface the series with
|
|
bos@559
|
480 an introductory message, in which you should describe the
|
|
bos@559
|
481 purpose of the series of changes you're sending.</para>
|
|
bos@559
|
482
|
|
bos@559
|
483 <sect2>
|
|
bos@672
|
484 <title>Changing the behavior of patchbombs</title>
|
|
bos@559
|
485
|
|
bos@584
|
486 <para id="x_53b">Not every project has exactly the same conventions for
|
|
bos@559
|
487 sending changes in email; the <literal
|
|
bos@559
|
488 role="hg-ext">patchbomb</literal> extension tries to
|
|
bos@559
|
489 accommodate a number of variations through command line
|
|
bos@559
|
490 options.</para>
|
|
bos@559
|
491 <itemizedlist>
|
|
bos@584
|
492 <listitem><para id="x_53c">You can write a subject for the introductory
|
|
bos@559
|
493 message on the command line using the <option
|
|
bos@559
|
494 role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
|
|
bos@559
|
495 option. This takes one argument, the text of the subject
|
|
bos@559
|
496 to use.</para>
|
|
bos@559
|
497 </listitem>
|
|
bos@584
|
498 <listitem><para id="x_53d">To change the email address from which the
|
|
bos@559
|
499 messages originate, use the <option
|
|
bos@559
|
500 role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
|
|
bos@559
|
501 option. This takes one argument, the email address to
|
|
bos@559
|
502 use.</para>
|
|
bos@559
|
503 </listitem>
|
|
bos@672
|
504 <listitem><para id="x_53e">The default behavior is to send unified diffs
|
|
bos@592
|
505 (see <xref linkend="sec:mq:patch"/> for a
|
|
bos@559
|
506 description of the
|
|
bos@559
|
507 format), one per message. You can send a binary bundle
|
|
bos@559
|
508 instead with the <option
|
|
bos@559
|
509 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
|
|
bos@559
|
510 option.</para>
|
|
bos@559
|
511 </listitem>
|
|
bos@584
|
512 <listitem><para id="x_53f">Unified diffs are normally prefaced with a
|
|
bos@559
|
513 metadata header. You can omit this, and send unadorned
|
|
bos@559
|
514 diffs, with the <option
|
|
bos@559
|
515 role="hg-ext-patchbomb-cmd-email-opt">hg
|
|
bos@559
|
516 --plain</option> option.</para>
|
|
bos@559
|
517 </listitem>
|
|
bos@584
|
518 <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
|
|
bos@559
|
519 in the same body part as the description of a patch. This
|
|
bos@559
|
520 makes it easiest for the largest number of readers to
|
|
bos@559
|
521 quote and respond to parts of a diff, as some mail clients
|
|
bos@559
|
522 will only quote the first MIME body part in a message. If
|
|
bos@559
|
523 you'd prefer to send the description and the diff in
|
|
bos@559
|
524 separate body parts, use the <option
|
|
bos@559
|
525 role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
|
|
bos@559
|
526 option.</para>
|
|
bos@559
|
527 </listitem>
|
|
bos@584
|
528 <listitem><para id="x_541">Instead of sending mail messages, you can
|
|
bos@559
|
529 write them to an <literal>mbox</literal>-format mail
|
|
bos@559
|
530 folder using the <option
|
|
bos@559
|
531 role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
|
|
bos@559
|
532 option. That option takes one argument, the name of the
|
|
bos@559
|
533 file to write to.</para>
|
|
bos@559
|
534 </listitem>
|
|
bos@584
|
535 <listitem><para id="x_542">If you would like to add a
|
|
bos@559
|
536 <command>diffstat</command>-format summary to each patch,
|
|
bos@559
|
537 and one to the introductory message, use the <option
|
|
bos@559
|
538 role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
|
|
bos@559
|
539 option. The <command>diffstat</command> command displays
|
|
bos@559
|
540 a table containing the name of each file patched, the
|
|
bos@559
|
541 number of lines affected, and a histogram showing how much
|
|
bos@559
|
542 each file is modified. This gives readers a qualitative
|
|
bos@559
|
543 glance at how complex a patch is.</para>
|
|
bos@559
|
544 </listitem></itemizedlist>
|
|
bos@559
|
545
|
|
bos@559
|
546 </sect2>
|
|
bos@559
|
547 </sect1>
|
|
bos@559
|
548 </chapter>
|
|
bos@559
|
549
|
|
bos@559
|
550 <!--
|
|
bos@559
|
551 local variables:
|
|
bos@559
|
552 sgml-parent-document: ("00book.xml" "book" "chapter")
|
|
bos@559
|
553 end:
|
|
bos@559
|
554 -->
|
