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 +-->