1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/ch14-hgext.xml	Sun Aug 16 04:58:01 2009 +0200
     1.3 @@ -0,0 +1,539 @@
     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>
   1.537 +
   1.538 +<!--
   1.539 +local variables: 
   1.540 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.541 +end:
   1.542 +-->
   1.543 \ No newline at end of file