web/html/abc.html~
changeset 1 672eaaab9204
parent 0 8083d21c0020
child 2 52d12eb31c30
equal deleted inserted replaced
0:8083d21c0020 1:672eaaab9204
     1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
       
     2 <title>Chapter 9. Finding and fixing mistakes</title>
       
     3 <link rel="stylesheet" href="/support/styles.css" type="text/css">
       
     4 <meta name="generator" content="DocBook XSL Stylesheets V1.74.3"><link rel="home" href="index.html" title="Mercurial: The Definitive Guide">
       
     5 <link rel="up" href="index.html" title="Mercurial: The Definitive Guide">
       
     6 <link rel="prev" href="managing-releases-and-branchy-development.html" title="Chapter 8. Managing releases and branchy development">
       
     7 <link rel="next" href="handling-repository-events-with-hooks.html" title="Chapter 10. Handling repository events with hooks"><link rel="alternate" type="application/atom+xml" title="Comments" href="/feeds/comments/">
       
     8 <link rel="shortcut icon" type="image/png" href="/support/figs/favicon.png">
       
     9 <script type="text/javascript" src="/support/jquery-min.js"></script>
       
    10 <script type="text/javascript" src="/support/form.js"></script>
       
    11 <script type="text/javascript" src="/support/hsbook.js"></script></head>
       
    12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
       
    13 <div class="navheader">
       
    14 <table width="100%" summary="Navigation header">
       
    15 <tr><th colspan="3" align="center">Chapter 14. Adding functionality with extensions</th></tr>
       
    16 <tr>
       
    17 <td width="20%" align="left">
       
    18 <a accesskey="p" href="advanced-uses-of-mercurial-queues.html">Prev</a> </td>
       
    19 <th width="60%" align="center"> </th>
       
    20 <td width="20%" align="right"> <a accesskey="n" href="migrating-to-mercurial.html">Next</a>
       
    21 </td>
       
    22 </tr>
       
    23 </table>
       
    24 <hr>
       
    25 </div>
       
    26 <div class="chapter" title="Chapter 14. Adding functionality with extensions">
       
    27 <div class="titlepage"><div><div><h2 class="title">
       
    28 <a name="chap:hgext"></a>Chapter 14. Adding functionality with extensions</h2></div></div></div>
       
    29 <div class="toc">
       
    30 <p><b>Table of Contents</b></p>
       
    31 <dl>
       
    32 <dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:inotify">14.1. Improve performance with the <code class="literal">inotify</code> extension</a></span></dt>
       
    33 <dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:extdiff">14.2. Flexible diff support with the <code class="literal">extdiff</code> extension</a></span></dt>
       
    34 <dd><dl><dt><span class="sect2"><a href="adding-functionality-with-extensions.html#id3071699">14.2.1. Defining command aliases</a></span></dt></dl></dd>
       
    35 <dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:transplant">14.3. Cherrypicking changes with the <code class="literal">transplant</code> extension</a></span></dt>
       
    36 <dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:patchbomb">14.4. Send changes via email with the <code class="literal">patchbomb</code> extension</a></span></dt>
       
    37 <dd><dl><dt><span class="sect2"><a href="adding-functionality-with-extensions.html#id3072184">14.4.1. Changing the behavior of patchbombs</a></span></dt></dl></dd>
       
    38 </dl>
       
    39 </div>
       
    40 <p><a name="x_4fe"></a>While the core of Mercurial is quite complete from a
       
    41     functionality standpoint, it's deliberately shorn of fancy
       
    42     features.  This approach of preserving simplicity keeps the
       
    43     software easy to deal with for both maintainers and users.</p>
       
    44 <p><a name="x_4ff"></a>However, Mercurial doesn't box you in with an inflexible
       
    45     command set: you can add features to it as
       
    46     <span class="emphasis"><em>extensions</em></span> (sometimes known as
       
    47     <span class="emphasis"><em>plugins</em></span>).  We've already discussed a few of
       
    48     these extensions in earlier chapters.</p>
       
    49 <p id="x_546"><a name="x_546"></a>When you provide a directory name, Mercurial will interpret
       
    50       this as “<span class="quote">operate on every file in this directory and its
       
    51 	subdirectories</span>”. Mercurial traverses the files and
       
    52       subdirectories in a directory in alphabetical order.  When it
       
    53       encounters a subdirectory, it will traverse that subdirectory
       
    54       before continuing with the current directory.</p>
       
    55 
       
    56 
       
    57 
       
    58 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
       
    59 <li class="listitem"><p><a name="x_500"></a><a class="xref" href="a-tour-of-mercurial-merging-work.html#sec:tour-merge:fetch" title="3.3. Simplifying the pull-merge-commit sequence">Section 3.3, “Simplifying the pull-merge-commit sequence”</a>
       
    60 	covers the <code class="literal">fetch</code> extension;
       
    61 	this combines pulling new changes and merging them with local
       
    62 	changes into a single command, <span class="command"><strong>fetch</strong></span>.</p></li>
       
    63 <li class="listitem"><p><a name="x_501"></a>In <a class="xref" href="handling-repository-events-with-hooks.html" title="Chapter 10. Handling repository events with hooks">Chapter 10, <i>Handling repository events with hooks</i></a>, we covered
       
    64 	several extensions that are useful for hook-related
       
    65 	functionality: <code class="literal">acl</code> adds
       
    66 	access control lists; <code class="literal">bugzilla</code> adds integration with the
       
    67 	Bugzilla bug tracking system; and <code class="literal">notify</code> sends notification emails on
       
    68 	new changes.</p></li>
       
    69 <li class="listitem"><p><a name="x_502"></a>The Mercurial Queues patch management extension is
       
    70 	so invaluable that it merits two chapters and an appendix all
       
    71 	to itself. <a class="xref" href="managing-change-with-mercurial-queues.html" title="Chapter 12. Managing change with Mercurial Queues">Chapter 12, <i>Managing change with Mercurial Queues</i></a> covers the
       
    72 	basics; <a class="xref" href="advanced-uses-of-mercurial-queues.html" title="Chapter 13. Advanced uses of Mercurial Queues">Chapter 13, <i>Advanced uses of Mercurial Queues</i></a> discusses advanced topics;
       
    73 	and <a class="xref" href="mercurial-queues-reference.html" title="Appendix B. Mercurial Queues reference">Appendix B, <i>Mercurial Queues reference</i></a> goes into detail on
       
    74 	each
       
    75 	command.</p></li>
       
    76 </ul></div>
       
    77 <p><a name="x_503"></a>In this chapter, we'll cover some of the other extensions that
       
    78     are available for Mercurial, and briefly touch on some of the
       
    79     machinery you'll need to know about if you want to write an
       
    80     extension of your own.</p>
       
    81 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a name="x_504"></a>In <a class="xref" href="adding-functionality-with-extensions.html#sec:hgext:inotify" title="14.1. Improve performance with the inotify extension">Section 14.1, “Improve performance with the <code class="literal">inotify</code> extension”</a>,
       
    82 	we'll discuss the possibility of <span class="emphasis"><em>huge</em></span>
       
    83 	performance improvements using the <code class="literal">inotify</code> extension.</p></li></ul></div>
       
    84 <div class="sect1" title="14.1. Improve performance with the inotify extension">
       
    85 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
       
    86 <a name="sec:hgext:inotify"></a>14.1. Improve performance with the <code class="literal">inotify</code> extension</h2></div></div></div>
       
    87 <p><a name="x_505"></a>Are you interested in having some of the most common
       
    88       Mercurial operations run as much as a hundred times faster?
       
    89       Read on!</p>
       
    90 <p><a name="x_506"></a>Mercurial has great performance under normal circumstances.
       
    91       For example, when you run the <span class="command"><strong>hg
       
    92 	status</strong></span> command, Mercurial has to scan almost every
       
    93       directory and file in your repository so that it can display
       
    94       file status.  Many other Mercurial commands need to do the same
       
    95       work behind the scenes; for example, the <span class="command"><strong>hg diff</strong></span> command uses the status
       
    96       machinery to avoid doing an expensive comparison operation on
       
    97       files that obviously haven't changed.</p>
       
    98 <p><a name="x_507"></a>Because obtaining file status is crucial to good
       
    99       performance, the authors of Mercurial have optimised this code
       
   100       to within an inch of its life.  However, there's no avoiding the
       
   101       fact that when you run <span class="command"><strong>hg
       
   102 	status</strong></span>, Mercurial is going to have to perform at
       
   103       least one expensive system call for each managed file to
       
   104       determine whether it's changed since the last time Mercurial
       
   105       checked.  For a sufficiently large repository, this can take a
       
   106       long time.</p>
       
   107 <p><a name="x_508"></a>To put a number on the magnitude of this effect, I created a
       
   108       repository containing 150,000 managed files.  I timed <span class="command"><strong>hg status</strong></span> as taking ten seconds to
       
   109       run, even when <span class="emphasis"><em>none</em></span> of those files had been
       
   110       modified.</p>
       
   111 <p><a name="x_509"></a>Many modern operating systems contain a file notification
       
   112       facility. If a program signs up to an appropriate service, the
       
   113       operating system will notify it every time a file of interest is
       
   114       created, modified, or deleted.  On Linux systems, the kernel
       
   115       component that does this is called
       
   116       <code class="literal">inotify</code>.</p>
       
   117 <p><a name="x_50a"></a>Mercurial's <code class="literal">inotify</code>
       
   118       extension talks to the kernel's <code class="literal">inotify</code>
       
   119       component to optimise <span class="command"><strong>hg status</strong></span>
       
   120       commands.  The extension has two components.  A daemon sits in
       
   121       the background and receives notifications from the
       
   122       <code class="literal">inotify</code> subsystem.  It also listens for
       
   123       connections from a regular Mercurial command.  The extension
       
   124       modifies Mercurial's behavior so that instead of scanning the
       
   125       filesystem, it queries the daemon.  Since the daemon has perfect
       
   126       information about the state of the repository, it can respond
       
   127       with a result instantaneously, avoiding the need to scan every
       
   128       directory and file in the repository.</p>
       
   129 <p><a name="x_50b"></a>Recall the ten seconds that I measured plain Mercurial as
       
   130       taking to run <span class="command"><strong>hg status</strong></span> on a
       
   131       150,000 file repository.  With the <code class="literal">inotify</code> extension enabled, the time
       
   132       dropped to 0.1 seconds, a factor of <span class="emphasis"><em>one
       
   133 	hundred</em></span> faster.</p>
       
   134 <p><a name="x_50c"></a>Before we continue, please pay attention to some
       
   135       caveats.</p>
       
   136 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
       
   137 <li class="listitem"><p><a name="x_50d"></a>The <code class="literal">inotify</code>
       
   138 	  extension is Linux-specific.  Because it interfaces directly
       
   139 	  to the Linux kernel's <code class="literal">inotify</code> subsystem,
       
   140 	  it does not work on other operating systems.</p></li>
       
   141 <li class="listitem"><p><a name="x_50e"></a>It should work on any Linux distribution that
       
   142 	  was released after early 2005.  Older distributions are
       
   143 	  likely to have a kernel that lacks
       
   144 	  <code class="literal">inotify</code>, or a version of
       
   145 	  <code class="literal">glibc</code> that does not have the necessary
       
   146 	  interfacing support.</p></li>
       
   147 <li class="listitem"><p><a name="x_50f"></a>Not all filesystems are suitable for use with
       
   148 	  the <code class="literal">inotify</code> extension.
       
   149 	  Network filesystems such as NFS are a non-starter, for
       
   150 	  example, particularly if you're running Mercurial on several
       
   151 	  systems, all mounting the same network filesystem.  The
       
   152 	  kernel's <code class="literal">inotify</code> system has no way of
       
   153 	  knowing about changes made on another system.  Most local
       
   154 	  filesystems (e.g. ext3, XFS, ReiserFS) should work
       
   155 	  fine.</p></li>
       
   156 </ul></div>
       
   157 <p><a name="x_510"></a>The <code class="literal">inotify</code> extension is
       
   158       not yet shipped with Mercurial as of May 2007, so it's a little
       
   159       more involved to set up than other extensions.  But the
       
   160       performance improvement is worth it!</p>
       
   161 <p><a name="x_511"></a>The extension currently comes in two parts: a set of patches
       
   162       to the Mercurial source code, and a library of Python bindings
       
   163       to the <code class="literal">inotify</code> subsystem.</p>
       
   164 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
       
   165 <tr>
       
   166 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="figs/note.png"></td>
       
   167 <th align="left">Note</th>
       
   168 </tr>
       
   169 <tr><td align="left" valign="top"><p><a name="x_512"></a>  There are <span class="emphasis"><em>two</em></span> Python
       
   170 	<code class="literal">inotify</code> binding libraries.  One of them is
       
   171 	called <code class="literal">pyinotify</code>, and is packaged by some
       
   172 	Linux distributions as <code class="literal">python-inotify</code>.
       
   173 	This is <span class="emphasis"><em>not</em></span> the one you'll need, as it is
       
   174 	too buggy and inefficient to be practical.</p></td></tr>
       
   175 </table></div>
       
   176 <p><a name="x_513"></a>To get going, it's best to already have a functioning copy
       
   177       of Mercurial installed.</p>
       
   178 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
       
   179 <tr>
       
   180 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="figs/note.png"></td>
       
   181 <th align="left">Note</th>
       
   182 </tr>
       
   183 <tr><td align="left" valign="top"><p><a name="x_514"></a>  If you follow the instructions below, you'll be
       
   184 	<span class="emphasis"><em>replacing</em></span> and overwriting any existing
       
   185 	installation of Mercurial that you might already have, using
       
   186 	the latest <span class="quote">“<span class="quote">bleeding edge</span>”</span> Mercurial code. Don't
       
   187 	say you weren't warned!</p></td></tr>
       
   188 </table></div>
       
   189 <div class="orderedlist"><ol class="orderedlist" type="1">
       
   190 <li class="listitem">
       
   191 <p><a name="x_515"></a>Clone the Python <code class="literal">inotify</code>
       
   192 	  binding repository.  Build and install it.</p>
       
   193 <pre class="programlisting">hg clone http://hg.kublai.com/python/inotify
       
   194 cd inotify
       
   195 python setup.py build --force
       
   196 sudo python setup.py install --skip-build</pre>
       
   197 </li>
       
   198 <li class="listitem">
       
   199 <p><a name="x_516"></a>Clone the <code class="filename">crew</code> Mercurial repository.
       
   200 	  Clone the <code class="literal">inotify</code> patch
       
   201 	  repository so that Mercurial Queues will be able to apply
       
   202 	  patches to your cope of the <code class="filename">crew</code> repository.</p>
       
   203 <pre class="programlisting">hg clone http://hg.intevation.org/mercurial/crew
       
   204 hg clone crew inotify
       
   205 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</pre>
       
   206 </li>
       
   207 <li class="listitem"><p><a name="x_517"></a>Make sure that you have the Mercurial Queues
       
   208 	  extension, <code class="literal">mq</code>, enabled.  If
       
   209 	  you've never used MQ, read <a class="xref" href="managing-change-with-mercurial-queues.html#sec:mq:start" title="12.5. Getting started with Mercurial Queues">Section 12.5, “Getting started with Mercurial Queues”</a> to get started
       
   210 	  quickly.</p></li>
       
   211 <li class="listitem">
       
   212 <p><a name="x_518"></a>Go into the <code class="filename">inotify</code> repo, and apply all
       
   213 	  of the <code class="literal">inotify</code> patches
       
   214 	  using the <code class="option">hg
       
   215 	    -a</code> option to the <span class="command"><strong>qpush</strong></span> command.</p>
       
   216 <pre class="programlisting">cd inotify
       
   217 hg qpush -a</pre>
       
   218 </li>
       
   219 <li class="listitem"><p><a name="x_519"></a>  If you get an error message from <span class="command"><strong>qpush</strong></span>, you should not continue.
       
   220 	  Instead, ask for help.</p></li>
       
   221 <li class="listitem">
       
   222 <p><a name="x_51a"></a>Build and install the patched version of
       
   223 	  Mercurial.</p>
       
   224 <pre class="programlisting">python setup.py build --force
       
   225 sudo python setup.py install --skip-build</pre>
       
   226 </li>
       
   227 </ol></div>
       
   228 <p><a name="x_51b"></a>Once you've build a suitably patched version of Mercurial,
       
   229       all you need to do to enable the <code class="literal">inotify</code> extension is add an entry to
       
   230       your <code class="filename">~/.hgrc</code>.</p>
       
   231 <pre class="programlisting">[extensions] inotify =</pre>
       
   232 <p><a name="x_51c"></a>When the <code class="literal">inotify</code> extension
       
   233       is enabled, Mercurial will automatically and transparently start
       
   234       the status daemon the first time you run a command that needs
       
   235       status in a repository.  It runs one status daemon per
       
   236       repository.</p>
       
   237 <p><a name="x_51d"></a>The status daemon is started silently, and runs in the
       
   238       background.  If you look at a list of running processes after
       
   239       you've enabled the <code class="literal">inotify</code>
       
   240       extension and run a few commands in different repositories,
       
   241       you'll thus see a few <code class="literal">hg</code> processes sitting
       
   242       around, waiting for updates from the kernel and queries from
       
   243       Mercurial.</p>
       
   244 <p><a name="x_51e"></a>The first time you run a Mercurial command in a repository
       
   245       when you have the <code class="literal">inotify</code>
       
   246       extension enabled, it will run with about the same performance
       
   247       as a normal Mercurial command.  This is because the status
       
   248       daemon needs to perform a normal status scan so that it has a
       
   249       baseline against which to apply later updates from the kernel.
       
   250       However, <span class="emphasis"><em>every</em></span> subsequent command that does
       
   251       any kind of status check should be noticeably faster on
       
   252       repositories of even fairly modest size.  Better yet, the bigger
       
   253       your repository is, the greater a performance advantage you'll
       
   254       see.  The <code class="literal">inotify</code> daemon makes
       
   255       status operations almost instantaneous on repositories of all
       
   256       sizes!</p>
       
   257 <p><a name="x_51f"></a>If you like, you can manually start a status daemon using
       
   258       the <span class="command"><strong>inserve</strong></span> command.
       
   259       This gives you slightly finer control over how the daemon ought
       
   260       to run.  This command will of course only be available when the
       
   261       <code class="literal">inotify</code> extension is
       
   262       enabled.</p>
       
   263 <p><a name="x_520"></a>When you're using the <code class="literal">inotify</code> extension, you should notice
       
   264       <span class="emphasis"><em>no difference at all</em></span> in Mercurial's
       
   265       behavior, with the sole exception of status-related commands
       
   266       running a whole lot faster than they used to.  You should
       
   267       specifically expect that commands will not print different
       
   268       output; neither should they give different results. If either of
       
   269       these situations occurs, please report a bug.</p>
       
   270 </div>
       
   271 <div class="sect1" title="14.2. Flexible diff support with the extdiff extension">
       
   272 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
       
   273 <a name="sec:hgext:extdiff"></a>14.2. Flexible diff support with the <code class="literal">extdiff</code> extension</h2></div></div></div>
       
   274 <p><a name="x_521"></a>Mercurial's built-in <span class="command"><strong>hg
       
   275 	diff</strong></span> command outputs plaintext unified diffs.</p>
       
   276 <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>hg diff</code></strong>
       
   277 diff -r 80997726a0ea myfile
       
   278 --- a/myfile	Wed Jan 06 06:50:18 2010 +0000
       
   279 +++ b/myfile	Wed Jan 06 06:50:18 2010 +0000
       
   280 @@ -1,1 +1,2 @@
       
   281  The first line.
       
   282 +The second line.
       
   283 </pre>
       
   284 <p><a name="x_522"></a>If you would like to use an external tool to display
       
   285       modifications, you'll want to use the <code class="literal">extdiff</code> extension.  This will let you
       
   286       use, for example, a graphical diff tool.</p>
       
   287 <p><a name="x_523"></a>The <code class="literal">extdiff</code> extension is
       
   288       bundled with Mercurial, so it's easy to set up.  In the <code class="literal">extensions</code> section of your
       
   289       <code class="filename">~/.hgrc</code>, simply add a
       
   290       one-line entry to enable the extension.</p>
       
   291 <pre class="programlisting">[extensions]
       
   292 extdiff =</pre>
       
   293 <p><a name="x_524"></a>This introduces a command named <span class="command"><strong>extdiff</strong></span>, which by default uses
       
   294       your system's <span class="command"><strong>diff</strong></span> command to generate a
       
   295       unified diff in the same form as the built-in <span class="command"><strong>hg diff</strong></span> command.</p>
       
   296 <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>hg extdiff</code></strong>
       
   297 --- a.80997726a0ea/myfile	2010-01-06 06:50:18.613674526 +0000
       
   298 +++ /tmp/extdiffNErQlu/a/myfile	2010-01-06 06:50:18.437687076 +0000
       
   299 @@ -1 +1,2 @@
       
   300  The first line.
       
   301 +The second line.
       
   302 </pre>
       
   303 <p><a name="x_525"></a>The result won't be exactly the same as with the built-in
       
   304       <span class="command"><strong>hg diff</strong></span> variations, because the
       
   305       output of <span class="command"><strong>diff</strong></span> varies from one system to
       
   306       another, even when passed the same options.</p>
       
   307 <p><a name="x_526"></a>As the <span class="quote">“<span class="quote"><code class="literal">making snapshot</code></span>”</span>
       
   308       lines of output above imply, the <span class="command"><strong>extdiff</strong></span> command works by
       
   309       creating two snapshots of your source tree.  The first snapshot
       
   310       is of the source revision; the second, of the target revision or
       
   311       working directory.  The <span class="command"><strong>extdiff</strong></span> command generates
       
   312       these snapshots in a temporary directory, passes the name of
       
   313       each directory to an external diff viewer, then deletes the
       
   314       temporary directory.  For efficiency, it only snapshots the
       
   315       directories and files that have changed between the two
       
   316       revisions.</p>
       
   317 <p><a name="x_527"></a>Snapshot directory names have the same base name as your
       
   318       repository. If your repository path is <code class="filename">/quux/bar/foo</code>, then <code class="filename">foo</code> will be the name of each
       
   319       snapshot directory.  Each snapshot directory name has its
       
   320       changeset ID appended, if appropriate.  If a snapshot is of
       
   321       revision <code class="literal">a631aca1083f</code>, the directory will be
       
   322       named <code class="filename">foo.a631aca1083f</code>.
       
   323       A snapshot of the working directory won't have a changeset ID
       
   324       appended, so it would just be <code class="filename">foo</code> in this example.  To see what
       
   325       this looks like in practice, look again at the <span class="command"><strong>extdiff</strong></span> example above.  Notice
       
   326       that the diff has the snapshot directory names embedded in its
       
   327       header.</p>
       
   328 <p><a name="x_528"></a>The <span class="command"><strong>extdiff</strong></span> command
       
   329       accepts two important options. The <code class="option">hg -p</code> option
       
   330       lets you choose a program to view differences with, instead of
       
   331       <span class="command"><strong>diff</strong></span>.  With the <code class="option">hg -o</code> option,
       
   332       you can change the options that <span class="command"><strong>extdiff</strong></span> passes to the program
       
   333       (by default, these options are
       
   334       <span class="quote">“<span class="quote"><code class="literal">-Npru</code></span>”</span>, which only make sense
       
   335       if you're running <span class="command"><strong>diff</strong></span>).  In other respects,
       
   336       the <span class="command"><strong>extdiff</strong></span> command
       
   337       acts similarly to the built-in <span class="command"><strong>hg
       
   338 	diff</strong></span> command: you use the same option names, syntax,
       
   339       and arguments to specify the revisions you want, the files you
       
   340       want, and so on.</p>
       
   341 <p><a name="x_529"></a>As an example, here's how to run the normal system
       
   342       <span class="command"><strong>diff</strong></span> command, getting it to generate context
       
   343       diffs (using the <code class="option">-c</code> option)
       
   344       instead of unified diffs, and five lines of context instead of
       
   345       the default three (passing <code class="literal">5</code> as the argument
       
   346       to the <code class="option">-C</code> option).</p>
       
   347 <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>hg extdiff -o -NprcC5</code></strong>
       
   348 *** a.80997726a0ea/myfile	Wed Jan  6 06:50:18 2010
       
   349 --- /tmp/extdiffNErQlu/a/myfile	Wed Jan  6 06:50:18 2010
       
   350 ***************
       
   351 *** 1 ****
       
   352 --- 1,2 ----
       
   353   The first line.
       
   354 + The second line.
       
   355 </pre>
       
   356 <p><a name="x_52a"></a>Launching a visual diff tool is just as easy.  Here's how to
       
   357       launch the <span class="command"><strong>kdiff3</strong></span> viewer.</p>
       
   358 <pre class="programlisting">hg extdiff -p kdiff3 -o</pre>
       
   359 <p><a name="x_52b"></a>If your diff viewing command can't deal with directories,
       
   360       you can easily work around this with a little scripting.  For an
       
   361       example of such scripting in action with the <code class="literal">mq</code> extension and the
       
   362       <span class="command"><strong>interdiff</strong></span> command, see <a class="xref" href="advanced-uses-of-mercurial-queues.html#mq-collab:tips:interdiff" title="13.9.2. Viewing the history of a patch">Section 13.9.2, “Viewing the history of a patch”</a>.</p>
       
   363 <div class="sect2" title="14.2.1. Defining command aliases">
       
   364 <div class="titlepage"><div><div><h3 class="title">
       
   365 <a name="id3071699"></a>14.2.1. Defining command aliases</h3></div></div></div>
       
   366 <p><a name="x_52c"></a>It can be cumbersome to remember the options to both the
       
   367 	<span class="command"><strong>extdiff</strong></span> command and
       
   368 	the diff viewer you want to use, so the <code class="literal">extdiff</code> extension lets you define
       
   369 	<span class="emphasis"><em>new</em></span> commands that will invoke your diff
       
   370 	viewer with exactly the right options.</p>
       
   371 <p><a name="x_52d"></a>All you need to do is edit your <code class="filename">~/.hgrc</code>, and add a section named
       
   372 	<code class="literal">extdiff</code>.  Inside this
       
   373 	section, you can define multiple commands.  Here's how to add
       
   374 	a <code class="literal">kdiff3</code> command.  Once you've defined
       
   375 	this, you can type <span class="quote">“<span class="quote"><code class="literal">hg kdiff3</code></span>”</span>
       
   376 	and the <code class="literal">extdiff</code> extension
       
   377 	will run <span class="command"><strong>kdiff3</strong></span> for you.</p>
       
   378 <pre class="programlisting">[extdiff]
       
   379 cmd.kdiff3 =</pre>
       
   380 <p><a name="x_52e"></a>If you leave the right hand side of the definition empty,
       
   381 	as above, the <code class="literal">extdiff</code>
       
   382 	extension uses the name of the command you defined as the name
       
   383 	of the external program to run.  But these names don't have to
       
   384 	be the same.  Here, we define a command named
       
   385 	<span class="quote">“<span class="quote"><code class="literal">hg wibble</code></span>”</span>, which runs
       
   386 	<span class="command"><strong>kdiff3</strong></span>.</p>
       
   387 <pre class="programlisting">[extdiff]
       
   388  cmd.wibble = kdiff3</pre>
       
   389 <p><a name="x_52f"></a>You can also specify the default options that you want to
       
   390 	invoke your diff viewing program with.  The prefix to use is
       
   391 	<span class="quote">“<span class="quote"><code class="literal">opts.</code></span>”</span>, followed by the name
       
   392 	of the command to which the options apply.  This example
       
   393 	defines a <span class="quote">“<span class="quote"><code class="literal">hg vimdiff</code></span>”</span> command
       
   394 	that runs the <span class="command"><strong>vim</strong></span> editor's
       
   395 	<code class="literal">DirDiff</code> extension.</p>
       
   396 <pre class="programlisting">[extdiff]
       
   397  cmd.vimdiff = vim
       
   398 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</pre>
       
   399 </div>
       
   400 </div>
       
   401 <div class="sect1" title="14.3. Cherrypicking changes with the transplant extension">
       
   402 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
       
   403 <a name="sec:hgext:transplant"></a>14.3. Cherrypicking changes with the <code class="literal">transplant</code> extension</h2></div></div></div>
       
   404 <p><a name="x_530"></a>Need to have a long chat with Brendan about this.</p>
       
   405 </div>
       
   406 <div class="sect1" title="14.4. Send changes via email with the patchbomb extension">
       
   407 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
       
   408 <a name="sec:hgext:patchbomb"></a>14.4. Send changes via email with the <code class="literal">patchbomb</code> extension</h2></div></div></div>
       
   409 <p><a name="x_531"></a>Many projects have a culture of <span class="quote">“<span class="quote">change
       
   410 	review</span>”</span>, in which people send their modifications to a
       
   411       mailing list for others to read and comment on before they
       
   412       commit the final version to a shared repository.  Some projects
       
   413       have people who act as gatekeepers; they apply changes from
       
   414       other people to a repository to which those others don't have
       
   415       access.</p>
       
   416 <p><a name="x_532"></a>Mercurial makes it easy to send changes over email for
       
   417       review or application, via its <code class="literal">patchbomb</code> extension.  The extension is
       
   418       so named because changes are formatted as patches, and it's usual
       
   419       to send one changeset per email message.  Sending a long series
       
   420       of changes by email is thus much like <span class="quote">“<span class="quote">bombing</span>”</span> the
       
   421       recipient's inbox, hence <span class="quote">“<span class="quote">patchbomb</span>”</span>.</p>
       
   422 <p><a name="x_533"></a>As usual, the basic configuration of the <code class="literal">patchbomb</code> extension takes just one or
       
   423       two lines in your <code class="filename">
       
   424 	/.hgrc</code>.</p>
       
   425 <pre class="programlisting">[extensions]
       
   426 patchbomb =</pre>
       
   427 <p><a name="x_534"></a>Once you've enabled the extension, you will have a new
       
   428       command available, named <span class="command"><strong>email</strong></span>.</p>
       
   429 <p><a name="x_535"></a>The safest and best way to invoke the <span class="command"><strong>email</strong></span> command is to
       
   430       <span class="emphasis"><em>always</em></span> run it first with the <code class="option">hg -n</code> option.
       
   431       This will show you what the command <span class="emphasis"><em>would</em></span>
       
   432       send, without actually sending anything.  Once you've had a
       
   433       quick glance over the changes and verified that you are sending
       
   434       the right ones, you can rerun the same command, with the <code class="option">hg -n</code> option
       
   435       removed.</p>
       
   436 <p><a name="x_536"></a>The <span class="command"><strong>email</strong></span> command
       
   437       accepts the same kind of revision syntax as every other
       
   438       Mercurial command.  For example, this command will send every
       
   439       revision between 7 and <code class="literal">tip</code>, inclusive.</p>
       
   440 <pre class="programlisting">hg email -n 7:tip</pre>
       
   441 <p><a name="x_537"></a>You can also specify a <span class="emphasis"><em>repository</em></span> to
       
   442       compare with.  If you provide a repository but no revisions, the
       
   443       <span class="command"><strong>email</strong></span> command will
       
   444       send all revisions in the local repository that are not present
       
   445       in the remote repository.  If you additionally specify revisions
       
   446       or a branch name (the latter using the <code class="option">hg -b</code> option),
       
   447       this will constrain the revisions sent.</p>
       
   448 <p><a name="x_538"></a>It's perfectly safe to run the <span class="command"><strong>email</strong></span> command without the
       
   449       names of the people you want to send to: if you do this, it will
       
   450       just prompt you for those values interactively.  (If you're
       
   451       using a Linux or Unix-like system, you should have enhanced
       
   452       <code class="literal">readline</code>-style editing capabilities when
       
   453       entering those headers, too, which is useful.)</p>
       
   454 <p><a name="x_539"></a>When you are sending just one revision, the <span class="command"><strong>email</strong></span> command will by
       
   455       default use the first line of the changeset description as the
       
   456       subject of the single email message it sends.</p>
       
   457 <p><a name="x_53a"></a>If you send multiple revisions, the <span class="command"><strong>email</strong></span> command will usually
       
   458       send one message per changeset.  It will preface the series with
       
   459       an introductory message, in which you should describe the
       
   460       purpose of the series of changes you're sending.</p>
       
   461 <div class="sect2" title="14.4.1. Changing the behavior of patchbombs">
       
   462 <div class="titlepage"><div><div><h3 class="title">
       
   463 <a name="id3072184"></a>14.4.1. Changing the behavior of patchbombs</h3></div></div></div>
       
   464 <p><a name="x_53b"></a>Not every project has exactly the same conventions for
       
   465 	sending changes in email; the <code class="literal">patchbomb</code> extension tries to
       
   466 	accommodate a number of variations through command line
       
   467 	options.</p>
       
   468 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
       
   469 <li class="listitem"><p><a name="x_53c"></a>You can write a subject for the introductory
       
   470 	    message on the command line using the <code class="option">hg -s</code>
       
   471 	    option.  This takes one argument, the text of the subject
       
   472 	    to use.</p></li>
       
   473 <li class="listitem"><p><a name="x_53d"></a>To change the email address from which the
       
   474 	    messages originate, use the <code class="option">hg -f</code>
       
   475 	    option.  This takes one argument, the email address to
       
   476 	    use.</p></li>
       
   477 <li class="listitem"><p><a name="x_53e"></a>The default behavior is to send unified diffs
       
   478 	    (see <a class="xref" href="managing-change-with-mercurial-queues.html#sec:mq:patch" title="12.4. Understanding patches">Section 12.4, “Understanding patches”</a> for a
       
   479 	    description of the
       
   480 	    format), one per message.  You can send a binary bundle
       
   481 	    instead with the <code class="option">hg -b</code>
       
   482 	    option.</p></li>
       
   483 <li class="listitem"><p><a name="x_53f"></a>Unified diffs are normally prefaced with a
       
   484 	    metadata header.  You can omit this, and send unadorned
       
   485 	    diffs, with the <code class="option">hg
       
   486 	      --plain</code> option.</p></li>
       
   487 <li class="listitem"><p><a name="x_540"></a>Diffs are normally sent <span class="quote">“<span class="quote">inline</span>”</span>,
       
   488 	    in the same body part as the description of a patch.  This
       
   489 	    makes it easiest for the largest number of readers to
       
   490 	    quote and respond to parts of a diff, as some mail clients
       
   491 	    will only quote the first MIME body part in a message. If
       
   492 	    you'd prefer to send the description and the diff in
       
   493 	    separate body parts, use the <code class="option">hg -a</code>
       
   494 	    option.</p></li>
       
   495 <li class="listitem"><p><a name="x_541"></a>Instead of sending mail messages, you can
       
   496 	    write them to an <code class="literal">mbox</code>-format mail
       
   497 	    folder using the <code class="option">hg -m</code>
       
   498 	    option.  That option takes one argument, the name of the
       
   499 	    file to write to.</p></li>
       
   500 <li class="listitem"><p><a name="x_542"></a>If you would like to add a
       
   501 	    <span class="command"><strong>diffstat</strong></span>-format summary to each patch,
       
   502 	    and one to the introductory message, use the <code class="option">hg -d</code>
       
   503 	    option.  The <span class="command"><strong>diffstat</strong></span> command displays
       
   504 	    a table containing the name of each file patched, the
       
   505 	    number of lines affected, and a histogram showing how much
       
   506 	    each file is modified.  This gives readers a qualitative
       
   507 	    glance at how complex a patch is.</p></li>
       
   508 </ul></div>
       
   509 </div>
       
   510 </div>
       
   511 </div>
       
   512 <div class="navfooter">
       
   513 <hr>
       
   514 <table width="100%" summary="Navigation footer">
       
   515 <tr>
       
   516 <td width="40%" align="left">
       
   517 <a accesskey="p" href="advanced-uses-of-mercurial-queues.html">Prev</a> </td>
       
   518 <td width="20%" align="center"> </td>
       
   519 <td width="40%" align="right"> <a accesskey="n" href="migrating-to-mercurial.html">Next</a>
       
   520 </td>
       
   521 </tr>
       
   522 <tr>
       
   523 <td width="40%" align="left" valign="top">Chapter 13. Advanced uses of Mercurial Queues </td>
       
   524 <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
       
   525 <td width="40%" align="right" valign="top"> Appendix A. Migrating to Mercurial</td>
       
   526 </tr>
       
   527 </table>
       
   528 </div>
       
   529 </body>
       
   530 </html>