hgbook
annotate fr/ch14-hgext.xml @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
parents | 6b680d569bb4 f0110009e946 |
children |
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 |
bos@559 | 142 not yet shipped with Mercurial as of May 2007, so it's a little |
bos@559 | 143 more involved to set up than other extensions. But the |
bos@559 | 144 performance improvement is worth it!</para> |
bos@559 | 145 |
bos@584 | 146 <para id="x_511">The extension currently comes in two parts: a set of patches |
bos@559 | 147 to the Mercurial source code, and a library of Python bindings |
bos@559 | 148 to the <literal>inotify</literal> subsystem.</para> |
bos@559 | 149 <note> |
bos@584 | 150 <para id="x_512"> There are <emphasis>two</emphasis> Python |
bos@559 | 151 <literal>inotify</literal> binding libraries. One of them is |
bos@559 | 152 called <literal>pyinotify</literal>, and is packaged by some |
bos@559 | 153 Linux distributions as <literal>python-inotify</literal>. |
bos@559 | 154 This is <emphasis>not</emphasis> the one you'll need, as it is |
bos@559 | 155 too buggy and inefficient to be practical.</para> |
bos@559 | 156 </note> |
bos@584 | 157 <para id="x_513">To get going, it's best to already have a functioning copy |
bos@559 | 158 of Mercurial installed.</para> |
bos@559 | 159 <note> |
bos@584 | 160 <para id="x_514"> If you follow the instructions below, you'll be |
bos@559 | 161 <emphasis>replacing</emphasis> and overwriting any existing |
bos@559 | 162 installation of Mercurial that you might already have, using |
bos@559 | 163 the latest <quote>bleeding edge</quote> Mercurial code. Don't |
bos@559 | 164 say you weren't warned!</para> |
bos@559 | 165 </note> |
bos@559 | 166 <orderedlist> |
bos@584 | 167 <listitem><para id="x_515">Clone the Python <literal>inotify</literal> |
bos@559 | 168 binding repository. Build and install it.</para> |
bos@580 | 169 <programlisting>hg clone http://hg.kublai.com/python/inotify |
bos@580 | 170 cd inotify |
bos@580 | 171 python setup.py build --force |
bos@580 | 172 sudo python setup.py install --skip-build</programlisting> |
bos@559 | 173 </listitem> |
bos@584 | 174 <listitem><para id="x_516">Clone the <filename |
bos@559 | 175 class="directory">crew</filename> Mercurial repository. |
bos@559 | 176 Clone the <literal role="hg-ext">inotify</literal> patch |
bos@559 | 177 repository so that Mercurial Queues will be able to apply |
bos@559 | 178 patches to your cope of the <filename |
bos@559 | 179 class="directory">crew</filename> repository.</para> |
bos@580 | 180 <programlisting>hg clone http://hg.intevation.org/mercurial/crew |
bos@580 | 181 hg clone crew inotify |
bos@580 | 182 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> |
bos@559 | 183 </listitem> |
bos@584 | 184 <listitem><para id="x_517">Make sure that you have the Mercurial Queues |
bos@559 | 185 extension, <literal role="hg-ext">mq</literal>, enabled. If |
bos@592 | 186 you've never used MQ, read <xref |
bos@559 | 187 linkend="sec:mq:start"/> to get started |
bos@559 | 188 quickly.</para> |
bos@559 | 189 </listitem> |
bos@584 | 190 <listitem><para id="x_518">Go into the <filename |
bos@559 | 191 class="directory">inotify</filename> repo, and apply all |
bos@559 | 192 of the <literal role="hg-ext">inotify</literal> patches |
bos@559 | 193 using the <option role="hg-ext-mq-cmd-qpush-opt">hg |
bos@559 | 194 -a</option> option to the <command |
bos@559 | 195 role="hg-ext-mq">qpush</command> command.</para> |
bos@580 | 196 <programlisting>cd inotify |
bos@580 | 197 hg qpush -a</programlisting> |
bos@559 | 198 </listitem> |
bos@584 | 199 <listitem><para id="x_519"> If you get an error message from <command |
bos@559 | 200 role="hg-ext-mq">qpush</command>, you should not continue. |
bos@559 | 201 Instead, ask for help.</para> |
bos@559 | 202 </listitem> |
bos@584 | 203 <listitem><para id="x_51a">Build and install the patched version of |
bos@559 | 204 Mercurial.</para> |
bos@580 | 205 <programlisting>python setup.py build --force |
bos@580 | 206 sudo python setup.py install --skip-build</programlisting> |
bos@559 | 207 </listitem> |
bos@559 | 208 </orderedlist> |
bos@584 | 209 <para id="x_51b">Once you've build a suitably patched version of Mercurial, |
bos@559 | 210 all you need to do to enable the <literal |
bos@559 | 211 role="hg-ext">inotify</literal> extension is add an entry to |
bos@580 | 212 your <filename role="special">~/.hgrc</filename>.</para> |
bos@559 | 213 <programlisting>[extensions] inotify =</programlisting> |
bos@584 | 214 <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension |
bos@559 | 215 is enabled, Mercurial will automatically and transparently start |
bos@559 | 216 the status daemon the first time you run a command that needs |
bos@559 | 217 status in a repository. It runs one status daemon per |
bos@559 | 218 repository.</para> |
bos@559 | 219 |
bos@584 | 220 <para id="x_51d">The status daemon is started silently, and runs in the |
bos@559 | 221 background. If you look at a list of running processes after |
bos@559 | 222 you've enabled the <literal role="hg-ext">inotify</literal> |
bos@559 | 223 extension and run a few commands in different repositories, |
bos@559 | 224 you'll thus see a few <literal>hg</literal> processes sitting |
bos@559 | 225 around, waiting for updates from the kernel and queries from |
bos@559 | 226 Mercurial.</para> |
bos@559 | 227 |
bos@584 | 228 <para id="x_51e">The first time you run a Mercurial command in a repository |
bos@559 | 229 when you have the <literal role="hg-ext">inotify</literal> |
bos@559 | 230 extension enabled, it will run with about the same performance |
bos@559 | 231 as a normal Mercurial command. This is because the status |
bos@559 | 232 daemon needs to perform a normal status scan so that it has a |
bos@559 | 233 baseline against which to apply later updates from the kernel. |
bos@559 | 234 However, <emphasis>every</emphasis> subsequent command that does |
bos@559 | 235 any kind of status check should be noticeably faster on |
bos@559 | 236 repositories of even fairly modest size. Better yet, the bigger |
bos@559 | 237 your repository is, the greater a performance advantage you'll |
bos@559 | 238 see. The <literal role="hg-ext">inotify</literal> daemon makes |
bos@559 | 239 status operations almost instantaneous on repositories of all |
bos@559 | 240 sizes!</para> |
bos@559 | 241 |
bos@584 | 242 <para id="x_51f">If you like, you can manually start a status daemon using |
bos@559 | 243 the <command role="hg-ext-inotify">inserve</command> command. |
bos@559 | 244 This gives you slightly finer control over how the daemon ought |
bos@559 | 245 to run. This command will of course only be available when the |
bos@559 | 246 <literal role="hg-ext">inotify</literal> extension is |
bos@559 | 247 enabled.</para> |
bos@559 | 248 |
bos@584 | 249 <para id="x_520">When you're using the <literal |
bos@559 | 250 role="hg-ext">inotify</literal> extension, you should notice |
bos@559 | 251 <emphasis>no difference at all</emphasis> in Mercurial's |
bos@672 | 252 behavior, with the sole exception of status-related commands |
bos@559 | 253 running a whole lot faster than they used to. You should |
bos@559 | 254 specifically expect that commands will not print different |
bos@559 | 255 output; neither should they give different results. If either of |
bos@559 | 256 these situations occurs, please report a bug.</para> |
bos@559 | 257 |
bos@559 | 258 </sect1> |
bos@559 | 259 <sect1 id="sec:hgext:extdiff"> |
bos@559 | 260 <title>Flexible diff support with the <literal |
bos@559 | 261 role="hg-ext">extdiff</literal> extension</title> |
bos@559 | 262 |
bos@584 | 263 <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg |
bos@567 | 264 diff</command> command outputs plaintext unified diffs.</para> |
bos@567 | 265 |
bos@567 | 266 &interaction.extdiff.diff; |
bos@567 | 267 |
bos@584 | 268 <para id="x_522">If you would like to use an external tool to display |
bos@567 | 269 modifications, you'll want to use the <literal |
bos@567 | 270 role="hg-ext">extdiff</literal> extension. This will let you |
bos@567 | 271 use, for example, a graphical diff tool.</para> |
bos@559 | 272 |
bos@584 | 273 <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is |
bos@559 | 274 bundled with Mercurial, so it's easy to set up. In the <literal |
bos@559 | 275 role="rc-extensions">extensions</literal> section of your |
bos@580 | 276 <filename role="special">~/.hgrc</filename>, simply add a |
bos@559 | 277 one-line entry to enable the extension.</para> |
bos@580 | 278 <programlisting>[extensions] |
bos@580 | 279 extdiff =</programlisting> |
bos@584 | 280 <para id="x_524">This introduces a command named <command |
bos@559 | 281 role="hg-ext-extdiff">extdiff</command>, which by default uses |
bos@559 | 282 your system's <command>diff</command> command to generate a |
bos@559 | 283 unified diff in the same form as the built-in <command |
bos@567 | 284 role="hg-cmd">hg diff</command> command.</para> |
bos@567 | 285 |
bos@567 | 286 &interaction.extdiff.extdiff; |
bos@567 | 287 |
bos@584 | 288 <para id="x_525">The result won't be exactly the same as with the built-in |
bos@567 | 289 <command role="hg-cmd">hg diff</command> variations, because the |
bos@567 | 290 output of <command>diff</command> varies from one system to |
bos@567 | 291 another, even when passed the same options.</para> |
bos@559 | 292 |
bos@584 | 293 <para id="x_526">As the <quote><literal>making snapshot</literal></quote> |
bos@559 | 294 lines of output above imply, the <command |
bos@559 | 295 role="hg-ext-extdiff">extdiff</command> command works by |
bos@559 | 296 creating two snapshots of your source tree. The first snapshot |
bos@559 | 297 is of the source revision; the second, of the target revision or |
bos@559 | 298 working directory. The <command |
bos@559 | 299 role="hg-ext-extdiff">extdiff</command> command generates |
bos@559 | 300 these snapshots in a temporary directory, passes the name of |
bos@559 | 301 each directory to an external diff viewer, then deletes the |
bos@559 | 302 temporary directory. For efficiency, it only snapshots the |
bos@559 | 303 directories and files that have changed between the two |
bos@559 | 304 revisions.</para> |
bos@559 | 305 |
bos@584 | 306 <para id="x_527">Snapshot directory names have the same base name as your |
bos@559 | 307 repository. If your repository path is <filename |
bos@559 | 308 class="directory">/quux/bar/foo</filename>, then <filename |
bos@559 | 309 class="directory">foo</filename> will be the name of each |
bos@559 | 310 snapshot directory. Each snapshot directory name has its |
bos@559 | 311 changeset ID appended, if appropriate. If a snapshot is of |
bos@559 | 312 revision <literal>a631aca1083f</literal>, the directory will be |
bos@559 | 313 named <filename class="directory">foo.a631aca1083f</filename>. |
bos@559 | 314 A snapshot of the working directory won't have a changeset ID |
bos@559 | 315 appended, so it would just be <filename |
bos@559 | 316 class="directory">foo</filename> in this example. To see what |
bos@559 | 317 this looks like in practice, look again at the <command |
bos@559 | 318 role="hg-ext-extdiff">extdiff</command> example above. Notice |
bos@559 | 319 that the diff has the snapshot directory names embedded in its |
bos@559 | 320 header.</para> |
bos@559 | 321 |
bos@584 | 322 <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command |
bos@559 | 323 accepts two important options. The <option |
bos@559 | 324 role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option |
bos@559 | 325 lets you choose a program to view differences with, instead of |
bos@559 | 326 <command>diff</command>. With the <option |
bos@559 | 327 role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, |
bos@559 | 328 you can change the options that <command |
bos@559 | 329 role="hg-ext-extdiff">extdiff</command> passes to the program |
bos@559 | 330 (by default, these options are |
bos@559 | 331 <quote><literal>-Npru</literal></quote>, which only make sense |
bos@559 | 332 if you're running <command>diff</command>). In other respects, |
bos@559 | 333 the <command role="hg-ext-extdiff">extdiff</command> command |
bos@559 | 334 acts similarly to the built-in <command role="hg-cmd">hg |
bos@559 | 335 diff</command> command: you use the same option names, syntax, |
bos@559 | 336 and arguments to specify the revisions you want, the files you |
bos@559 | 337 want, and so on.</para> |
bos@559 | 338 |
bos@584 | 339 <para id="x_529">As an example, here's how to run the normal system |
bos@559 | 340 <command>diff</command> command, getting it to generate context |
bos@559 | 341 diffs (using the <option role="cmd-opt-diff">-c</option> option) |
bos@559 | 342 instead of unified diffs, and five lines of context instead of |
bos@559 | 343 the default three (passing <literal>5</literal> as the argument |
bos@567 | 344 to the <option role="cmd-opt-diff">-C</option> option).</para> |
bos@567 | 345 |
bos@567 | 346 &interaction.extdiff.extdiff-ctx; |
bos@559 | 347 |
bos@584 | 348 <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to |
bos@559 | 349 launch the <command>kdiff3</command> viewer.</para> |
bos@559 | 350 <programlisting>hg extdiff -p kdiff3 -o</programlisting> |
bos@559 | 351 |
bos@584 | 352 <para id="x_52b">If your diff viewing command can't deal with directories, |
bos@559 | 353 you can easily work around this with a little scripting. For an |
bos@559 | 354 example of such scripting in action with the <literal |
bos@559 | 355 role="hg-ext">mq</literal> extension and the |
bos@592 | 356 <command>interdiff</command> command, see <xref |
bos@559 | 357 linkend="mq-collab:tips:interdiff"/>.</para> |
bos@559 | 358 |
bos@559 | 359 <sect2> |
bos@559 | 360 <title>Defining command aliases</title> |
bos@559 | 361 |
bos@584 | 362 <para id="x_52c">It can be cumbersome to remember the options to both the |
bos@559 | 363 <command role="hg-ext-extdiff">extdiff</command> command and |
bos@559 | 364 the diff viewer you want to use, so the <literal |
bos@559 | 365 role="hg-ext">extdiff</literal> extension lets you define |
bos@559 | 366 <emphasis>new</emphasis> commands that will invoke your diff |
bos@559 | 367 viewer with exactly the right options.</para> |
bos@559 | 368 |
bos@584 | 369 <para id="x_52d">All you need to do is edit your <filename |
bos@580 | 370 role="special">~/.hgrc</filename>, and add a section named |
bos@580 | 371 <literal role="rc-extdiff">extdiff</literal>. Inside this |
bos@580 | 372 section, you can define multiple commands. Here's how to add |
bos@580 | 373 a <literal>kdiff3</literal> command. Once you've defined |
bos@580 | 374 this, you can type <quote><literal>hg kdiff3</literal></quote> |
bos@580 | 375 and the <literal role="hg-ext">extdiff</literal> extension |
bos@580 | 376 will run <command>kdiff3</command> for you.</para> |
bos@580 | 377 <programlisting>[extdiff] |
bos@580 | 378 cmd.kdiff3 =</programlisting> |
bos@584 | 379 <para id="x_52e">If you leave the right hand side of the definition empty, |
bos@559 | 380 as above, the <literal role="hg-ext">extdiff</literal> |
bos@559 | 381 extension uses the name of the command you defined as the name |
bos@559 | 382 of the external program to run. But these names don't have to |
bos@559 | 383 be the same. Here, we define a command named |
bos@559 | 384 <quote><literal>hg wibble</literal></quote>, which runs |
bos@559 | 385 <command>kdiff3</command>.</para> |
bos@580 | 386 <programlisting>[extdiff] |
bos@580 | 387 cmd.wibble = kdiff3</programlisting> |
bos@559 | 388 |
bos@584 | 389 <para id="x_52f">You can also specify the default options that you want to |
bos@559 | 390 invoke your diff viewing program with. The prefix to use is |
bos@559 | 391 <quote><literal>opts.</literal></quote>, followed by the name |
bos@559 | 392 of the command to which the options apply. This example |
bos@559 | 393 defines a <quote><literal>hg vimdiff</literal></quote> command |
bos@559 | 394 that runs the <command>vim</command> editor's |
bos@559 | 395 <literal>DirDiff</literal> extension.</para> |
bos@580 | 396 <programlisting>[extdiff] |
bos@580 | 397 cmd.vimdiff = vim |
bos@580 | 398 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> |
bos@559 | 399 |
bos@559 | 400 </sect2> |
bos@559 | 401 </sect1> |
bos@559 | 402 <sect1 id="sec:hgext:transplant"> |
bos@559 | 403 <title>Cherrypicking changes with the <literal |
bos@559 | 404 role="hg-ext">transplant</literal> extension</title> |
bos@559 | 405 |
bos@584 | 406 <para id="x_530">Need to have a long chat with Brendan about this.</para> |
bos@559 | 407 |
bos@559 | 408 </sect1> |
bos@559 | 409 <sect1 id="sec:hgext:patchbomb"> |
bos@559 | 410 <title>Send changes via email with the <literal |
bos@559 | 411 role="hg-ext">patchbomb</literal> extension</title> |
bos@559 | 412 |
bos@584 | 413 <para id="x_531">Many projects have a culture of <quote>change |
bos@559 | 414 review</quote>, in which people send their modifications to a |
bos@559 | 415 mailing list for others to read and comment on before they |
bos@559 | 416 commit the final version to a shared repository. Some projects |
bos@559 | 417 have people who act as gatekeepers; they apply changes from |
bos@559 | 418 other people to a repository to which those others don't have |
bos@559 | 419 access.</para> |
bos@559 | 420 |
bos@584 | 421 <para id="x_532">Mercurial makes it easy to send changes over email for |
bos@559 | 422 review or application, via its <literal |
bos@559 | 423 role="hg-ext">patchbomb</literal> extension. The extension is |
ori@561 | 424 so named because changes are formatted as patches, and it's usual |
bos@559 | 425 to send one changeset per email message. Sending a long series |
bos@559 | 426 of changes by email is thus much like <quote>bombing</quote> the |
bos@559 | 427 recipient's inbox, hence <quote>patchbomb</quote>.</para> |
bos@559 | 428 |
bos@584 | 429 <para id="x_533">As usual, the basic configuration of the <literal |
bos@559 | 430 role="hg-ext">patchbomb</literal> extension takes just one or |
bos@559 | 431 two lines in your <filename role="special"> |
bos@559 | 432 /.hgrc</filename>.</para> |
bos@580 | 433 <programlisting>[extensions] |
bos@580 | 434 patchbomb =</programlisting> |
bos@584 | 435 <para id="x_534">Once you've enabled the extension, you will have a new |
bos@559 | 436 command available, named <command |
bos@559 | 437 role="hg-ext-patchbomb">email</command>.</para> |
bos@559 | 438 |
bos@584 | 439 <para id="x_535">The safest and best way to invoke the <command |
bos@559 | 440 role="hg-ext-patchbomb">email</command> command is to |
bos@559 | 441 <emphasis>always</emphasis> run it first with the <option |
bos@559 | 442 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. |
bos@559 | 443 This will show you what the command <emphasis>would</emphasis> |
bos@559 | 444 send, without actually sending anything. Once you've had a |
bos@559 | 445 quick glance over the changes and verified that you are sending |
bos@559 | 446 the right ones, you can rerun the same command, with the <option |
bos@559 | 447 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option |
bos@559 | 448 removed.</para> |
bos@559 | 449 |
bos@584 | 450 <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command |
bos@559 | 451 accepts the same kind of revision syntax as every other |
bos@559 | 452 Mercurial command. For example, this command will send every |
bos@559 | 453 revision between 7 and <literal>tip</literal>, inclusive.</para> |
bos@559 | 454 <programlisting>hg email -n 7:tip</programlisting> |
bos@584 | 455 <para id="x_537">You can also specify a <emphasis>repository</emphasis> to |
bos@559 | 456 compare with. If you provide a repository but no revisions, the |
bos@559 | 457 <command role="hg-ext-patchbomb">email</command> command will |
bos@559 | 458 send all revisions in the local repository that are not present |
bos@559 | 459 in the remote repository. If you additionally specify revisions |
bos@559 | 460 or a branch name (the latter using the <option |
bos@559 | 461 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), |
bos@559 | 462 this will constrain the revisions sent.</para> |
bos@559 | 463 |
bos@584 | 464 <para id="x_538">It's perfectly safe to run the <command |
bos@559 | 465 role="hg-ext-patchbomb">email</command> command without the |
bos@559 | 466 names of the people you want to send to: if you do this, it will |
bos@559 | 467 just prompt you for those values interactively. (If you're |
bos@559 | 468 using a Linux or Unix-like system, you should have enhanced |
bos@559 | 469 <literal>readline</literal>-style editing capabilities when |
bos@559 | 470 entering those headers, too, which is useful.)</para> |
bos@559 | 471 |
bos@584 | 472 <para id="x_539">When you are sending just one revision, the <command |
bos@559 | 473 role="hg-ext-patchbomb">email</command> command will by |
bos@559 | 474 default use the first line of the changeset description as the |
bos@559 | 475 subject of the single email message it sends.</para> |
bos@559 | 476 |
bos@584 | 477 <para id="x_53a">If you send multiple revisions, the <command |
bos@559 | 478 role="hg-ext-patchbomb">email</command> command will usually |
bos@559 | 479 send one message per changeset. It will preface the series with |
bos@559 | 480 an introductory message, in which you should describe the |
bos@559 | 481 purpose of the series of changes you're sending.</para> |
bos@559 | 482 |
bos@559 | 483 <sect2> |
bos@672 | 484 <title>Changing the behavior of patchbombs</title> |
bos@559 | 485 |
bos@584 | 486 <para id="x_53b">Not every project has exactly the same conventions for |
bos@559 | 487 sending changes in email; the <literal |
bos@559 | 488 role="hg-ext">patchbomb</literal> extension tries to |
bos@559 | 489 accommodate a number of variations through command line |
bos@559 | 490 options.</para> |
bos@559 | 491 <itemizedlist> |
bos@584 | 492 <listitem><para id="x_53c">You can write a subject for the introductory |
bos@559 | 493 message on the command line using the <option |
bos@559 | 494 role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> |
bos@559 | 495 option. This takes one argument, the text of the subject |
bos@559 | 496 to use.</para> |
bos@559 | 497 </listitem> |
bos@584 | 498 <listitem><para id="x_53d">To change the email address from which the |
bos@559 | 499 messages originate, use the <option |
bos@559 | 500 role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> |
bos@559 | 501 option. This takes one argument, the email address to |
bos@559 | 502 use.</para> |
bos@559 | 503 </listitem> |
bos@672 | 504 <listitem><para id="x_53e">The default behavior is to send unified diffs |
bos@592 | 505 (see <xref linkend="sec:mq:patch"/> for a |
bos@559 | 506 description of the |
bos@559 | 507 format), one per message. You can send a binary bundle |
bos@559 | 508 instead with the <option |
bos@559 | 509 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> |
bos@559 | 510 option.</para> |
bos@559 | 511 </listitem> |
bos@584 | 512 <listitem><para id="x_53f">Unified diffs are normally prefaced with a |
bos@559 | 513 metadata header. You can omit this, and send unadorned |
bos@559 | 514 diffs, with the <option |
bos@559 | 515 role="hg-ext-patchbomb-cmd-email-opt">hg |
bos@559 | 516 --plain</option> option.</para> |
bos@559 | 517 </listitem> |
bos@584 | 518 <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, |
bos@559 | 519 in the same body part as the description of a patch. This |
bos@559 | 520 makes it easiest for the largest number of readers to |
bos@559 | 521 quote and respond to parts of a diff, as some mail clients |
bos@559 | 522 will only quote the first MIME body part in a message. If |
bos@559 | 523 you'd prefer to send the description and the diff in |
bos@559 | 524 separate body parts, use the <option |
bos@559 | 525 role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> |
bos@559 | 526 option.</para> |
bos@559 | 527 </listitem> |
bos@584 | 528 <listitem><para id="x_541">Instead of sending mail messages, you can |
bos@559 | 529 write them to an <literal>mbox</literal>-format mail |
bos@559 | 530 folder using the <option |
bos@559 | 531 role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> |
bos@559 | 532 option. That option takes one argument, the name of the |
bos@559 | 533 file to write to.</para> |
bos@559 | 534 </listitem> |
bos@584 | 535 <listitem><para id="x_542">If you would like to add a |
bos@559 | 536 <command>diffstat</command>-format summary to each patch, |
bos@559 | 537 and one to the introductory message, use the <option |
bos@559 | 538 role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> |
bos@559 | 539 option. The <command>diffstat</command> command displays |
bos@559 | 540 a table containing the name of each file patched, the |
bos@559 | 541 number of lines affected, and a histogram showing how much |
bos@559 | 542 each file is modified. This gives readers a qualitative |
bos@559 | 543 glance at how complex a patch is.</para> |
bos@559 | 544 </listitem></itemizedlist> |
bos@559 | 545 |
bos@559 | 546 </sect2> |
bos@559 | 547 </sect1> |
bos@559 | 548 </chapter> |
bos@559 | 549 |
bos@559 | 550 <!-- |
bos@559 | 551 local variables: |
bos@559 | 552 sgml-parent-document: ("00book.xml" "book" "chapter") |
bos@559 | 553 end: |
bos@559 | 554 --> |