| 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@567
|
270 diff</command> command outputs plaintext unified diffs.</para>
|
|
bos@567
|
271
|
|
bos@567
|
272 &interaction.extdiff.diff;
|
|
bos@567
|
273
|
|
bos@567
|
274 <para>If you would like to use an external tool to display
|
|
bos@567
|
275 modifications, you'll want to use the <literal
|
|
bos@567
|
276 role="hg-ext">extdiff</literal> extension. This will let you
|
|
bos@567
|
277 use, for example, a graphical diff tool.</para>
|
|
bos@559
|
278
|
|
bos@559
|
279 <para>The <literal role="hg-ext">extdiff</literal> extension is
|
|
bos@559
|
280 bundled with Mercurial, so it's easy to set up. In the <literal
|
|
bos@559
|
281 role="rc-extensions">extensions</literal> section of your
|
|
bos@559
|
282 <filename role="special"> /.hgrc</filename>, simply add a
|
|
bos@559
|
283 one-line entry to enable the extension.</para>
|
|
bos@559
|
284 <programlisting>[extensions] extdiff =</programlisting>
|
|
bos@559
|
285 <para>This introduces a command named <command
|
|
bos@559
|
286 role="hg-ext-extdiff">extdiff</command>, which by default uses
|
|
bos@559
|
287 your system's <command>diff</command> command to generate a
|
|
bos@559
|
288 unified diff in the same form as the built-in <command
|
|
bos@567
|
289 role="hg-cmd">hg diff</command> command.</para>
|
|
bos@567
|
290
|
|
bos@567
|
291 &interaction.extdiff.extdiff;
|
|
bos@567
|
292
|
|
bos@567
|
293 <para>The result won't be exactly the same as with the built-in
|
|
bos@567
|
294 <command role="hg-cmd">hg diff</command> variations, because the
|
|
bos@567
|
295 output of <command>diff</command> varies from one system to
|
|
bos@567
|
296 another, even when passed the same options.</para>
|
|
bos@559
|
297
|
|
bos@559
|
298 <para>As the <quote><literal>making snapshot</literal></quote>
|
|
bos@559
|
299 lines of output above imply, the <command
|
|
bos@559
|
300 role="hg-ext-extdiff">extdiff</command> command works by
|
|
bos@559
|
301 creating two snapshots of your source tree. The first snapshot
|
|
bos@559
|
302 is of the source revision; the second, of the target revision or
|
|
bos@559
|
303 working directory. The <command
|
|
bos@559
|
304 role="hg-ext-extdiff">extdiff</command> command generates
|
|
bos@559
|
305 these snapshots in a temporary directory, passes the name of
|
|
bos@559
|
306 each directory to an external diff viewer, then deletes the
|
|
bos@559
|
307 temporary directory. For efficiency, it only snapshots the
|
|
bos@559
|
308 directories and files that have changed between the two
|
|
bos@559
|
309 revisions.</para>
|
|
bos@559
|
310
|
|
bos@559
|
311 <para>Snapshot directory names have the same base name as your
|
|
bos@559
|
312 repository. If your repository path is <filename
|
|
bos@559
|
313 class="directory">/quux/bar/foo</filename>, then <filename
|
|
bos@559
|
314 class="directory">foo</filename> will be the name of each
|
|
bos@559
|
315 snapshot directory. Each snapshot directory name has its
|
|
bos@559
|
316 changeset ID appended, if appropriate. If a snapshot is of
|
|
bos@559
|
317 revision <literal>a631aca1083f</literal>, the directory will be
|
|
bos@559
|
318 named <filename class="directory">foo.a631aca1083f</filename>.
|
|
bos@559
|
319 A snapshot of the working directory won't have a changeset ID
|
|
bos@559
|
320 appended, so it would just be <filename
|
|
bos@559
|
321 class="directory">foo</filename> in this example. To see what
|
|
bos@559
|
322 this looks like in practice, look again at the <command
|
|
bos@559
|
323 role="hg-ext-extdiff">extdiff</command> example above. Notice
|
|
bos@559
|
324 that the diff has the snapshot directory names embedded in its
|
|
bos@559
|
325 header.</para>
|
|
bos@559
|
326
|
|
bos@559
|
327 <para>The <command role="hg-ext-extdiff">extdiff</command> command
|
|
bos@559
|
328 accepts two important options. The <option
|
|
bos@559
|
329 role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
|
|
bos@559
|
330 lets you choose a program to view differences with, instead of
|
|
bos@559
|
331 <command>diff</command>. With the <option
|
|
bos@559
|
332 role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
|
|
bos@559
|
333 you can change the options that <command
|
|
bos@559
|
334 role="hg-ext-extdiff">extdiff</command> passes to the program
|
|
bos@559
|
335 (by default, these options are
|
|
bos@559
|
336 <quote><literal>-Npru</literal></quote>, which only make sense
|
|
bos@559
|
337 if you're running <command>diff</command>). In other respects,
|
|
bos@559
|
338 the <command role="hg-ext-extdiff">extdiff</command> command
|
|
bos@559
|
339 acts similarly to the built-in <command role="hg-cmd">hg
|
|
bos@559
|
340 diff</command> command: you use the same option names, syntax,
|
|
bos@559
|
341 and arguments to specify the revisions you want, the files you
|
|
bos@559
|
342 want, and so on.</para>
|
|
bos@559
|
343
|
|
bos@559
|
344 <para>As an example, here's how to run the normal system
|
|
bos@559
|
345 <command>diff</command> command, getting it to generate context
|
|
bos@559
|
346 diffs (using the <option role="cmd-opt-diff">-c</option> option)
|
|
bos@559
|
347 instead of unified diffs, and five lines of context instead of
|
|
bos@559
|
348 the default three (passing <literal>5</literal> as the argument
|
|
bos@567
|
349 to the <option role="cmd-opt-diff">-C</option> option).</para>
|
|
bos@567
|
350
|
|
bos@567
|
351 &interaction.extdiff.extdiff-ctx;
|
|
bos@559
|
352
|
|
bos@559
|
353 <para>Launching a visual diff tool is just as easy. Here's how to
|
|
bos@559
|
354 launch the <command>kdiff3</command> viewer.</para>
|
|
bos@559
|
355 <programlisting>hg extdiff -p kdiff3 -o</programlisting>
|
|
bos@559
|
356
|
|
bos@559
|
357 <para>If your diff viewing command can't deal with directories,
|
|
bos@559
|
358 you can easily work around this with a little scripting. For an
|
|
bos@559
|
359 example of such scripting in action with the <literal
|
|
bos@559
|
360 role="hg-ext">mq</literal> extension and the
|
|
bos@559
|
361 <command>interdiff</command> command, see section <xref
|
|
bos@559
|
362 linkend="mq-collab:tips:interdiff"/>.</para>
|
|
bos@559
|
363
|
|
bos@559
|
364 <sect2>
|
|
bos@559
|
365 <title>Defining command aliases</title>
|
|
bos@559
|
366
|
|
bos@559
|
367 <para>It can be cumbersome to remember the options to both the
|
|
bos@559
|
368 <command role="hg-ext-extdiff">extdiff</command> command and
|
|
bos@559
|
369 the diff viewer you want to use, so the <literal
|
|
bos@559
|
370 role="hg-ext">extdiff</literal> extension lets you define
|
|
bos@559
|
371 <emphasis>new</emphasis> commands that will invoke your diff
|
|
bos@559
|
372 viewer with exactly the right options.</para>
|
|
bos@559
|
373
|
|
bos@559
|
374 <para>All you need to do is edit your <filename role="special">
|
|
bos@559
|
375 /.hgrc</filename>, and add a section named <literal
|
|
bos@559
|
376 role="rc-extdiff">extdiff</literal>. Inside this section,
|
|
bos@559
|
377 you can define multiple commands. Here's how to add a
|
|
bos@559
|
378 <literal>kdiff3</literal> command. Once you've defined this,
|
|
bos@559
|
379 you can type <quote><literal>hg kdiff3</literal></quote> and
|
|
bos@559
|
380 the <literal role="hg-ext">extdiff</literal> extension will
|
|
bos@559
|
381 run <command>kdiff3</command> for you.</para>
|
|
bos@559
|
382 <programlisting>[extdiff] cmd.kdiff3 =</programlisting>
|
|
bos@559
|
383 <para>If you leave the right hand side of the definition empty,
|
|
bos@559
|
384 as above, the <literal role="hg-ext">extdiff</literal>
|
|
bos@559
|
385 extension uses the name of the command you defined as the name
|
|
bos@559
|
386 of the external program to run. But these names don't have to
|
|
bos@559
|
387 be the same. Here, we define a command named
|
|
bos@559
|
388 <quote><literal>hg wibble</literal></quote>, which runs
|
|
bos@559
|
389 <command>kdiff3</command>.</para>
|
|
bos@559
|
390 <programlisting>[extdiff] cmd.wibble = kdiff3</programlisting>
|
|
bos@559
|
391
|
|
bos@559
|
392 <para>You can also specify the default options that you want to
|
|
bos@559
|
393 invoke your diff viewing program with. The prefix to use is
|
|
bos@559
|
394 <quote><literal>opts.</literal></quote>, followed by the name
|
|
bos@559
|
395 of the command to which the options apply. This example
|
|
bos@559
|
396 defines a <quote><literal>hg vimdiff</literal></quote> command
|
|
bos@559
|
397 that runs the <command>vim</command> editor's
|
|
bos@559
|
398 <literal>DirDiff</literal> extension.</para>
|
|
bos@559
|
399 <programlisting>[extdiff] cmd.vimdiff = vim opts.vimdiff = -f
|
|
bos@559
|
400 '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
|
|
bos@559
|
401
|
|
bos@559
|
402 </sect2>
|
|
bos@559
|
403 </sect1>
|
|
bos@559
|
404 <sect1 id="sec:hgext:transplant">
|
|
bos@559
|
405 <title>Cherrypicking changes with the <literal
|
|
bos@559
|
406 role="hg-ext">transplant</literal> extension</title>
|
|
bos@559
|
407
|
|
bos@559
|
408 <para>Need to have a long chat with Brendan about this.</para>
|
|
bos@559
|
409
|
|
bos@559
|
410 </sect1>
|
|
bos@559
|
411 <sect1 id="sec:hgext:patchbomb">
|
|
bos@559
|
412 <title>Send changes via email with the <literal
|
|
bos@559
|
413 role="hg-ext">patchbomb</literal> extension</title>
|
|
bos@559
|
414
|
|
bos@559
|
415 <para>Many projects have a culture of <quote>change
|
|
bos@559
|
416 review</quote>, in which people send their modifications to a
|
|
bos@559
|
417 mailing list for others to read and comment on before they
|
|
bos@559
|
418 commit the final version to a shared repository. Some projects
|
|
bos@559
|
419 have people who act as gatekeepers; they apply changes from
|
|
bos@559
|
420 other people to a repository to which those others don't have
|
|
bos@559
|
421 access.</para>
|
|
bos@559
|
422
|
|
bos@559
|
423 <para>Mercurial makes it easy to send changes over email for
|
|
bos@559
|
424 review or application, via its <literal
|
|
bos@559
|
425 role="hg-ext">patchbomb</literal> extension. The extension is
|
|
ori@561
|
426 so named because changes are formatted as patches, and it's usual
|
|
bos@559
|
427 to send one changeset per email message. Sending a long series
|
|
bos@559
|
428 of changes by email is thus much like <quote>bombing</quote> the
|
|
bos@559
|
429 recipient's inbox, hence <quote>patchbomb</quote>.</para>
|
|
bos@559
|
430
|
|
bos@559
|
431 <para>As usual, the basic configuration of the <literal
|
|
bos@559
|
432 role="hg-ext">patchbomb</literal> extension takes just one or
|
|
bos@559
|
433 two lines in your <filename role="special">
|
|
bos@559
|
434 /.hgrc</filename>.</para>
|
|
bos@559
|
435 <programlisting>[extensions] patchbomb =</programlisting>
|
|
bos@559
|
436 <para>Once you've enabled the extension, you will have a new
|
|
bos@559
|
437 command available, named <command
|
|
bos@559
|
438 role="hg-ext-patchbomb">email</command>.</para>
|
|
bos@559
|
439
|
|
bos@559
|
440 <para>The safest and best way to invoke the <command
|
|
bos@559
|
441 role="hg-ext-patchbomb">email</command> command is to
|
|
bos@559
|
442 <emphasis>always</emphasis> run it first with the <option
|
|
bos@559
|
443 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
|
|
bos@559
|
444 This will show you what the command <emphasis>would</emphasis>
|
|
bos@559
|
445 send, without actually sending anything. Once you've had a
|
|
bos@559
|
446 quick glance over the changes and verified that you are sending
|
|
bos@559
|
447 the right ones, you can rerun the same command, with the <option
|
|
bos@559
|
448 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
|
|
bos@559
|
449 removed.</para>
|
|
bos@559
|
450
|
|
bos@559
|
451 <para>The <command role="hg-ext-patchbomb">email</command> command
|
|
bos@559
|
452 accepts the same kind of revision syntax as every other
|
|
bos@559
|
453 Mercurial command. For example, this command will send every
|
|
bos@559
|
454 revision between 7 and <literal>tip</literal>, inclusive.</para>
|
|
bos@559
|
455 <programlisting>hg email -n 7:tip</programlisting>
|
|
bos@559
|
456 <para>You can also specify a <emphasis>repository</emphasis> to
|
|
bos@559
|
457 compare with. If you provide a repository but no revisions, the
|
|
bos@559
|
458 <command role="hg-ext-patchbomb">email</command> command will
|
|
bos@559
|
459 send all revisions in the local repository that are not present
|
|
bos@559
|
460 in the remote repository. If you additionally specify revisions
|
|
bos@559
|
461 or a branch name (the latter using the <option
|
|
bos@559
|
462 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
|
|
bos@559
|
463 this will constrain the revisions sent.</para>
|
|
bos@559
|
464
|
|
bos@559
|
465 <para>It's perfectly safe to run the <command
|
|
bos@559
|
466 role="hg-ext-patchbomb">email</command> command without the
|
|
bos@559
|
467 names of the people you want to send to: if you do this, it will
|
|
bos@559
|
468 just prompt you for those values interactively. (If you're
|
|
bos@559
|
469 using a Linux or Unix-like system, you should have enhanced
|
|
bos@559
|
470 <literal>readline</literal>-style editing capabilities when
|
|
bos@559
|
471 entering those headers, too, which is useful.)</para>
|
|
bos@559
|
472
|
|
bos@559
|
473 <para>When you are sending just one revision, the <command
|
|
bos@559
|
474 role="hg-ext-patchbomb">email</command> command will by
|
|
bos@559
|
475 default use the first line of the changeset description as the
|
|
bos@559
|
476 subject of the single email message it sends.</para>
|
|
bos@559
|
477
|
|
bos@559
|
478 <para>If you send multiple revisions, the <command
|
|
bos@559
|
479 role="hg-ext-patchbomb">email</command> command will usually
|
|
bos@559
|
480 send one message per changeset. It will preface the series with
|
|
bos@559
|
481 an introductory message, in which you should describe the
|
|
bos@559
|
482 purpose of the series of changes you're sending.</para>
|
|
bos@559
|
483
|
|
bos@559
|
484 <sect2>
|
|
bos@559
|
485 <title>Changing the behaviour of patchbombs</title>
|
|
bos@559
|
486
|
|
bos@559
|
487 <para>Not every project has exactly the same conventions for
|
|
bos@559
|
488 sending changes in email; the <literal
|
|
bos@559
|
489 role="hg-ext">patchbomb</literal> extension tries to
|
|
bos@559
|
490 accommodate a number of variations through command line
|
|
bos@559
|
491 options.</para>
|
|
bos@559
|
492 <itemizedlist>
|
|
bos@559
|
493 <listitem><para>You can write a subject for the introductory
|
|
bos@559
|
494 message on the command line using the <option
|
|
bos@559
|
495 role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
|
|
bos@559
|
496 option. This takes one argument, the text of the subject
|
|
bos@559
|
497 to use.</para>
|
|
bos@559
|
498 </listitem>
|
|
bos@559
|
499 <listitem><para>To change the email address from which the
|
|
bos@559
|
500 messages originate, use the <option
|
|
bos@559
|
501 role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
|
|
bos@559
|
502 option. This takes one argument, the email address to
|
|
bos@559
|
503 use.</para>
|
|
bos@559
|
504 </listitem>
|
|
bos@559
|
505 <listitem><para>The default behaviour is to send unified diffs
|
|
bos@559
|
506 (see section <xref linkend="sec:mq:patch"/> for a
|
|
bos@559
|
507 description of the
|
|
bos@559
|
508 format), one per message. You can send a binary bundle
|
|
bos@559
|
509 instead with the <option
|
|
bos@559
|
510 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
|
|
bos@559
|
511 option.</para>
|
|
bos@559
|
512 </listitem>
|
|
bos@559
|
513 <listitem><para>Unified diffs are normally prefaced with a
|
|
bos@559
|
514 metadata header. You can omit this, and send unadorned
|
|
bos@559
|
515 diffs, with the <option
|
|
bos@559
|
516 role="hg-ext-patchbomb-cmd-email-opt">hg
|
|
bos@559
|
517 --plain</option> option.</para>
|
|
bos@559
|
518 </listitem>
|
|
bos@559
|
519 <listitem><para>Diffs are normally sent <quote>inline</quote>,
|
|
bos@559
|
520 in the same body part as the description of a patch. This
|
|
bos@559
|
521 makes it easiest for the largest number of readers to
|
|
bos@559
|
522 quote and respond to parts of a diff, as some mail clients
|
|
bos@559
|
523 will only quote the first MIME body part in a message. If
|
|
bos@559
|
524 you'd prefer to send the description and the diff in
|
|
bos@559
|
525 separate body parts, use the <option
|
|
bos@559
|
526 role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
|
|
bos@559
|
527 option.</para>
|
|
bos@559
|
528 </listitem>
|
|
bos@559
|
529 <listitem><para>Instead of sending mail messages, you can
|
|
bos@559
|
530 write them to an <literal>mbox</literal>-format mail
|
|
bos@559
|
531 folder using the <option
|
|
bos@559
|
532 role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
|
|
bos@559
|
533 option. That option takes one argument, the name of the
|
|
bos@559
|
534 file to write to.</para>
|
|
bos@559
|
535 </listitem>
|
|
bos@559
|
536 <listitem><para>If you would like to add a
|
|
bos@559
|
537 <command>diffstat</command>-format summary to each patch,
|
|
bos@559
|
538 and one to the introductory message, use the <option
|
|
bos@559
|
539 role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
|
|
bos@559
|
540 option. The <command>diffstat</command> command displays
|
|
bos@559
|
541 a table containing the name of each file patched, the
|
|
bos@559
|
542 number of lines affected, and a histogram showing how much
|
|
bos@559
|
543 each file is modified. This gives readers a qualitative
|
|
bos@559
|
544 glance at how complex a patch is.</para>
|
|
bos@559
|
545 </listitem></itemizedlist>
|
|
bos@559
|
546
|
|
bos@559
|
547 </sect2>
|
|
bos@559
|
548 </sect1>
|
|
bos@559
|
549 </chapter>
|
|
bos@559
|
550
|
|
bos@559
|
551 <!--
|
|
bos@559
|
552 local variables:
|
|
bos@559
|
553 sgml-parent-document: ("00book.xml" "book" "chapter")
|
|
bos@559
|
554 end:
|
|
bos@559
|
555 -->
|
