hgbook
diff fr/ch14-hgext.xml @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
parents | 6b680d569bb4 f0110009e946 |
children |
line diff
1.1 --- a/fr/ch14-hgext.xml Sun Aug 16 04:58:01 2009 +0200 1.2 +++ b/fr/ch14-hgext.xml Sun Dec 13 16:35:56 2009 +0900 1.3 @@ -1,539 +1,554 @@ 1.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 1.6 -<chapter> 1.7 -<title>Adding functionality with extensions</title> 1.8 -<para>\label{chap:hgext}</para> 1.9 - 1.10 -<para>While the core of Mercurial is quite complete from a functionality 1.11 -standpoint, it's deliberately shorn of fancy features. This approach 1.12 -of preserving simplicity keeps the software easy to deal with for both 1.13 -maintainers and users.</para> 1.14 - 1.15 -<para>However, Mercurial doesn't box you in with an inflexible command set: 1.16 -you can add features to it as <emphasis>extensions</emphasis> (sometimes known as 1.17 -<emphasis>plugins</emphasis>). We've already discussed a few of these extensions in 1.18 -earlier chapters.</para> 1.19 -<itemizedlist> 1.20 -<listitem><para>Section <xref linkend="sec:tour-merge:fetch"/> covers the <literal role="hg-ext">fetch</literal> 1.21 - extension; this combines pulling new changes and merging them with 1.22 - local changes into a single command, <command role="hg-ext-fetch">fetch</command>.</para> 1.23 -</listitem> 1.24 -<listitem><para>In chapter <xref linkend="chap:hook"/>, we covered several extensions that 1.25 - are useful for hook-related functionality: <literal role="hg-ext">acl</literal> adds access 1.26 - control lists; <literal role="hg-ext">bugzilla</literal> adds integration with the Bugzilla 1.27 - bug tracking system; and <literal role="hg-ext">notify</literal> sends notification emails on 1.28 - new changes.</para> 1.29 -</listitem> 1.30 -<listitem><para>The Mercurial Queues patch management extension is so invaluable 1.31 - that it merits two chapters and an appendix all to itself. 1.32 - Chapter <xref linkend="chap:mq"/> covers the basics; 1.33 - chapter <xref linkend="chap:mq-collab"/> discusses advanced topics; and 1.34 - appendix <xref linkend="chap:mqref"/> goes into detail on each command.</para> 1.35 -</listitem></itemizedlist> 1.36 - 1.37 -<para>In this chapter, we'll cover some of the other extensions that are 1.38 -available for Mercurial, and briefly touch on some of the machinery 1.39 -you'll need to know about if you want to write an extension of your 1.40 -own.</para> 1.41 -<itemizedlist> 1.42 -<listitem><para>In section <xref linkend="sec:hgext:inotify"/>, we'll discuss the 1.43 - possibility of <emphasis>huge</emphasis> performance improvements using the 1.44 - <literal role="hg-ext">inotify</literal> extension.</para> 1.45 -</listitem></itemizedlist> 1.46 - 1.47 -<sect1> 1.48 -<title>Improve performance with the <literal role="hg-ext">inotify</literal> extension</title> 1.49 -<para>\label{sec:hgext:inotify} 1.50 -</para> 1.51 - 1.52 -<para>Are you interested in having some of the most common Mercurial 1.53 -operations run as much as a hundred times faster? Read on! 1.54 -</para> 1.55 - 1.56 -<para>Mercurial has great performance under normal circumstances. For 1.57 -example, when you run the <command role="hg-cmd">hg status</command> command, Mercurial has to 1.58 -scan almost every directory and file in your repository so that it can 1.59 -display file status. Many other Mercurial commands need to do the 1.60 -same work behind the scenes; for example, the <command role="hg-cmd">hg diff</command> command 1.61 -uses the status machinery to avoid doing an expensive comparison 1.62 -operation on files that obviously haven't changed. 1.63 -</para> 1.64 - 1.65 -<para>Because obtaining file status is crucial to good performance, the 1.66 -authors of Mercurial have optimised this code to within an inch of its 1.67 -life. However, there's no avoiding the fact that when you run 1.68 -<command role="hg-cmd">hg status</command>, Mercurial is going to have to perform at least one 1.69 -expensive system call for each managed file to determine whether it's 1.70 -changed since the last time Mercurial checked. For a sufficiently 1.71 -large repository, this can take a long time. 1.72 -</para> 1.73 - 1.74 -<para>To put a number on the magnitude of this effect, I created a 1.75 -repository containing 150,000 managed files. I timed <command role="hg-cmd">hg status</command> 1.76 -as taking ten seconds to run, even when <emphasis>none</emphasis> of those files had 1.77 -been modified. 1.78 -</para> 1.79 - 1.80 -<para>Many modern operating systems contain a file notification facility. 1.81 -If a program signs up to an appropriate service, the operating system 1.82 -will notify it every time a file of interest is created, modified, or 1.83 -deleted. On Linux systems, the kernel component that does this is 1.84 -called <literal>inotify</literal>. 1.85 -</para> 1.86 - 1.87 -<para>Mercurial's <literal role="hg-ext">inotify</literal> extension talks to the kernel's 1.88 -<literal>inotify</literal> component to optimise <command role="hg-cmd">hg status</command> commands. The 1.89 -extension has two components. A daemon sits in the background and 1.90 -receives notifications from the <literal>inotify</literal> subsystem. It also 1.91 -listens for connections from a regular Mercurial command. The 1.92 -extension modifies Mercurial's behaviour so that instead of scanning 1.93 -the filesystem, it queries the daemon. Since the daemon has perfect 1.94 -information about the state of the repository, it can respond with a 1.95 -result instantaneously, avoiding the need to scan every directory and 1.96 -file in the repository. 1.97 -</para> 1.98 - 1.99 -<para>Recall the ten seconds that I measured plain Mercurial as taking to 1.100 -run <command role="hg-cmd">hg status</command> on a 150,000 file repository. With the 1.101 -<literal role="hg-ext">inotify</literal> extension enabled, the time dropped to 0.1 seconds, a 1.102 -factor of <emphasis>one hundred</emphasis> faster. 1.103 -</para> 1.104 - 1.105 -<para>Before we continue, please pay attention to some caveats. 1.106 -</para> 1.107 -<itemizedlist> 1.108 -<listitem><para>The <literal role="hg-ext">inotify</literal> extension is Linux-specific. Because it 1.109 - interfaces directly to the Linux kernel's <literal>inotify</literal> 1.110 - subsystem, it does not work on other operating systems. 1.111 -</para> 1.112 -</listitem> 1.113 -<listitem><para>It should work on any Linux distribution that was released after 1.114 - early 2005. Older distributions are likely to have a kernel that 1.115 - lacks <literal>inotify</literal>, or a version of <literal>glibc</literal> that does not 1.116 - have the necessary interfacing support. 1.117 -</para> 1.118 -</listitem> 1.119 -<listitem><para>Not all filesystems are suitable for use with the 1.120 - <literal role="hg-ext">inotify</literal> extension. Network filesystems such as NFS are a 1.121 - non-starter, for example, particularly if you're running Mercurial 1.122 - on several systems, all mounting the same network filesystem. The 1.123 - kernel's <literal>inotify</literal> system has no way of knowing about changes 1.124 - made on another system. Most local filesystems (e.g. ext3, XFS, 1.125 - ReiserFS) should work fine. 1.126 -</para> 1.127 -</listitem></itemizedlist> 1.128 - 1.129 -<para>The <literal role="hg-ext">inotify</literal> extension is not yet shipped with Mercurial as of 1.130 -May 2007, so it's a little more involved to set up than other 1.131 -extensions. But the performance improvement is worth it! 1.132 -</para> 1.133 - 1.134 -<para>The extension currently comes in two parts: a set of patches to the 1.135 -Mercurial source code, and a library of Python bindings to the 1.136 -<literal>inotify</literal> subsystem. 1.137 -</para> 1.138 -<note> 1.139 -<para> There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding libraries. One 1.140 - of them is called <literal>pyinotify</literal>, and is packaged by some Linux 1.141 - distributions as <literal>python-inotify</literal>. This is <emphasis>not</emphasis> the 1.142 - one you'll need, as it is too buggy and inefficient to be practical. 1.143 -</para> 1.144 -</note> 1.145 -<para>To get going, it's best to already have a functioning copy of 1.146 -Mercurial installed. 1.147 -</para> 1.148 -<note> 1.149 -<para> If you follow the instructions below, you'll be <emphasis>replacing</emphasis> and 1.150 - overwriting any existing installation of Mercurial that you might 1.151 - already have, using the latest <quote>bleeding edge</quote> Mercurial code. 1.152 - Don't say you weren't warned! 1.153 -</para> 1.154 -</note> 1.155 -<orderedlist> 1.156 -<listitem><para>Clone the Python <literal>inotify</literal> binding repository. Build and 1.157 - install it. 1.158 -</para> 1.159 -</listitem><programlisting> 1.160 -<listitem><para> hg clone http://hg.kublai.com/python/inotify 1.161 - cd inotify 1.162 - python setup.py build --force 1.163 - sudo python setup.py install --skip-build 1.164 -</para> 1.165 -</listitem></programlisting> 1.166 -</para> 1.167 -</listitem> 1.168 -<listitem><para>Clone the <filename class="directory">crew</filename> Mercurial repository. Clone the 1.169 - <literal role="hg-ext">inotify</literal> patch repository so that Mercurial Queues will be 1.170 - able to apply patches to your cope of the <filename class="directory">crew</filename> repository. 1.171 -</para> 1.172 -</listitem><programlisting> 1.173 -<listitem><para> hg clone http://hg.intevation.org/mercurial/crew 1.174 - hg clone crew inotify 1.175 - hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches 1.176 -</para> 1.177 -</listitem></programlisting> 1.178 -</para> 1.179 -</listitem> 1.180 -<listitem><para>Make sure that you have the Mercurial Queues extension, 1.181 - <literal role="hg-ext">mq</literal>, enabled. If you've never used MQ, read 1.182 - section <xref linkend="sec:mq:start"/> to get started quickly. 1.183 -</para> 1.184 -</listitem> 1.185 -<listitem><para>Go into the <filename class="directory">inotify</filename> repo, and apply all of the 1.186 - <literal role="hg-ext">inotify</literal> patches using the <option role="hg-ext-mq-cmd-qpush-opt">-a</option> option to 1.187 - the <command role="hg-ext-mq">qpush</command> command. 1.188 -</para> 1.189 -</listitem><programlisting> 1.190 -<listitem><para> cd inotify 1.191 - hg qpush -a 1.192 -</para> 1.193 -</listitem></programlisting> 1.194 -<listitem><para> If you get an error message from <command role="hg-ext-mq">qpush</command>, you should not 1.195 - continue. Instead, ask for help. 1.196 -</para> 1.197 -</listitem> 1.198 -<listitem><para>Build and install the patched version of Mercurial. 1.199 -</para> 1.200 -</listitem><programlisting> 1.201 -<listitem><para> python setup.py build --force 1.202 - sudo python setup.py install --skip-build 1.203 -</para> 1.204 -</listitem></programlisting> 1.205 -</orderedlist> 1.206 -<para>Once you've build a suitably patched version of Mercurial, all you 1.207 -need to do to enable the <literal role="hg-ext">inotify</literal> extension is add an entry to 1.208 -your <filename role="special"> /.hgrc</filename>. 1.209 -</para> 1.210 -<programlisting> 1.211 -<para> [extensions] 1.212 - inotify = 1.213 -</para> 1.214 -</programlisting> 1.215 -<para>When the <literal role="hg-ext">inotify</literal> extension is enabled, Mercurial will 1.216 -automatically and transparently start the status daemon the first time 1.217 -you run a command that needs status in a repository. It runs one 1.218 -status daemon per repository. 1.219 -</para> 1.220 - 1.221 -<para>The status daemon is started silently, and runs in the background. If 1.222 -you look at a list of running processes after you've enabled the 1.223 -<literal role="hg-ext">inotify</literal> extension and run a few commands in different 1.224 -repositories, you'll thus see a few <literal>hg</literal> processes sitting 1.225 -around, waiting for updates from the kernel and queries from 1.226 -Mercurial. 1.227 -</para> 1.228 - 1.229 -<para>The first time you run a Mercurial command in a repository when you 1.230 -have the <literal role="hg-ext">inotify</literal> extension enabled, it will run with about the 1.231 -same performance as a normal Mercurial command. This is because the 1.232 -status daemon needs to perform a normal status scan so that it has a 1.233 -baseline against which to apply later updates from the kernel. 1.234 -However, <emphasis>every</emphasis> subsequent command that does any kind of status 1.235 -check should be noticeably faster on repositories of even fairly 1.236 -modest size. Better yet, the bigger your repository is, the greater a 1.237 -performance advantage you'll see. The <literal role="hg-ext">inotify</literal> daemon makes 1.238 -status operations almost instantaneous on repositories of all sizes! 1.239 -</para> 1.240 - 1.241 -<para>If you like, you can manually start a status daemon using the 1.242 -<command role="hg-ext-inotify">inserve</command> command. This gives you slightly finer 1.243 -control over how the daemon ought to run. This command will of course 1.244 -only be available when the <literal role="hg-ext">inotify</literal> extension is enabled. 1.245 -</para> 1.246 - 1.247 -<para>When you're using the <literal role="hg-ext">inotify</literal> extension, you should notice 1.248 -<emphasis>no difference at all</emphasis> in Mercurial's behaviour, with the sole 1.249 -exception of status-related commands running a whole lot faster than 1.250 -they used to. You should specifically expect that commands will not 1.251 -print different output; neither should they give different results. 1.252 -If either of these situations occurs, please report a bug. 1.253 -</para> 1.254 - 1.255 -</sect1> 1.256 -<sect1> 1.257 -<title>Flexible diff support with the <literal role="hg-ext">extdiff</literal> extension</title> 1.258 -<para>\label{sec:hgext:extdiff} 1.259 -</para> 1.260 - 1.261 -<para>Mercurial's built-in <command role="hg-cmd">hg diff</command> command outputs plaintext unified 1.262 -diffs. 1.263 -<!-- &interaction.extdiff.diff; --> 1.264 -If you would like to use an external tool to display modifications, 1.265 -you'll want to use the <literal role="hg-ext">extdiff</literal> extension. This will let you 1.266 -use, for example, a graphical diff tool. 1.267 -</para> 1.268 - 1.269 -<para>The <literal role="hg-ext">extdiff</literal> extension is bundled with Mercurial, so it's easy 1.270 -to set up. In the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>, 1.271 -simply add a one-line entry to enable the extension. 1.272 -</para> 1.273 -<programlisting> 1.274 -<para> [extensions] 1.275 - extdiff = 1.276 -</para> 1.277 -</programlisting> 1.278 -<para>This introduces a command named <command role="hg-ext-extdiff">extdiff</command>, which by 1.279 -default uses your system's <command>diff</command> command to generate a 1.280 -unified diff in the same form as the built-in <command role="hg-cmd">hg diff</command> command. 1.281 -<!-- &interaction.extdiff.extdiff; --> 1.282 -The result won't be exactly the same as with the built-in <command role="hg-cmd">hg diff</command> 1.283 -variations, because the output of <command>diff</command> varies from one 1.284 -system to another, even when passed the same options. 1.285 -</para> 1.286 - 1.287 -<para>As the <quote><literal>making snapshot</literal></quote> lines of output above imply, the 1.288 -<command role="hg-ext-extdiff">extdiff</command> command works by creating two snapshots of 1.289 -your source tree. The first snapshot is of the source revision; the 1.290 -second, of the target revision or working directory. The 1.291 -<command role="hg-ext-extdiff">extdiff</command> command generates these snapshots in a 1.292 -temporary directory, passes the name of each directory to an external 1.293 -diff viewer, then deletes the temporary directory. For efficiency, it 1.294 -only snapshots the directories and files that have changed between the 1.295 -two revisions. 1.296 -</para> 1.297 - 1.298 -<para>Snapshot directory names have the same base name as your repository. 1.299 -If your repository path is <filename class="directory">/quux/bar/foo</filename>, then <filename class="directory">foo</filename> 1.300 -will be the name of each snapshot directory. Each snapshot directory 1.301 -name has its changeset ID appended, if appropriate. If a snapshot is 1.302 -of revision <literal>a631aca1083f</literal>, the directory will be named 1.303 -<filename class="directory">foo.a631aca1083f</filename>. A snapshot of the working directory won't 1.304 -have a changeset ID appended, so it would just be <filename class="directory">foo</filename> in 1.305 -this example. To see what this looks like in practice, look again at 1.306 -the <command role="hg-ext-extdiff">extdiff</command> example above. Notice that the diff has 1.307 -the snapshot directory names embedded in its header. 1.308 -</para> 1.309 - 1.310 -<para>The <command role="hg-ext-extdiff">extdiff</command> command accepts two important options. 1.311 -The <option role="hg-ext-extdiff-cmd-extdiff-opt">-p</option> option lets you choose a program to 1.312 -view differences with, instead of <command>diff</command>. With the 1.313 -<option role="hg-ext-extdiff-cmd-extdiff-opt">-o</option> option, you can change the options that 1.314 -<command role="hg-ext-extdiff">extdiff</command> passes to the program (by default, these 1.315 -options are <quote><literal>-Npru</literal></quote>, which only make sense if you're 1.316 -running <command>diff</command>). In other respects, the 1.317 -<command role="hg-ext-extdiff">extdiff</command> command acts similarly to the built-in 1.318 -<command role="hg-cmd">hg diff</command> command: you use the same option names, syntax, and 1.319 -arguments to specify the revisions you want, the files you want, and 1.320 -so on. 1.321 -</para> 1.322 - 1.323 -<para>As an example, here's how to run the normal system <command>diff</command> 1.324 -command, getting it to generate context diffs (using the 1.325 -<option role="cmd-opt-diff">-c</option> option) instead of unified diffs, and five lines of 1.326 -context instead of the default three (passing <literal>5</literal> as the 1.327 -argument to the <option role="cmd-opt-diff">-C</option> option). 1.328 -<!-- &interaction.extdiff.extdiff-ctx; --> 1.329 -</para> 1.330 - 1.331 -<para>Launching a visual diff tool is just as easy. Here's how to launch 1.332 -the <command>kdiff3</command> viewer. 1.333 -</para> 1.334 -<programlisting> 1.335 -<para> hg extdiff -p kdiff3 -o </quote> 1.336 -</para> 1.337 -</programlisting> 1.338 - 1.339 -<para>If your diff viewing command can't deal with directories, you can 1.340 -easily work around this with a little scripting. For an example of 1.341 -such scripting in action with the <literal role="hg-ext">mq</literal> extension and the 1.342 -<command>interdiff</command> command, see 1.343 -section <xref linkend="mq-collab:tips:interdiff"/>. 1.344 -</para> 1.345 - 1.346 -<sect2> 1.347 -<title>Defining command aliases</title> 1.348 - 1.349 -<para>It can be cumbersome to remember the options to both the 1.350 -<command role="hg-ext-extdiff">extdiff</command> command and the diff viewer you want to use, 1.351 -so the <literal role="hg-ext">extdiff</literal> extension lets you define <emphasis>new</emphasis> commands 1.352 -that will invoke your diff viewer with exactly the right options. 1.353 -</para> 1.354 - 1.355 -<para>All you need to do is edit your <filename role="special"> /.hgrc</filename>, and add a section named 1.356 -<literal role="rc-extdiff">extdiff</literal>. Inside this section, you can define multiple 1.357 -commands. Here's how to add a <literal>kdiff3</literal> command. Once you've 1.358 -defined this, you can type <quote><literal>hg kdiff3</literal></quote> and the 1.359 -<literal role="hg-ext">extdiff</literal> extension will run <command>kdiff3</command> for you. 1.360 -</para> 1.361 -<programlisting> 1.362 -<para> [extdiff] 1.363 - cmd.kdiff3 = 1.364 -</para> 1.365 -</programlisting> 1.366 -<para>If you leave the right hand side of the definition empty, as above, 1.367 -the <literal role="hg-ext">extdiff</literal> extension uses the name of the command you defined 1.368 -as the name of the external program to run. But these names don't 1.369 -have to be the same. Here, we define a command named <quote>\texttt{hg 1.370 - wibble}</quote>, which runs <command>kdiff3</command>. 1.371 -</para> 1.372 -<programlisting> 1.373 -<para> [extdiff] 1.374 - cmd.wibble = kdiff3 1.375 -</para> 1.376 -</programlisting> 1.377 - 1.378 -<para>You can also specify the default options that you want to invoke your 1.379 -diff viewing program with. The prefix to use is <quote><literal>opts.</literal></quote>, 1.380 -followed by the name of the command to which the options apply. This 1.381 -example defines a <quote><literal>hg vimdiff</literal></quote> command that runs the 1.382 -<command>vim</command> editor's <literal>DirDiff</literal> extension. 1.383 -</para> 1.384 -<programlisting> 1.385 -<para> [extdiff] 1.386 - cmd.vimdiff = vim 1.387 - opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)' 1.388 -</para> 1.389 -</programlisting> 1.390 - 1.391 -</sect2> 1.392 -</sect1> 1.393 -<sect1> 1.394 -<title>Cherrypicking changes with the <literal role="hg-ext">transplant</literal> extension</title> 1.395 -<para>\label{sec:hgext:transplant} 1.396 -</para> 1.397 - 1.398 -<para>Need to have a long chat with Brendan about this. 1.399 -</para> 1.400 - 1.401 -</sect1> 1.402 -<sect1> 1.403 -<title>Send changes via email with the <literal role="hg-ext">patchbomb</literal> extension</title> 1.404 -<para>\label{sec:hgext:patchbomb} 1.405 -</para> 1.406 - 1.407 -<para>Many projects have a culture of <quote>change review</quote>, in which people 1.408 -send their modifications to a mailing list for others to read and 1.409 -comment on before they commit the final version to a shared 1.410 -repository. Some projects have people who act as gatekeepers; they 1.411 -apply changes from other people to a repository to which those others 1.412 -don't have access. 1.413 -</para> 1.414 - 1.415 -<para>Mercurial makes it easy to send changes over email for review or 1.416 -application, via its <literal role="hg-ext">patchbomb</literal> extension. The extension is so 1.417 -namd because changes are formatted as patches, and it's usual to send 1.418 -one changeset per email message. Sending a long series of changes by 1.419 -email is thus much like <quote>bombing</quote> the recipient's inbox, hence 1.420 -<quote>patchbomb</quote>. 1.421 -</para> 1.422 - 1.423 -<para>As usual, the basic configuration of the <literal role="hg-ext">patchbomb</literal> extension 1.424 -takes just one or two lines in your <filename role="special"> /.hgrc</filename>. 1.425 -</para> 1.426 -<programlisting> 1.427 -<para> [extensions] 1.428 - patchbomb = 1.429 -</para> 1.430 -</programlisting> 1.431 -<para>Once you've enabled the extension, you will have a new command 1.432 -available, named <command role="hg-ext-patchbomb">email</command>. 1.433 -</para> 1.434 - 1.435 -<para>The safest and best way to invoke the <command role="hg-ext-patchbomb">email</command> 1.436 -command is to <emphasis>always</emphasis> run it first with the 1.437 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option. This will show you what the 1.438 -command <emphasis>would</emphasis> send, without actually sending anything. Once 1.439 -you've had a quick glance over the changes and verified that you are 1.440 -sending the right ones, you can rerun the same command, with the 1.441 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option removed. 1.442 -</para> 1.443 - 1.444 -<para>The <command role="hg-ext-patchbomb">email</command> command accepts the same kind of 1.445 -revision syntax as every other Mercurial command. For example, this 1.446 -command will send every revision between 7 and <literal>tip</literal>, 1.447 -inclusive. 1.448 -</para> 1.449 -<programlisting> 1.450 -<para> hg email -n 7:tip 1.451 -</para> 1.452 -</programlisting> 1.453 -<para>You can also specify a <emphasis>repository</emphasis> to compare with. If you 1.454 -provide a repository but no revisions, the <command role="hg-ext-patchbomb">email</command> 1.455 -command will send all revisions in the local repository that are not 1.456 -present in the remote repository. If you additionally specify 1.457 -revisions or a branch name (the latter using the 1.458 -<option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option), this will constrain the 1.459 -revisions sent. 1.460 -</para> 1.461 - 1.462 -<para>It's perfectly safe to run the <command role="hg-ext-patchbomb">email</command> command 1.463 -without the names of the people you want to send to: if you do this, 1.464 -it will just prompt you for those values interactively. (If you're 1.465 -using a Linux or Unix-like system, you should have enhanced 1.466 -<literal>readline</literal>-style editing capabilities when entering those 1.467 -headers, too, which is useful.) 1.468 -</para> 1.469 - 1.470 -<para>When you are sending just one revision, the <command role="hg-ext-patchbomb">email</command> 1.471 -command will by default use the first line of the changeset 1.472 -description as the subject of the single email message it sends. 1.473 -</para> 1.474 - 1.475 -<para>If you send multiple revisions, the <command role="hg-ext-patchbomb">email</command> command 1.476 -will usually send one message per changeset. It will preface the 1.477 -series with an introductory message, in which you should describe the 1.478 -purpose of the series of changes you're sending. 1.479 -</para> 1.480 - 1.481 -<sect2> 1.482 -<title>Changing the behaviour of patchbombs</title> 1.483 - 1.484 -<para>Not every project has exactly the same conventions for sending changes 1.485 -in email; the <literal role="hg-ext">patchbomb</literal> extension tries to accommodate a 1.486 -number of variations through command line options. 1.487 -</para> 1.488 -<itemizedlist> 1.489 -<listitem><para>You can write a subject for the introductory message on the 1.490 - command line using the <option role="hg-ext-patchbomb-cmd-email-opt">-s</option> option. This 1.491 - takes one argument, the text of the subject to use. 1.492 -</para> 1.493 -</listitem> 1.494 -<listitem><para>To change the email address from which the messages originate, 1.495 - use the <option role="hg-ext-patchbomb-cmd-email-opt">-f</option> option. This takes one 1.496 - argument, the email address to use. 1.497 -</para> 1.498 -</listitem> 1.499 -<listitem><para>The default behaviour is to send unified diffs (see 1.500 - section <xref linkend="sec:mq:patch"/> for a description of the format), one per 1.501 - message. You can send a binary bundle instead with the 1.502 - <option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option. 1.503 -</para> 1.504 -</listitem> 1.505 -<listitem><para>Unified diffs are normally prefaced with a metadata header. You 1.506 - can omit this, and send unadorned diffs, with the 1.507 - <option role="hg-ext-patchbomb-cmd-email-opt">--plain</option> option. 1.508 -</para> 1.509 -</listitem> 1.510 -<listitem><para>Diffs are normally sent <quote>inline</quote>, in the same body part as the 1.511 - description of a patch. This makes it easiest for the largest 1.512 - number of readers to quote and respond to parts of a diff, as some 1.513 - mail clients will only quote the first MIME body part in a message. 1.514 - If you'd prefer to send the description and the diff in separate 1.515 - body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">-a</option> option. 1.516 -</para> 1.517 -</listitem> 1.518 -<listitem><para>Instead of sending mail messages, you can write them to an 1.519 - <literal>mbox</literal>-format mail folder using the 1.520 - <option role="hg-ext-patchbomb-cmd-email-opt">-m</option> option. That option takes one 1.521 - argument, the name of the file to write to. 1.522 -</para> 1.523 -</listitem> 1.524 -<listitem><para>If you would like to add a <command>diffstat</command>-format summary to 1.525 - each patch, and one to the introductory message, use the 1.526 - <option role="hg-ext-patchbomb-cmd-email-opt">-d</option> option. The <command>diffstat</command> 1.527 - command displays a table containing the name of each file patched, 1.528 - the number of lines affected, and a histogram showing how much each 1.529 - file is modified. This gives readers a qualitative glance at how 1.530 - complex a patch is. 1.531 -</para> 1.532 -</listitem></itemizedlist> 1.533 - 1.534 -</sect2> 1.535 -</sect1> 1.536 +<chapter id="chap:hgext"> 1.537 + <?dbhtml filename="adding-functionality-with-extensions.html"?> 1.538 + <title>Adding functionality with extensions</title> 1.539 + 1.540 + <para id="x_4fe">While the core of Mercurial is quite complete from a 1.541 + functionality standpoint, it's deliberately shorn of fancy 1.542 + features. This approach of preserving simplicity keeps the 1.543 + software easy to deal with for both maintainers and users.</para> 1.544 + 1.545 + <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 1.546 + command set: you can add features to it as 1.547 + <emphasis>extensions</emphasis> (sometimes known as 1.548 + <emphasis>plugins</emphasis>). We've already discussed a few of 1.549 + these extensions in earlier chapters.</para> 1.550 + <itemizedlist> 1.551 + <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/> 1.552 + covers the <literal role="hg-ext">fetch</literal> extension; 1.553 + this combines pulling new changes and merging them with local 1.554 + changes into a single command, <command 1.555 + role="hg-ext-fetch">fetch</command>.</para> 1.556 + </listitem> 1.557 + <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered 1.558 + several extensions that are useful for hook-related 1.559 + functionality: <literal role="hg-ext">acl</literal> adds 1.560 + access control lists; <literal 1.561 + role="hg-ext">bugzilla</literal> adds integration with the 1.562 + Bugzilla bug tracking system; and <literal 1.563 + role="hg-ext">notify</literal> sends notification emails on 1.564 + new changes.</para> 1.565 + </listitem> 1.566 + <listitem><para id="x_502">The Mercurial Queues patch management extension is 1.567 + so invaluable that it merits two chapters and an appendix all 1.568 + to itself. <xref linkend="chap:mq"/> covers the 1.569 + basics; <xref 1.570 + linkend="chap:mq-collab"/> discusses advanced topics; 1.571 + and <xref linkend="chap:mqref"/> goes into detail on 1.572 + each 1.573 + command.</para> 1.574 + </listitem></itemizedlist> 1.575 + 1.576 + <para id="x_503">In this chapter, we'll cover some of the other extensions that 1.577 + are available for Mercurial, and briefly touch on some of the 1.578 + machinery you'll need to know about if you want to write an 1.579 + extension of your own.</para> 1.580 + <itemizedlist> 1.581 + <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>, 1.582 + we'll discuss the possibility of <emphasis>huge</emphasis> 1.583 + performance improvements using the <literal 1.584 + role="hg-ext">inotify</literal> extension.</para> 1.585 + </listitem></itemizedlist> 1.586 + 1.587 + <sect1 id="sec:hgext:inotify"> 1.588 + <title>Improve performance with the <literal 1.589 + role="hg-ext">inotify</literal> extension</title> 1.590 + 1.591 + <para id="x_505">Are you interested in having some of the most common 1.592 + Mercurial operations run as much as a hundred times faster? 1.593 + Read on!</para> 1.594 + 1.595 + <para id="x_506">Mercurial has great performance under normal circumstances. 1.596 + For example, when you run the <command role="hg-cmd">hg 1.597 + status</command> command, Mercurial has to scan almost every 1.598 + directory and file in your repository so that it can display 1.599 + file status. Many other Mercurial commands need to do the same 1.600 + work behind the scenes; for example, the <command 1.601 + role="hg-cmd">hg diff</command> command uses the status 1.602 + machinery to avoid doing an expensive comparison operation on 1.603 + files that obviously haven't changed.</para> 1.604 + 1.605 + <para id="x_507">Because obtaining file status is crucial to good 1.606 + performance, the authors of Mercurial have optimised this code 1.607 + to within an inch of its life. However, there's no avoiding the 1.608 + fact that when you run <command role="hg-cmd">hg 1.609 + status</command>, Mercurial is going to have to perform at 1.610 + least one expensive system call for each managed file to 1.611 + determine whether it's changed since the last time Mercurial 1.612 + checked. For a sufficiently large repository, this can take a 1.613 + long time.</para> 1.614 + 1.615 + <para id="x_508">To put a number on the magnitude of this effect, I created a 1.616 + repository containing 150,000 managed files. I timed <command 1.617 + role="hg-cmd">hg status</command> as taking ten seconds to 1.618 + run, even when <emphasis>none</emphasis> of those files had been 1.619 + modified.</para> 1.620 + 1.621 + <para id="x_509">Many modern operating systems contain a file notification 1.622 + facility. If a program signs up to an appropriate service, the 1.623 + operating system will notify it every time a file of interest is 1.624 + created, modified, or deleted. On Linux systems, the kernel 1.625 + component that does this is called 1.626 + <literal>inotify</literal>.</para> 1.627 + 1.628 + <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 1.629 + extension talks to the kernel's <literal>inotify</literal> 1.630 + component to optimise <command role="hg-cmd">hg status</command> 1.631 + commands. The extension has two components. A daemon sits in 1.632 + the background and receives notifications from the 1.633 + <literal>inotify</literal> subsystem. It also listens for 1.634 + connections from a regular Mercurial command. The extension 1.635 + modifies Mercurial's behavior so that instead of scanning the 1.636 + filesystem, it queries the daemon. Since the daemon has perfect 1.637 + information about the state of the repository, it can respond 1.638 + with a result instantaneously, avoiding the need to scan every 1.639 + directory and file in the repository.</para> 1.640 + 1.641 + <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 1.642 + taking to run <command role="hg-cmd">hg status</command> on a 1.643 + 150,000 file repository. With the <literal 1.644 + role="hg-ext">inotify</literal> extension enabled, the time 1.645 + dropped to 0.1 seconds, a factor of <emphasis>one 1.646 + hundred</emphasis> faster.</para> 1.647 + 1.648 + <para id="x_50c">Before we continue, please pay attention to some 1.649 + caveats.</para> 1.650 + <itemizedlist> 1.651 + <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 1.652 + extension is Linux-specific. Because it interfaces directly 1.653 + to the Linux kernel's <literal>inotify</literal> subsystem, 1.654 + it does not work on other operating systems.</para> 1.655 + </listitem> 1.656 + <listitem><para id="x_50e">It should work on any Linux distribution that 1.657 + was released after early 2005. Older distributions are 1.658 + likely to have a kernel that lacks 1.659 + <literal>inotify</literal>, or a version of 1.660 + <literal>glibc</literal> that does not have the necessary 1.661 + interfacing support.</para> 1.662 + </listitem> 1.663 + <listitem><para id="x_50f">Not all filesystems are suitable for use with 1.664 + the <literal role="hg-ext">inotify</literal> extension. 1.665 + Network filesystems such as NFS are a non-starter, for 1.666 + example, particularly if you're running Mercurial on several 1.667 + systems, all mounting the same network filesystem. The 1.668 + kernel's <literal>inotify</literal> system has no way of 1.669 + knowing about changes made on another system. Most local 1.670 + filesystems (e.g. ext3, XFS, ReiserFS) should work 1.671 + fine.</para> 1.672 + </listitem></itemizedlist> 1.673 + 1.674 + <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 1.675 + not yet shipped with Mercurial as of May 2007, so it's a little 1.676 + more involved to set up than other extensions. But the 1.677 + performance improvement is worth it!</para> 1.678 + 1.679 + <para id="x_511">The extension currently comes in two parts: a set of patches 1.680 + to the Mercurial source code, and a library of Python bindings 1.681 + to the <literal>inotify</literal> subsystem.</para> 1.682 + <note> 1.683 + <para id="x_512"> There are <emphasis>two</emphasis> Python 1.684 + <literal>inotify</literal> binding libraries. One of them is 1.685 + called <literal>pyinotify</literal>, and is packaged by some 1.686 + Linux distributions as <literal>python-inotify</literal>. 1.687 + This is <emphasis>not</emphasis> the one you'll need, as it is 1.688 + too buggy and inefficient to be practical.</para> 1.689 + </note> 1.690 + <para id="x_513">To get going, it's best to already have a functioning copy 1.691 + of Mercurial installed.</para> 1.692 + <note> 1.693 + <para id="x_514"> If you follow the instructions below, you'll be 1.694 + <emphasis>replacing</emphasis> and overwriting any existing 1.695 + installation of Mercurial that you might already have, using 1.696 + the latest <quote>bleeding edge</quote> Mercurial code. Don't 1.697 + say you weren't warned!</para> 1.698 + </note> 1.699 + <orderedlist> 1.700 + <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 1.701 + binding repository. Build and install it.</para> 1.702 + <programlisting>hg clone http://hg.kublai.com/python/inotify 1.703 +cd inotify 1.704 +python setup.py build --force 1.705 +sudo python setup.py install --skip-build</programlisting> 1.706 + </listitem> 1.707 + <listitem><para id="x_516">Clone the <filename 1.708 + class="directory">crew</filename> Mercurial repository. 1.709 + Clone the <literal role="hg-ext">inotify</literal> patch 1.710 + repository so that Mercurial Queues will be able to apply 1.711 + patches to your cope of the <filename 1.712 + class="directory">crew</filename> repository.</para> 1.713 + <programlisting>hg clone http://hg.intevation.org/mercurial/crew 1.714 +hg clone crew inotify 1.715 +hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 1.716 + </listitem> 1.717 + <listitem><para id="x_517">Make sure that you have the Mercurial Queues 1.718 + extension, <literal role="hg-ext">mq</literal>, enabled. If 1.719 + you've never used MQ, read <xref 1.720 + linkend="sec:mq:start"/> to get started 1.721 + quickly.</para> 1.722 + </listitem> 1.723 + <listitem><para id="x_518">Go into the <filename 1.724 + class="directory">inotify</filename> repo, and apply all 1.725 + of the <literal role="hg-ext">inotify</literal> patches 1.726 + using the <option role="hg-ext-mq-cmd-qpush-opt">hg 1.727 + -a</option> option to the <command 1.728 + role="hg-ext-mq">qpush</command> command.</para> 1.729 + <programlisting>cd inotify 1.730 +hg qpush -a</programlisting> 1.731 + </listitem> 1.732 + <listitem><para id="x_519"> If you get an error message from <command 1.733 + role="hg-ext-mq">qpush</command>, you should not continue. 1.734 + Instead, ask for help.</para> 1.735 + </listitem> 1.736 + <listitem><para id="x_51a">Build and install the patched version of 1.737 + Mercurial.</para> 1.738 + <programlisting>python setup.py build --force 1.739 +sudo python setup.py install --skip-build</programlisting> 1.740 + </listitem> 1.741 + </orderedlist> 1.742 + <para id="x_51b">Once you've build a suitably patched version of Mercurial, 1.743 + all you need to do to enable the <literal 1.744 + role="hg-ext">inotify</literal> extension is add an entry to 1.745 + your <filename role="special">~/.hgrc</filename>.</para> 1.746 + <programlisting>[extensions] inotify =</programlisting> 1.747 + <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 1.748 + is enabled, Mercurial will automatically and transparently start 1.749 + the status daemon the first time you run a command that needs 1.750 + status in a repository. It runs one status daemon per 1.751 + repository.</para> 1.752 + 1.753 + <para id="x_51d">The status daemon is started silently, and runs in the 1.754 + background. If you look at a list of running processes after 1.755 + you've enabled the <literal role="hg-ext">inotify</literal> 1.756 + extension and run a few commands in different repositories, 1.757 + you'll thus see a few <literal>hg</literal> processes sitting 1.758 + around, waiting for updates from the kernel and queries from 1.759 + Mercurial.</para> 1.760 + 1.761 + <para id="x_51e">The first time you run a Mercurial command in a repository 1.762 + when you have the <literal role="hg-ext">inotify</literal> 1.763 + extension enabled, it will run with about the same performance 1.764 + as a normal Mercurial command. This is because the status 1.765 + daemon needs to perform a normal status scan so that it has a 1.766 + baseline against which to apply later updates from the kernel. 1.767 + However, <emphasis>every</emphasis> subsequent command that does 1.768 + any kind of status check should be noticeably faster on 1.769 + repositories of even fairly modest size. Better yet, the bigger 1.770 + your repository is, the greater a performance advantage you'll 1.771 + see. The <literal role="hg-ext">inotify</literal> daemon makes 1.772 + status operations almost instantaneous on repositories of all 1.773 + sizes!</para> 1.774 + 1.775 + <para id="x_51f">If you like, you can manually start a status daemon using 1.776 + the <command role="hg-ext-inotify">inserve</command> command. 1.777 + This gives you slightly finer control over how the daemon ought 1.778 + to run. This command will of course only be available when the 1.779 + <literal role="hg-ext">inotify</literal> extension is 1.780 + enabled.</para> 1.781 + 1.782 + <para id="x_520">When you're using the <literal 1.783 + role="hg-ext">inotify</literal> extension, you should notice 1.784 + <emphasis>no difference at all</emphasis> in Mercurial's 1.785 + behavior, with the sole exception of status-related commands 1.786 + running a whole lot faster than they used to. You should 1.787 + specifically expect that commands will not print different 1.788 + output; neither should they give different results. If either of 1.789 + these situations occurs, please report a bug.</para> 1.790 + 1.791 + </sect1> 1.792 + <sect1 id="sec:hgext:extdiff"> 1.793 + <title>Flexible diff support with the <literal 1.794 + role="hg-ext">extdiff</literal> extension</title> 1.795 + 1.796 + <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 1.797 + diff</command> command outputs plaintext unified diffs.</para> 1.798 + 1.799 + &interaction.extdiff.diff; 1.800 + 1.801 + <para id="x_522">If you would like to use an external tool to display 1.802 + modifications, you'll want to use the <literal 1.803 + role="hg-ext">extdiff</literal> extension. This will let you 1.804 + use, for example, a graphical diff tool.</para> 1.805 + 1.806 + <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 1.807 + bundled with Mercurial, so it's easy to set up. In the <literal 1.808 + role="rc-extensions">extensions</literal> section of your 1.809 + <filename role="special">~/.hgrc</filename>, simply add a 1.810 + one-line entry to enable the extension.</para> 1.811 + <programlisting>[extensions] 1.812 +extdiff =</programlisting> 1.813 + <para id="x_524">This introduces a command named <command 1.814 + role="hg-ext-extdiff">extdiff</command>, which by default uses 1.815 + your system's <command>diff</command> command to generate a 1.816 + unified diff in the same form as the built-in <command 1.817 + role="hg-cmd">hg diff</command> command.</para> 1.818 + 1.819 + &interaction.extdiff.extdiff; 1.820 + 1.821 + <para id="x_525">The result won't be exactly the same as with the built-in 1.822 + <command role="hg-cmd">hg diff</command> variations, because the 1.823 + output of <command>diff</command> varies from one system to 1.824 + another, even when passed the same options.</para> 1.825 + 1.826 + <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 1.827 + lines of output above imply, the <command 1.828 + role="hg-ext-extdiff">extdiff</command> command works by 1.829 + creating two snapshots of your source tree. The first snapshot 1.830 + is of the source revision; the second, of the target revision or 1.831 + working directory. The <command 1.832 + role="hg-ext-extdiff">extdiff</command> command generates 1.833 + these snapshots in a temporary directory, passes the name of 1.834 + each directory to an external diff viewer, then deletes the 1.835 + temporary directory. For efficiency, it only snapshots the 1.836 + directories and files that have changed between the two 1.837 + revisions.</para> 1.838 + 1.839 + <para id="x_527">Snapshot directory names have the same base name as your 1.840 + repository. If your repository path is <filename 1.841 + class="directory">/quux/bar/foo</filename>, then <filename 1.842 + class="directory">foo</filename> will be the name of each 1.843 + snapshot directory. Each snapshot directory name has its 1.844 + changeset ID appended, if appropriate. If a snapshot is of 1.845 + revision <literal>a631aca1083f</literal>, the directory will be 1.846 + named <filename class="directory">foo.a631aca1083f</filename>. 1.847 + A snapshot of the working directory won't have a changeset ID 1.848 + appended, so it would just be <filename 1.849 + class="directory">foo</filename> in this example. To see what 1.850 + this looks like in practice, look again at the <command 1.851 + role="hg-ext-extdiff">extdiff</command> example above. Notice 1.852 + that the diff has the snapshot directory names embedded in its 1.853 + header.</para> 1.854 + 1.855 + <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 1.856 + accepts two important options. The <option 1.857 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 1.858 + lets you choose a program to view differences with, instead of 1.859 + <command>diff</command>. With the <option 1.860 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, 1.861 + you can change the options that <command 1.862 + role="hg-ext-extdiff">extdiff</command> passes to the program 1.863 + (by default, these options are 1.864 + <quote><literal>-Npru</literal></quote>, which only make sense 1.865 + if you're running <command>diff</command>). In other respects, 1.866 + the <command role="hg-ext-extdiff">extdiff</command> command 1.867 + acts similarly to the built-in <command role="hg-cmd">hg 1.868 + diff</command> command: you use the same option names, syntax, 1.869 + and arguments to specify the revisions you want, the files you 1.870 + want, and so on.</para> 1.871 + 1.872 + <para id="x_529">As an example, here's how to run the normal system 1.873 + <command>diff</command> command, getting it to generate context 1.874 + diffs (using the <option role="cmd-opt-diff">-c</option> option) 1.875 + instead of unified diffs, and five lines of context instead of 1.876 + the default three (passing <literal>5</literal> as the argument 1.877 + to the <option role="cmd-opt-diff">-C</option> option).</para> 1.878 + 1.879 + &interaction.extdiff.extdiff-ctx; 1.880 + 1.881 + <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 1.882 + launch the <command>kdiff3</command> viewer.</para> 1.883 + <programlisting>hg extdiff -p kdiff3 -o</programlisting> 1.884 + 1.885 + <para id="x_52b">If your diff viewing command can't deal with directories, 1.886 + you can easily work around this with a little scripting. For an 1.887 + example of such scripting in action with the <literal 1.888 + role="hg-ext">mq</literal> extension and the 1.889 + <command>interdiff</command> command, see <xref 1.890 + linkend="mq-collab:tips:interdiff"/>.</para> 1.891 + 1.892 + <sect2> 1.893 + <title>Defining command aliases</title> 1.894 + 1.895 + <para id="x_52c">It can be cumbersome to remember the options to both the 1.896 + <command role="hg-ext-extdiff">extdiff</command> command and 1.897 + the diff viewer you want to use, so the <literal 1.898 + role="hg-ext">extdiff</literal> extension lets you define 1.899 + <emphasis>new</emphasis> commands that will invoke your diff 1.900 + viewer with exactly the right options.</para> 1.901 + 1.902 + <para id="x_52d">All you need to do is edit your <filename 1.903 + role="special">~/.hgrc</filename>, and add a section named 1.904 + <literal role="rc-extdiff">extdiff</literal>. Inside this 1.905 + section, you can define multiple commands. Here's how to add 1.906 + a <literal>kdiff3</literal> command. Once you've defined 1.907 + this, you can type <quote><literal>hg kdiff3</literal></quote> 1.908 + and the <literal role="hg-ext">extdiff</literal> extension 1.909 + will run <command>kdiff3</command> for you.</para> 1.910 + <programlisting>[extdiff] 1.911 +cmd.kdiff3 =</programlisting> 1.912 + <para id="x_52e">If you leave the right hand side of the definition empty, 1.913 + as above, the <literal role="hg-ext">extdiff</literal> 1.914 + extension uses the name of the command you defined as the name 1.915 + of the external program to run. But these names don't have to 1.916 + be the same. Here, we define a command named 1.917 + <quote><literal>hg wibble</literal></quote>, which runs 1.918 + <command>kdiff3</command>.</para> 1.919 + <programlisting>[extdiff] 1.920 + cmd.wibble = kdiff3</programlisting> 1.921 + 1.922 + <para id="x_52f">You can also specify the default options that you want to 1.923 + invoke your diff viewing program with. The prefix to use is 1.924 + <quote><literal>opts.</literal></quote>, followed by the name 1.925 + of the command to which the options apply. This example 1.926 + defines a <quote><literal>hg vimdiff</literal></quote> command 1.927 + that runs the <command>vim</command> editor's 1.928 + <literal>DirDiff</literal> extension.</para> 1.929 + <programlisting>[extdiff] 1.930 + cmd.vimdiff = vim 1.931 +opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> 1.932 + 1.933 + </sect2> 1.934 + </sect1> 1.935 + <sect1 id="sec:hgext:transplant"> 1.936 + <title>Cherrypicking changes with the <literal 1.937 + role="hg-ext">transplant</literal> extension</title> 1.938 + 1.939 + <para id="x_530">Need to have a long chat with Brendan about this.</para> 1.940 + 1.941 + </sect1> 1.942 + <sect1 id="sec:hgext:patchbomb"> 1.943 + <title>Send changes via email with the <literal 1.944 + role="hg-ext">patchbomb</literal> extension</title> 1.945 + 1.946 + <para id="x_531">Many projects have a culture of <quote>change 1.947 + review</quote>, in which people send their modifications to a 1.948 + mailing list for others to read and comment on before they 1.949 + commit the final version to a shared repository. Some projects 1.950 + have people who act as gatekeepers; they apply changes from 1.951 + other people to a repository to which those others don't have 1.952 + access.</para> 1.953 + 1.954 + <para id="x_532">Mercurial makes it easy to send changes over email for 1.955 + review or application, via its <literal 1.956 + role="hg-ext">patchbomb</literal> extension. The extension is 1.957 + so named because changes are formatted as patches, and it's usual 1.958 + to send one changeset per email message. Sending a long series 1.959 + of changes by email is thus much like <quote>bombing</quote> the 1.960 + recipient's inbox, hence <quote>patchbomb</quote>.</para> 1.961 + 1.962 + <para id="x_533">As usual, the basic configuration of the <literal 1.963 + role="hg-ext">patchbomb</literal> extension takes just one or 1.964 + two lines in your <filename role="special"> 1.965 + /.hgrc</filename>.</para> 1.966 + <programlisting>[extensions] 1.967 +patchbomb =</programlisting> 1.968 + <para id="x_534">Once you've enabled the extension, you will have a new 1.969 + command available, named <command 1.970 + role="hg-ext-patchbomb">email</command>.</para> 1.971 + 1.972 + <para id="x_535">The safest and best way to invoke the <command 1.973 + role="hg-ext-patchbomb">email</command> command is to 1.974 + <emphasis>always</emphasis> run it first with the <option 1.975 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 1.976 + This will show you what the command <emphasis>would</emphasis> 1.977 + send, without actually sending anything. Once you've had a 1.978 + quick glance over the changes and verified that you are sending 1.979 + the right ones, you can rerun the same command, with the <option 1.980 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 1.981 + removed.</para> 1.982 + 1.983 + <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 1.984 + accepts the same kind of revision syntax as every other 1.985 + Mercurial command. For example, this command will send every 1.986 + revision between 7 and <literal>tip</literal>, inclusive.</para> 1.987 + <programlisting>hg email -n 7:tip</programlisting> 1.988 + <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 1.989 + compare with. If you provide a repository but no revisions, the 1.990 + <command role="hg-ext-patchbomb">email</command> command will 1.991 + send all revisions in the local repository that are not present 1.992 + in the remote repository. If you additionally specify revisions 1.993 + or a branch name (the latter using the <option 1.994 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 1.995 + this will constrain the revisions sent.</para> 1.996 + 1.997 + <para id="x_538">It's perfectly safe to run the <command 1.998 + role="hg-ext-patchbomb">email</command> command without the 1.999 + names of the people you want to send to: if you do this, it will 1.1000 + just prompt you for those values interactively. (If you're 1.1001 + using a Linux or Unix-like system, you should have enhanced 1.1002 + <literal>readline</literal>-style editing capabilities when 1.1003 + entering those headers, too, which is useful.)</para> 1.1004 + 1.1005 + <para id="x_539">When you are sending just one revision, the <command 1.1006 + role="hg-ext-patchbomb">email</command> command will by 1.1007 + default use the first line of the changeset description as the 1.1008 + subject of the single email message it sends.</para> 1.1009 + 1.1010 + <para id="x_53a">If you send multiple revisions, the <command 1.1011 + role="hg-ext-patchbomb">email</command> command will usually 1.1012 + send one message per changeset. It will preface the series with 1.1013 + an introductory message, in which you should describe the 1.1014 + purpose of the series of changes you're sending.</para> 1.1015 + 1.1016 + <sect2> 1.1017 + <title>Changing the behavior of patchbombs</title> 1.1018 + 1.1019 + <para id="x_53b">Not every project has exactly the same conventions for 1.1020 + sending changes in email; the <literal 1.1021 + role="hg-ext">patchbomb</literal> extension tries to 1.1022 + accommodate a number of variations through command line 1.1023 + options.</para> 1.1024 + <itemizedlist> 1.1025 + <listitem><para id="x_53c">You can write a subject for the introductory 1.1026 + message on the command line using the <option 1.1027 + role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 1.1028 + option. This takes one argument, the text of the subject 1.1029 + to use.</para> 1.1030 + </listitem> 1.1031 + <listitem><para id="x_53d">To change the email address from which the 1.1032 + messages originate, use the <option 1.1033 + role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 1.1034 + option. This takes one argument, the email address to 1.1035 + use.</para> 1.1036 + </listitem> 1.1037 + <listitem><para id="x_53e">The default behavior is to send unified diffs 1.1038 + (see <xref linkend="sec:mq:patch"/> for a 1.1039 + description of the 1.1040 + format), one per message. You can send a binary bundle 1.1041 + instead with the <option 1.1042 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 1.1043 + option.</para> 1.1044 + </listitem> 1.1045 + <listitem><para id="x_53f">Unified diffs are normally prefaced with a 1.1046 + metadata header. You can omit this, and send unadorned 1.1047 + diffs, with the <option 1.1048 + role="hg-ext-patchbomb-cmd-email-opt">hg 1.1049 + --plain</option> option.</para> 1.1050 + </listitem> 1.1051 + <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 1.1052 + in the same body part as the description of a patch. This 1.1053 + makes it easiest for the largest number of readers to 1.1054 + quote and respond to parts of a diff, as some mail clients 1.1055 + will only quote the first MIME body part in a message. If 1.1056 + you'd prefer to send the description and the diff in 1.1057 + separate body parts, use the <option 1.1058 + role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 1.1059 + option.</para> 1.1060 + </listitem> 1.1061 + <listitem><para id="x_541">Instead of sending mail messages, you can 1.1062 + write them to an <literal>mbox</literal>-format mail 1.1063 + folder using the <option 1.1064 + role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 1.1065 + option. That option takes one argument, the name of the 1.1066 + file to write to.</para> 1.1067 + </listitem> 1.1068 + <listitem><para id="x_542">If you would like to add a 1.1069 + <command>diffstat</command>-format summary to each patch, 1.1070 + and one to the introductory message, use the <option 1.1071 + role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> 1.1072 + option. The <command>diffstat</command> command displays 1.1073 + a table containing the name of each file patched, the 1.1074 + number of lines affected, and a histogram showing how much 1.1075 + each file is modified. This gives readers a qualitative 1.1076 + glance at how complex a patch is.</para> 1.1077 + </listitem></itemizedlist> 1.1078 + 1.1079 + </sect2> 1.1080 + </sect1> 1.1081 </chapter> 1.1082 1.1083 <!-- 1.1084 local variables: 1.1085 sgml-parent-document: ("00book.xml" "book" "chapter") 1.1086 end: 1.1087 ---> 1.1088 \ No newline at end of file 1.1089 +-->