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