hgbook

annotate en/ch14-hgext.xml @ 1114:527b86d55d4a

find changesets by author, revision, files, or words in the commit message
inotify: update installation information

inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author Nicolas Dumazet <nicdumz.commits@gmail.com>
date Sun Dec 13 16:35:56 2009 +0900 (2009-12-13)
parents acf9dc5f088d
children
rev   line source
bos@559 1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559 2
bos@559 3 <chapter id="chap:hgext">
bos@572 4 <?dbhtml filename="adding-functionality-with-extensions.html"?>
bos@559 5 <title>Adding functionality with extensions</title>
bos@559 6
bos@584 7 <para id="x_4fe">While the core of Mercurial is quite complete from a
bos@559 8 functionality standpoint, it's deliberately shorn of fancy
bos@559 9 features. This approach of preserving simplicity keeps the
bos@559 10 software easy to deal with for both maintainers and users.</para>
bos@559 11
bos@584 12 <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
bos@559 13 command set: you can add features to it as
bos@559 14 <emphasis>extensions</emphasis> (sometimes known as
bos@559 15 <emphasis>plugins</emphasis>). We've already discussed a few of
bos@559 16 these extensions in earlier chapters.</para>
bos@559 17 <itemizedlist>
bos@592 18 <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
bos@559 19 covers the <literal role="hg-ext">fetch</literal> extension;
bos@559 20 this combines pulling new changes and merging them with local
bos@559 21 changes into a single command, <command
bos@559 22 role="hg-ext-fetch">fetch</command>.</para>
bos@559 23 </listitem>
bos@592 24 <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
bos@559 25 several extensions that are useful for hook-related
bos@559 26 functionality: <literal role="hg-ext">acl</literal> adds
bos@559 27 access control lists; <literal
bos@559 28 role="hg-ext">bugzilla</literal> adds integration with the
bos@559 29 Bugzilla bug tracking system; and <literal
bos@559 30 role="hg-ext">notify</literal> sends notification emails on
bos@559 31 new changes.</para>
bos@559 32 </listitem>
bos@584 33 <listitem><para id="x_502">The Mercurial Queues patch management extension is
bos@559 34 so invaluable that it merits two chapters and an appendix all
bos@592 35 to itself. <xref linkend="chap:mq"/> covers the
bos@592 36 basics; <xref
bos@559 37 linkend="chap:mq-collab"/> discusses advanced topics;
bos@592 38 and <xref linkend="chap:mqref"/> goes into detail on
bos@559 39 each
bos@559 40 command.</para>
bos@559 41 </listitem></itemizedlist>
bos@559 42
bos@584 43 <para id="x_503">In this chapter, we'll cover some of the other extensions that
bos@559 44 are available for Mercurial, and briefly touch on some of the
bos@559 45 machinery you'll need to know about if you want to write an
bos@559 46 extension of your own.</para>
bos@559 47 <itemizedlist>
bos@592 48 <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
bos@559 49 we'll discuss the possibility of <emphasis>huge</emphasis>
bos@559 50 performance improvements using the <literal
bos@559 51 role="hg-ext">inotify</literal> extension.</para>
bos@559 52 </listitem></itemizedlist>
bos@559 53
bos@559 54 <sect1 id="sec:hgext:inotify">
bos@559 55 <title>Improve performance with the <literal
bos@559 56 role="hg-ext">inotify</literal> extension</title>
bos@559 57
bos@584 58 <para id="x_505">Are you interested in having some of the most common
bos@559 59 Mercurial operations run as much as a hundred times faster?
bos@559 60 Read on!</para>
bos@559 61
bos@584 62 <para id="x_506">Mercurial has great performance under normal circumstances.
bos@559 63 For example, when you run the <command role="hg-cmd">hg
bos@559 64 status</command> command, Mercurial has to scan almost every
bos@559 65 directory and file in your repository so that it can display
bos@559 66 file status. Many other Mercurial commands need to do the same
bos@559 67 work behind the scenes; for example, the <command
bos@559 68 role="hg-cmd">hg diff</command> command uses the status
bos@559 69 machinery to avoid doing an expensive comparison operation on
bos@559 70 files that obviously haven't changed.</para>
bos@559 71
bos@584 72 <para id="x_507">Because obtaining file status is crucial to good
bos@559 73 performance, the authors of Mercurial have optimised this code
bos@559 74 to within an inch of its life. However, there's no avoiding the
bos@559 75 fact that when you run <command role="hg-cmd">hg
bos@559 76 status</command>, Mercurial is going to have to perform at
bos@559 77 least one expensive system call for each managed file to
bos@559 78 determine whether it's changed since the last time Mercurial
bos@559 79 checked. For a sufficiently large repository, this can take a
bos@559 80 long time.</para>
bos@559 81
bos@584 82 <para id="x_508">To put a number on the magnitude of this effect, I created a
bos@559 83 repository containing 150,000 managed files. I timed <command
bos@559 84 role="hg-cmd">hg status</command> as taking ten seconds to
bos@559 85 run, even when <emphasis>none</emphasis> of those files had been
bos@559 86 modified.</para>
bos@559 87
bos@584 88 <para id="x_509">Many modern operating systems contain a file notification
bos@559 89 facility. If a program signs up to an appropriate service, the
bos@559 90 operating system will notify it every time a file of interest is
bos@559 91 created, modified, or deleted. On Linux systems, the kernel
bos@559 92 component that does this is called
bos@559 93 <literal>inotify</literal>.</para>
bos@559 94
bos@584 95 <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal>
bos@559 96 extension talks to the kernel's <literal>inotify</literal>
bos@559 97 component to optimise <command role="hg-cmd">hg status</command>
bos@559 98 commands. The extension has two components. A daemon sits in
bos@559 99 the background and receives notifications from the
bos@559 100 <literal>inotify</literal> subsystem. It also listens for
bos@559 101 connections from a regular Mercurial command. The extension
bos@672 102 modifies Mercurial's behavior so that instead of scanning the
bos@559 103 filesystem, it queries the daemon. Since the daemon has perfect
bos@559 104 information about the state of the repository, it can respond
bos@559 105 with a result instantaneously, avoiding the need to scan every
bos@559 106 directory and file in the repository.</para>
bos@559 107
bos@584 108 <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
bos@559 109 taking to run <command role="hg-cmd">hg status</command> on a
bos@559 110 150,000 file repository. With the <literal
bos@559 111 role="hg-ext">inotify</literal> extension enabled, the time
bos@559 112 dropped to 0.1 seconds, a factor of <emphasis>one
bos@559 113 hundred</emphasis> faster.</para>
bos@559 114
bos@584 115 <para id="x_50c">Before we continue, please pay attention to some
bos@559 116 caveats.</para>
bos@559 117 <itemizedlist>
bos@584 118 <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal>
bos@559 119 extension is Linux-specific. Because it interfaces directly
bos@559 120 to the Linux kernel's <literal>inotify</literal> subsystem,
bos@559 121 it does not work on other operating systems.</para>
bos@559 122 </listitem>
bos@584 123 <listitem><para id="x_50e">It should work on any Linux distribution that
bos@559 124 was released after early 2005. Older distributions are
bos@559 125 likely to have a kernel that lacks
bos@559 126 <literal>inotify</literal>, or a version of
bos@559 127 <literal>glibc</literal> that does not have the necessary
bos@559 128 interfacing support.</para>
bos@559 129 </listitem>
bos@584 130 <listitem><para id="x_50f">Not all filesystems are suitable for use with
bos@559 131 the <literal role="hg-ext">inotify</literal> extension.
bos@559 132 Network filesystems such as NFS are a non-starter, for
bos@559 133 example, particularly if you're running Mercurial on several
bos@559 134 systems, all mounting the same network filesystem. The
bos@559 135 kernel's <literal>inotify</literal> system has no way of
bos@559 136 knowing about changes made on another system. Most local
bos@559 137 filesystems (e.g. ext3, XFS, ReiserFS) should work
bos@559 138 fine.</para>
bos@559 139 </listitem></itemizedlist>
bos@559 140
bos@584 141 <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is
nicdumz@1114 142 shipped with Mercurial since 1.0.
nicdumz@1114 143 All you need to do to enable the <literal
bos@559 144 role="hg-ext">inotify</literal> extension is add an entry to
bos@580 145 your <filename role="special">~/.hgrc</filename>.</para>
bos@559 146 <programlisting>[extensions] inotify =</programlisting>
bos@584 147 <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension
bos@559 148 is enabled, Mercurial will automatically and transparently start
bos@559 149 the status daemon the first time you run a command that needs
bos@559 150 status in a repository. It runs one status daemon per
bos@559 151 repository.</para>
bos@559 152
bos@584 153 <para id="x_51d">The status daemon is started silently, and runs in the
bos@559 154 background. If you look at a list of running processes after
bos@559 155 you've enabled the <literal role="hg-ext">inotify</literal>
bos@559 156 extension and run a few commands in different repositories,
bos@559 157 you'll thus see a few <literal>hg</literal> processes sitting
bos@559 158 around, waiting for updates from the kernel and queries from
bos@559 159 Mercurial.</para>
bos@559 160
bos@584 161 <para id="x_51e">The first time you run a Mercurial command in a repository
bos@559 162 when you have the <literal role="hg-ext">inotify</literal>
bos@559 163 extension enabled, it will run with about the same performance
bos@559 164 as a normal Mercurial command. This is because the status
bos@559 165 daemon needs to perform a normal status scan so that it has a
bos@559 166 baseline against which to apply later updates from the kernel.
bos@559 167 However, <emphasis>every</emphasis> subsequent command that does
bos@559 168 any kind of status check should be noticeably faster on
bos@559 169 repositories of even fairly modest size. Better yet, the bigger
bos@559 170 your repository is, the greater a performance advantage you'll
bos@559 171 see. The <literal role="hg-ext">inotify</literal> daemon makes
bos@559 172 status operations almost instantaneous on repositories of all
bos@559 173 sizes!</para>
bos@559 174
bos@584 175 <para id="x_51f">If you like, you can manually start a status daemon using
bos@559 176 the <command role="hg-ext-inotify">inserve</command> command.
bos@559 177 This gives you slightly finer control over how the daemon ought
bos@559 178 to run. This command will of course only be available when the
bos@559 179 <literal role="hg-ext">inotify</literal> extension is
bos@559 180 enabled.</para>
bos@559 181
bos@584 182 <para id="x_520">When you're using the <literal
bos@559 183 role="hg-ext">inotify</literal> extension, you should notice
bos@559 184 <emphasis>no difference at all</emphasis> in Mercurial's
bos@672 185 behavior, with the sole exception of status-related commands
bos@559 186 running a whole lot faster than they used to. You should
bos@559 187 specifically expect that commands will not print different
bos@559 188 output; neither should they give different results. If either of
bos@559 189 these situations occurs, please report a bug.</para>
bos@559 190
bos@559 191 </sect1>
bos@559 192 <sect1 id="sec:hgext:extdiff">
bos@559 193 <title>Flexible diff support with the <literal
bos@559 194 role="hg-ext">extdiff</literal> extension</title>
bos@559 195
bos@584 196 <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg
bos@567 197 diff</command> command outputs plaintext unified diffs.</para>
bos@567 198
bos@567 199 &interaction.extdiff.diff;
bos@567 200
bos@584 201 <para id="x_522">If you would like to use an external tool to display
bos@567 202 modifications, you'll want to use the <literal
bos@567 203 role="hg-ext">extdiff</literal> extension. This will let you
bos@567 204 use, for example, a graphical diff tool.</para>
bos@559 205
bos@584 206 <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is
bos@559 207 bundled with Mercurial, so it's easy to set up. In the <literal
bos@559 208 role="rc-extensions">extensions</literal> section of your
bos@580 209 <filename role="special">~/.hgrc</filename>, simply add a
bos@559 210 one-line entry to enable the extension.</para>
bos@580 211 <programlisting>[extensions]
bos@580 212 extdiff =</programlisting>
bos@584 213 <para id="x_524">This introduces a command named <command
bos@559 214 role="hg-ext-extdiff">extdiff</command>, which by default uses
bos@559 215 your system's <command>diff</command> command to generate a
bos@559 216 unified diff in the same form as the built-in <command
bos@567 217 role="hg-cmd">hg diff</command> command.</para>
bos@567 218
bos@567 219 &interaction.extdiff.extdiff;
bos@567 220
bos@584 221 <para id="x_525">The result won't be exactly the same as with the built-in
bos@567 222 <command role="hg-cmd">hg diff</command> variations, because the
bos@567 223 output of <command>diff</command> varies from one system to
bos@567 224 another, even when passed the same options.</para>
bos@559 225
bos@584 226 <para id="x_526">As the <quote><literal>making snapshot</literal></quote>
bos@559 227 lines of output above imply, the <command
bos@559 228 role="hg-ext-extdiff">extdiff</command> command works by
bos@559 229 creating two snapshots of your source tree. The first snapshot
bos@559 230 is of the source revision; the second, of the target revision or
bos@559 231 working directory. The <command
bos@559 232 role="hg-ext-extdiff">extdiff</command> command generates
bos@559 233 these snapshots in a temporary directory, passes the name of
bos@559 234 each directory to an external diff viewer, then deletes the
bos@559 235 temporary directory. For efficiency, it only snapshots the
bos@559 236 directories and files that have changed between the two
bos@559 237 revisions.</para>
bos@559 238
bos@584 239 <para id="x_527">Snapshot directory names have the same base name as your
bos@559 240 repository. If your repository path is <filename
bos@559 241 class="directory">/quux/bar/foo</filename>, then <filename
bos@559 242 class="directory">foo</filename> will be the name of each
bos@559 243 snapshot directory. Each snapshot directory name has its
bos@559 244 changeset ID appended, if appropriate. If a snapshot is of
bos@559 245 revision <literal>a631aca1083f</literal>, the directory will be
bos@559 246 named <filename class="directory">foo.a631aca1083f</filename>.
bos@559 247 A snapshot of the working directory won't have a changeset ID
bos@559 248 appended, so it would just be <filename
bos@559 249 class="directory">foo</filename> in this example. To see what
bos@559 250 this looks like in practice, look again at the <command
bos@559 251 role="hg-ext-extdiff">extdiff</command> example above. Notice
bos@559 252 that the diff has the snapshot directory names embedded in its
bos@559 253 header.</para>
bos@559 254
bos@584 255 <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command
bos@559 256 accepts two important options. The <option
bos@559 257 role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
bos@559 258 lets you choose a program to view differences with, instead of
bos@559 259 <command>diff</command>. With the <option
bos@559 260 role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
bos@559 261 you can change the options that <command
bos@559 262 role="hg-ext-extdiff">extdiff</command> passes to the program
bos@559 263 (by default, these options are
bos@559 264 <quote><literal>-Npru</literal></quote>, which only make sense
bos@559 265 if you're running <command>diff</command>). In other respects,
bos@559 266 the <command role="hg-ext-extdiff">extdiff</command> command
bos@559 267 acts similarly to the built-in <command role="hg-cmd">hg
bos@559 268 diff</command> command: you use the same option names, syntax,
bos@559 269 and arguments to specify the revisions you want, the files you
bos@559 270 want, and so on.</para>
bos@559 271
bos@584 272 <para id="x_529">As an example, here's how to run the normal system
bos@559 273 <command>diff</command> command, getting it to generate context
bos@559 274 diffs (using the <option role="cmd-opt-diff">-c</option> option)
bos@559 275 instead of unified diffs, and five lines of context instead of
bos@559 276 the default three (passing <literal>5</literal> as the argument
bos@567 277 to the <option role="cmd-opt-diff">-C</option> option).</para>
bos@567 278
bos@567 279 &interaction.extdiff.extdiff-ctx;
bos@559 280
bos@584 281 <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to
bos@559 282 launch the <command>kdiff3</command> viewer.</para>
bos@559 283 <programlisting>hg extdiff -p kdiff3 -o</programlisting>
bos@559 284
bos@584 285 <para id="x_52b">If your diff viewing command can't deal with directories,
bos@559 286 you can easily work around this with a little scripting. For an
bos@559 287 example of such scripting in action with the <literal
bos@559 288 role="hg-ext">mq</literal> extension and the
bos@592 289 <command>interdiff</command> command, see <xref
bos@559 290 linkend="mq-collab:tips:interdiff"/>.</para>
bos@559 291
bos@559 292 <sect2>
bos@559 293 <title>Defining command aliases</title>
bos@559 294
bos@584 295 <para id="x_52c">It can be cumbersome to remember the options to both the
bos@559 296 <command role="hg-ext-extdiff">extdiff</command> command and
bos@559 297 the diff viewer you want to use, so the <literal
bos@559 298 role="hg-ext">extdiff</literal> extension lets you define
bos@559 299 <emphasis>new</emphasis> commands that will invoke your diff
bos@559 300 viewer with exactly the right options.</para>
bos@559 301
bos@584 302 <para id="x_52d">All you need to do is edit your <filename
bos@580 303 role="special">~/.hgrc</filename>, and add a section named
bos@580 304 <literal role="rc-extdiff">extdiff</literal>. Inside this
bos@580 305 section, you can define multiple commands. Here's how to add
bos@580 306 a <literal>kdiff3</literal> command. Once you've defined
bos@580 307 this, you can type <quote><literal>hg kdiff3</literal></quote>
bos@580 308 and the <literal role="hg-ext">extdiff</literal> extension
bos@580 309 will run <command>kdiff3</command> for you.</para>
bos@580 310 <programlisting>[extdiff]
bos@580 311 cmd.kdiff3 =</programlisting>
bos@584 312 <para id="x_52e">If you leave the right hand side of the definition empty,
bos@559 313 as above, the <literal role="hg-ext">extdiff</literal>
bos@559 314 extension uses the name of the command you defined as the name
bos@559 315 of the external program to run. But these names don't have to
bos@559 316 be the same. Here, we define a command named
bos@559 317 <quote><literal>hg wibble</literal></quote>, which runs
bos@559 318 <command>kdiff3</command>.</para>
bos@580 319 <programlisting>[extdiff]
bos@580 320 cmd.wibble = kdiff3</programlisting>
bos@559 321
bos@584 322 <para id="x_52f">You can also specify the default options that you want to
bos@559 323 invoke your diff viewing program with. The prefix to use is
bos@559 324 <quote><literal>opts.</literal></quote>, followed by the name
bos@559 325 of the command to which the options apply. This example
bos@559 326 defines a <quote><literal>hg vimdiff</literal></quote> command
bos@559 327 that runs the <command>vim</command> editor's
bos@559 328 <literal>DirDiff</literal> extension.</para>
bos@580 329 <programlisting>[extdiff]
bos@580 330 cmd.vimdiff = vim
bos@580 331 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
bos@559 332
bos@559 333 </sect2>
bos@559 334 </sect1>
bos@559 335 <sect1 id="sec:hgext:transplant">
bos@559 336 <title>Cherrypicking changes with the <literal
bos@559 337 role="hg-ext">transplant</literal> extension</title>
bos@559 338
bos@584 339 <para id="x_530">Need to have a long chat with Brendan about this.</para>
bos@559 340
bos@559 341 </sect1>
bos@559 342 <sect1 id="sec:hgext:patchbomb">
bos@559 343 <title>Send changes via email with the <literal
bos@559 344 role="hg-ext">patchbomb</literal> extension</title>
bos@559 345
bos@584 346 <para id="x_531">Many projects have a culture of <quote>change
bos@559 347 review</quote>, in which people send their modifications to a
bos@559 348 mailing list for others to read and comment on before they
bos@559 349 commit the final version to a shared repository. Some projects
bos@559 350 have people who act as gatekeepers; they apply changes from
bos@559 351 other people to a repository to which those others don't have
bos@559 352 access.</para>
bos@559 353
bos@584 354 <para id="x_532">Mercurial makes it easy to send changes over email for
bos@559 355 review or application, via its <literal
bos@559 356 role="hg-ext">patchbomb</literal> extension. The extension is
ori@561 357 so named because changes are formatted as patches, and it's usual
bos@559 358 to send one changeset per email message. Sending a long series
bos@559 359 of changes by email is thus much like <quote>bombing</quote> the
bos@559 360 recipient's inbox, hence <quote>patchbomb</quote>.</para>
bos@559 361
bos@584 362 <para id="x_533">As usual, the basic configuration of the <literal
bos@559 363 role="hg-ext">patchbomb</literal> extension takes just one or
bos@559 364 two lines in your <filename role="special">
bos@559 365 /.hgrc</filename>.</para>
bos@580 366 <programlisting>[extensions]
bos@580 367 patchbomb =</programlisting>
bos@584 368 <para id="x_534">Once you've enabled the extension, you will have a new
bos@559 369 command available, named <command
bos@559 370 role="hg-ext-patchbomb">email</command>.</para>
bos@559 371
bos@584 372 <para id="x_535">The safest and best way to invoke the <command
bos@559 373 role="hg-ext-patchbomb">email</command> command is to
bos@559 374 <emphasis>always</emphasis> run it first with the <option
bos@559 375 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
bos@559 376 This will show you what the command <emphasis>would</emphasis>
bos@559 377 send, without actually sending anything. Once you've had a
bos@559 378 quick glance over the changes and verified that you are sending
bos@559 379 the right ones, you can rerun the same command, with the <option
bos@559 380 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
bos@559 381 removed.</para>
bos@559 382
bos@584 383 <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command
bos@559 384 accepts the same kind of revision syntax as every other
bos@559 385 Mercurial command. For example, this command will send every
bos@559 386 revision between 7 and <literal>tip</literal>, inclusive.</para>
bos@559 387 <programlisting>hg email -n 7:tip</programlisting>
bos@584 388 <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
bos@559 389 compare with. If you provide a repository but no revisions, the
bos@559 390 <command role="hg-ext-patchbomb">email</command> command will
bos@559 391 send all revisions in the local repository that are not present
bos@559 392 in the remote repository. If you additionally specify revisions
bos@559 393 or a branch name (the latter using the <option
bos@559 394 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
bos@559 395 this will constrain the revisions sent.</para>
bos@559 396
bos@584 397 <para id="x_538">It's perfectly safe to run the <command
bos@559 398 role="hg-ext-patchbomb">email</command> command without the
bos@559 399 names of the people you want to send to: if you do this, it will
bos@559 400 just prompt you for those values interactively. (If you're
bos@559 401 using a Linux or Unix-like system, you should have enhanced
bos@559 402 <literal>readline</literal>-style editing capabilities when
bos@559 403 entering those headers, too, which is useful.)</para>
bos@559 404
bos@584 405 <para id="x_539">When you are sending just one revision, the <command
bos@559 406 role="hg-ext-patchbomb">email</command> command will by
bos@559 407 default use the first line of the changeset description as the
bos@559 408 subject of the single email message it sends.</para>
bos@559 409
bos@584 410 <para id="x_53a">If you send multiple revisions, the <command
bos@559 411 role="hg-ext-patchbomb">email</command> command will usually
bos@559 412 send one message per changeset. It will preface the series with
bos@559 413 an introductory message, in which you should describe the
bos@559 414 purpose of the series of changes you're sending.</para>
bos@559 415
bos@559 416 <sect2>
bos@672 417 <title>Changing the behavior of patchbombs</title>
bos@559 418
bos@584 419 <para id="x_53b">Not every project has exactly the same conventions for
bos@559 420 sending changes in email; the <literal
bos@559 421 role="hg-ext">patchbomb</literal> extension tries to
bos@559 422 accommodate a number of variations through command line
bos@559 423 options.</para>
bos@559 424 <itemizedlist>
bos@584 425 <listitem><para id="x_53c">You can write a subject for the introductory
bos@559 426 message on the command line using the <option
bos@559 427 role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
bos@559 428 option. This takes one argument, the text of the subject
bos@559 429 to use.</para>
bos@559 430 </listitem>
bos@584 431 <listitem><para id="x_53d">To change the email address from which the
bos@559 432 messages originate, use the <option
bos@559 433 role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
bos@559 434 option. This takes one argument, the email address to
bos@559 435 use.</para>
bos@559 436 </listitem>
bos@672 437 <listitem><para id="x_53e">The default behavior is to send unified diffs
bos@592 438 (see <xref linkend="sec:mq:patch"/> for a
bos@559 439 description of the
bos@559 440 format), one per message. You can send a binary bundle
bos@559 441 instead with the <option
bos@559 442 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
bos@559 443 option.</para>
bos@559 444 </listitem>
bos@584 445 <listitem><para id="x_53f">Unified diffs are normally prefaced with a
bos@559 446 metadata header. You can omit this, and send unadorned
bos@559 447 diffs, with the <option
bos@559 448 role="hg-ext-patchbomb-cmd-email-opt">hg
bos@559 449 --plain</option> option.</para>
bos@559 450 </listitem>
bos@584 451 <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
bos@559 452 in the same body part as the description of a patch. This
bos@559 453 makes it easiest for the largest number of readers to
bos@559 454 quote and respond to parts of a diff, as some mail clients
bos@559 455 will only quote the first MIME body part in a message. If
bos@559 456 you'd prefer to send the description and the diff in
bos@559 457 separate body parts, use the <option
bos@559 458 role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
bos@559 459 option.</para>
bos@559 460 </listitem>
bos@584 461 <listitem><para id="x_541">Instead of sending mail messages, you can
bos@559 462 write them to an <literal>mbox</literal>-format mail
bos@559 463 folder using the <option
bos@559 464 role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
bos@559 465 option. That option takes one argument, the name of the
bos@559 466 file to write to.</para>
bos@559 467 </listitem>
bos@584 468 <listitem><para id="x_542">If you would like to add a
bos@559 469 <command>diffstat</command>-format summary to each patch,
bos@559 470 and one to the introductory message, use the <option
bos@559 471 role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
bos@559 472 option. The <command>diffstat</command> command displays
bos@559 473 a table containing the name of each file patched, the
bos@559 474 number of lines affected, and a histogram showing how much
bos@559 475 each file is modified. This gives readers a qualitative
bos@559 476 glance at how complex a patch is.</para>
bos@559 477 </listitem></itemizedlist>
bos@559 478
bos@559 479 </sect2>
bos@559 480 </sect1>
bos@559 481 </chapter>
bos@559 482
bos@559 483 <!--
bos@559 484 local variables:
bos@559 485 sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559 486 end:
bos@559 487 -->