hgbook

annotate es/hgext.tex @ 365:5c676825e7a1

find changesets by author, revision, files, or words in the commit message
corrected typo and grammar error
author Javier Rojas <jerojasro@devnull.li>
date Sat Oct 25 15:52:56 2008 -0500 (2008-10-25)
parents 04c08ad7e92e
children aeda195f54a6
rev   line source
jerojasro@336 1 \chapter{Adding functionality with extensions}
jerojasro@336 2 \label{chap:hgext}
jerojasro@336 3
jerojasro@336 4 While the core of Mercurial is quite complete from a functionality
jerojasro@336 5 standpoint, it's deliberately shorn of fancy features. This approach
jerojasro@336 6 of preserving simplicity keeps the software easy to deal with for both
jerojasro@336 7 maintainers and users.
jerojasro@336 8
jerojasro@336 9 However, Mercurial doesn't box you in with an inflexible command set:
jerojasro@336 10 you can add features to it as \emph{extensions} (sometimes known as
jerojasro@336 11 \emph{plugins}). We've already discussed a few of these extensions in
jerojasro@336 12 earlier chapters.
jerojasro@336 13 \begin{itemize}
jerojasro@336 14 \item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch}
jerojasro@336 15 extension; this combines pulling new changes and merging them with
jerojasro@336 16 local changes into a single command, \hgxcmd{fetch}{fetch}.
jerojasro@336 17 \item In chapter~\ref{chap:hook}, we covered several extensions that
jerojasro@336 18 are useful for hook-related functionality: \hgext{acl} adds access
jerojasro@336 19 control lists; \hgext{bugzilla} adds integration with the Bugzilla
jerojasro@336 20 bug tracking system; and \hgext{notify} sends notification emails on
jerojasro@336 21 new changes.
jerojasro@336 22 \item The Mercurial Queues patch management extension is so invaluable
jerojasro@336 23 that it merits two chapters and an appendix all to itself.
jerojasro@336 24 Chapter~\ref{chap:mq} covers the basics;
jerojasro@336 25 chapter~\ref{chap:mq-collab} discusses advanced topics; and
jerojasro@336 26 appendix~\ref{chap:mqref} goes into detail on each command.
jerojasro@336 27 \end{itemize}
jerojasro@336 28
jerojasro@336 29 In this chapter, we'll cover some of the other extensions that are
jerojasro@336 30 available for Mercurial, and briefly touch on some of the machinery
jerojasro@336 31 you'll need to know about if you want to write an extension of your
jerojasro@336 32 own.
jerojasro@336 33 \begin{itemize}
jerojasro@336 34 \item In section~\ref{sec:hgext:inotify}, we'll discuss the
jerojasro@336 35 possibility of \emph{huge} performance improvements using the
jerojasro@336 36 \hgext{inotify} extension.
jerojasro@336 37 \end{itemize}
jerojasro@336 38
jerojasro@336 39 \section{Improve performance with the \hgext{inotify} extension}
jerojasro@336 40 \label{sec:hgext:inotify}
jerojasro@336 41
jerojasro@336 42 Are you interested in having some of the most common Mercurial
jerojasro@336 43 operations run as much as a hundred times faster? Read on!
jerojasro@336 44
jerojasro@336 45 Mercurial has great performance under normal circumstances. For
jerojasro@336 46 example, when you run the \hgcmd{status} command, Mercurial has to
jerojasro@336 47 scan almost every directory and file in your repository so that it can
jerojasro@336 48 display file status. Many other Mercurial commands need to do the
jerojasro@336 49 same work behind the scenes; for example, the \hgcmd{diff} command
jerojasro@336 50 uses the status machinery to avoid doing an expensive comparison
jerojasro@336 51 operation on files that obviously haven't changed.
jerojasro@336 52
jerojasro@336 53 Because obtaining file status is crucial to good performance, the
jerojasro@336 54 authors of Mercurial have optimised this code to within an inch of its
jerojasro@336 55 life. However, there's no avoiding the fact that when you run
jerojasro@336 56 \hgcmd{status}, Mercurial is going to have to perform at least one
jerojasro@336 57 expensive system call for each managed file to determine whether it's
jerojasro@336 58 changed since the last time Mercurial checked. For a sufficiently
jerojasro@336 59 large repository, this can take a long time.
jerojasro@336 60
jerojasro@336 61 To put a number on the magnitude of this effect, I created a
jerojasro@336 62 repository containing 150,000 managed files. I timed \hgcmd{status}
jerojasro@336 63 as taking ten seconds to run, even when \emph{none} of those files had
jerojasro@336 64 been modified.
jerojasro@336 65
jerojasro@336 66 Many modern operating systems contain a file notification facility.
jerojasro@336 67 If a program signs up to an appropriate service, the operating system
jerojasro@336 68 will notify it every time a file of interest is created, modified, or
jerojasro@336 69 deleted. On Linux systems, the kernel component that does this is
jerojasro@336 70 called \texttt{inotify}.
jerojasro@336 71
jerojasro@336 72 Mercurial's \hgext{inotify} extension talks to the kernel's
jerojasro@336 73 \texttt{inotify} component to optimise \hgcmd{status} commands. The
jerojasro@336 74 extension has two components. A daemon sits in the background and
jerojasro@336 75 receives notifications from the \texttt{inotify} subsystem. It also
jerojasro@336 76 listens for connections from a regular Mercurial command. The
jerojasro@336 77 extension modifies Mercurial's behaviour so that instead of scanning
jerojasro@336 78 the filesystem, it queries the daemon. Since the daemon has perfect
jerojasro@336 79 information about the state of the repository, it can respond with a
jerojasro@336 80 result instantaneously, avoiding the need to scan every directory and
jerojasro@336 81 file in the repository.
jerojasro@336 82
jerojasro@336 83 Recall the ten seconds that I measured plain Mercurial as taking to
jerojasro@336 84 run \hgcmd{status} on a 150,000 file repository. With the
jerojasro@336 85 \hgext{inotify} extension enabled, the time dropped to 0.1~seconds, a
jerojasro@336 86 factor of \emph{one hundred} faster.
jerojasro@336 87
jerojasro@336 88 Before we continue, please pay attention to some caveats.
jerojasro@336 89 \begin{itemize}
jerojasro@336 90 \item The \hgext{inotify} extension is Linux-specific. Because it
jerojasro@336 91 interfaces directly to the Linux kernel's \texttt{inotify}
jerojasro@336 92 subsystem, it does not work on other operating systems.
jerojasro@336 93 \item It should work on any Linux distribution that was released after
jerojasro@336 94 early~2005. Older distributions are likely to have a kernel that
jerojasro@336 95 lacks \texttt{inotify}, or a version of \texttt{glibc} that does not
jerojasro@336 96 have the necessary interfacing support.
jerojasro@336 97 \item Not all filesystems are suitable for use with the
jerojasro@336 98 \hgext{inotify} extension. Network filesystems such as NFS are a
jerojasro@336 99 non-starter, for example, particularly if you're running Mercurial
jerojasro@336 100 on several systems, all mounting the same network filesystem. The
jerojasro@336 101 kernel's \texttt{inotify} system has no way of knowing about changes
jerojasro@336 102 made on another system. Most local filesystems (e.g.~ext3, XFS,
jerojasro@336 103 ReiserFS) should work fine.
jerojasro@336 104 \end{itemize}
jerojasro@336 105
jerojasro@336 106 The \hgext{inotify} extension is not yet shipped with Mercurial as of
jerojasro@336 107 May~2007, so it's a little more involved to set up than other
jerojasro@336 108 extensions. But the performance improvement is worth it!
jerojasro@336 109
jerojasro@336 110 The extension currently comes in two parts: a set of patches to the
jerojasro@336 111 Mercurial source code, and a library of Python bindings to the
jerojasro@336 112 \texttt{inotify} subsystem.
jerojasro@336 113 \begin{note}
jerojasro@336 114 There are \emph{two} Python \texttt{inotify} binding libraries. One
jerojasro@336 115 of them is called \texttt{pyinotify}, and is packaged by some Linux
jerojasro@336 116 distributions as \texttt{python-inotify}. This is \emph{not} the
jerojasro@336 117 one you'll need, as it is too buggy and inefficient to be practical.
jerojasro@336 118 \end{note}
jerojasro@336 119 To get going, it's best to already have a functioning copy of
jerojasro@336 120 Mercurial installed.
jerojasro@336 121 \begin{note}
jerojasro@336 122 If you follow the instructions below, you'll be \emph{replacing} and
jerojasro@336 123 overwriting any existing installation of Mercurial that you might
jerojasro@336 124 already have, using the latest ``bleeding edge'' Mercurial code.
jerojasro@336 125 Don't say you weren't warned!
jerojasro@336 126 \end{note}
jerojasro@336 127 \begin{enumerate}
jerojasro@336 128 \item Clone the Python \texttt{inotify} binding repository. Build and
jerojasro@336 129 install it.
jerojasro@336 130 \begin{codesample4}
jerojasro@336 131 hg clone http://hg.kublai.com/python/inotify
jerojasro@336 132 cd inotify
jerojasro@336 133 python setup.py build --force
jerojasro@336 134 sudo python setup.py install --skip-build
jerojasro@336 135 \end{codesample4}
jerojasro@336 136 \item Clone the \dirname{crew} Mercurial repository. Clone the
jerojasro@336 137 \hgext{inotify} patch repository so that Mercurial Queues will be
jerojasro@336 138 able to apply patches to your cope of the \dirname{crew} repository.
jerojasro@336 139 \begin{codesample4}
jerojasro@336 140 hg clone http://hg.intevation.org/mercurial/crew
jerojasro@336 141 hg clone crew inotify
jerojasro@336 142 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
jerojasro@336 143 \end{codesample4}
jerojasro@336 144 \item Make sure that you have the Mercurial Queues extension,
jerojasro@336 145 \hgext{mq}, enabled. If you've never used MQ, read
jerojasro@336 146 section~\ref{sec:mq:start} to get started quickly.
jerojasro@336 147 \item Go into the \dirname{inotify} repo, and apply all of the
jerojasro@336 148 \hgext{inotify} patches using the \hgxopt{mq}{qpush}{-a} option to
jerojasro@336 149 the \hgxcmd{mq}{qpush} command.
jerojasro@336 150 \begin{codesample4}
jerojasro@336 151 cd inotify
jerojasro@336 152 hg qpush -a
jerojasro@336 153 \end{codesample4}
jerojasro@336 154 If you get an error message from \hgxcmd{mq}{qpush}, you should not
jerojasro@336 155 continue. Instead, ask for help.
jerojasro@336 156 \item Build and install the patched version of Mercurial.
jerojasro@336 157 \begin{codesample4}
jerojasro@336 158 python setup.py build --force
jerojasro@336 159 sudo python setup.py install --skip-build
jerojasro@336 160 \end{codesample4}
jerojasro@336 161 \end{enumerate}
jerojasro@336 162 Once you've build a suitably patched version of Mercurial, all you
jerojasro@336 163 need to do to enable the \hgext{inotify} extension is add an entry to
jerojasro@336 164 your \hgrc.
jerojasro@336 165 \begin{codesample2}
jerojasro@336 166 [extensions]
jerojasro@336 167 inotify =
jerojasro@336 168 \end{codesample2}
jerojasro@336 169 When the \hgext{inotify} extension is enabled, Mercurial will
jerojasro@336 170 automatically and transparently start the status daemon the first time
jerojasro@336 171 you run a command that needs status in a repository. It runs one
jerojasro@336 172 status daemon per repository.
jerojasro@336 173
jerojasro@336 174 The status daemon is started silently, and runs in the background. If
jerojasro@336 175 you look at a list of running processes after you've enabled the
jerojasro@336 176 \hgext{inotify} extension and run a few commands in different
jerojasro@336 177 repositories, you'll thus see a few \texttt{hg} processes sitting
jerojasro@336 178 around, waiting for updates from the kernel and queries from
jerojasro@336 179 Mercurial.
jerojasro@336 180
jerojasro@336 181 The first time you run a Mercurial command in a repository when you
jerojasro@336 182 have the \hgext{inotify} extension enabled, it will run with about the
jerojasro@336 183 same performance as a normal Mercurial command. This is because the
jerojasro@336 184 status daemon needs to perform a normal status scan so that it has a
jerojasro@336 185 baseline against which to apply later updates from the kernel.
jerojasro@336 186 However, \emph{every} subsequent command that does any kind of status
jerojasro@336 187 check should be noticeably faster on repositories of even fairly
jerojasro@336 188 modest size. Better yet, the bigger your repository is, the greater a
jerojasro@336 189 performance advantage you'll see. The \hgext{inotify} daemon makes
jerojasro@336 190 status operations almost instantaneous on repositories of all sizes!
jerojasro@336 191
jerojasro@336 192 If you like, you can manually start a status daemon using the
jerojasro@336 193 \hgxcmd{inotify}{inserve} command. This gives you slightly finer
jerojasro@336 194 control over how the daemon ought to run. This command will of course
jerojasro@336 195 only be available when the \hgext{inotify} extension is enabled.
jerojasro@336 196
jerojasro@336 197 When you're using the \hgext{inotify} extension, you should notice
jerojasro@336 198 \emph{no difference at all} in Mercurial's behaviour, with the sole
jerojasro@336 199 exception of status-related commands running a whole lot faster than
jerojasro@336 200 they used to. You should specifically expect that commands will not
jerojasro@336 201 print different output; neither should they give different results.
jerojasro@336 202 If either of these situations occurs, please report a bug.
jerojasro@336 203
jerojasro@336 204 \section{Flexible diff support with the \hgext{extdiff} extension}
jerojasro@336 205 \label{sec:hgext:extdiff}
jerojasro@336 206
jerojasro@336 207 Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
jerojasro@336 208 diffs.
jerojasro@336 209 \interaction{extdiff.diff}
jerojasro@336 210 If you would like to use an external tool to display modifications,
jerojasro@336 211 you'll want to use the \hgext{extdiff} extension. This will let you
jerojasro@336 212 use, for example, a graphical diff tool.
jerojasro@336 213
jerojasro@336 214 The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
jerojasro@336 215 to set up. In the \rcsection{extensions} section of your \hgrc,
jerojasro@336 216 simply add a one-line entry to enable the extension.
jerojasro@336 217 \begin{codesample2}
jerojasro@336 218 [extensions]
jerojasro@336 219 extdiff =
jerojasro@336 220 \end{codesample2}
jerojasro@336 221 This introduces a command named \hgxcmd{extdiff}{extdiff}, which by
jerojasro@336 222 default uses your system's \command{diff} command to generate a
jerojasro@336 223 unified diff in the same form as the built-in \hgcmd{diff} command.
jerojasro@336 224 \interaction{extdiff.extdiff}
jerojasro@336 225 The result won't be exactly the same as with the built-in \hgcmd{diff}
jerojasro@336 226 variations, because the output of \command{diff} varies from one
jerojasro@336 227 system to another, even when passed the same options.
jerojasro@336 228
jerojasro@336 229 As the ``\texttt{making snapshot}'' lines of output above imply, the
jerojasro@336 230 \hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
jerojasro@336 231 your source tree. The first snapshot is of the source revision; the
jerojasro@336 232 second, of the target revision or working directory. The
jerojasro@336 233 \hgxcmd{extdiff}{extdiff} command generates these snapshots in a
jerojasro@336 234 temporary directory, passes the name of each directory to an external
jerojasro@336 235 diff viewer, then deletes the temporary directory. For efficiency, it
jerojasro@336 236 only snapshots the directories and files that have changed between the
jerojasro@336 237 two revisions.
jerojasro@336 238
jerojasro@336 239 Snapshot directory names have the same base name as your repository.
jerojasro@336 240 If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
jerojasro@336 241 will be the name of each snapshot directory. Each snapshot directory
jerojasro@336 242 name has its changeset ID appended, if appropriate. If a snapshot is
jerojasro@336 243 of revision \texttt{a631aca1083f}, the directory will be named
jerojasro@336 244 \dirname{foo.a631aca1083f}. A snapshot of the working directory won't
jerojasro@336 245 have a changeset ID appended, so it would just be \dirname{foo} in
jerojasro@336 246 this example. To see what this looks like in practice, look again at
jerojasro@336 247 the \hgxcmd{extdiff}{extdiff} example above. Notice that the diff has
jerojasro@336 248 the snapshot directory names embedded in its header.
jerojasro@336 249
jerojasro@336 250 The \hgxcmd{extdiff}{extdiff} command accepts two important options.
jerojasro@336 251 The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
jerojasro@336 252 view differences with, instead of \command{diff}. With the
jerojasro@336 253 \hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
jerojasro@336 254 \hgxcmd{extdiff}{extdiff} passes to the program (by default, these
jerojasro@336 255 options are ``\texttt{-Npru}'', which only make sense if you're
jerojasro@336 256 running \command{diff}). In other respects, the
jerojasro@336 257 \hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
jerojasro@336 258 \hgcmd{diff} command: you use the same option names, syntax, and
jerojasro@336 259 arguments to specify the revisions you want, the files you want, and
jerojasro@336 260 so on.
jerojasro@336 261
jerojasro@336 262 As an example, here's how to run the normal system \command{diff}
jerojasro@336 263 command, getting it to generate context diffs (using the
jerojasro@336 264 \cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
jerojasro@336 265 context instead of the default three (passing \texttt{5} as the
jerojasro@336 266 argument to the \cmdopt{diff}{-C} option).
jerojasro@336 267 \interaction{extdiff.extdiff-ctx}
jerojasro@336 268
jerojasro@336 269 Launching a visual diff tool is just as easy. Here's how to launch
jerojasro@336 270 the \command{kdiff3} viewer.
jerojasro@336 271 \begin{codesample2}
jerojasro@336 272 hg extdiff -p kdiff3 -o ''
jerojasro@336 273 \end{codesample2}
jerojasro@336 274
jerojasro@336 275 If your diff viewing command can't deal with directories, you can
jerojasro@336 276 easily work around this with a little scripting. For an example of
jerojasro@336 277 such scripting in action with the \hgext{mq} extension and the
jerojasro@336 278 \command{interdiff} command, see
jerojasro@336 279 section~\ref{mq-collab:tips:interdiff}.
jerojasro@336 280
jerojasro@336 281 \subsection{Defining command aliases}
jerojasro@336 282
jerojasro@336 283 It can be cumbersome to remember the options to both the
jerojasro@336 284 \hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use,
jerojasro@336 285 so the \hgext{extdiff} extension lets you define \emph{new} commands
jerojasro@336 286 that will invoke your diff viewer with exactly the right options.
jerojasro@336 287
jerojasro@336 288 All you need to do is edit your \hgrc, and add a section named
jerojasro@336 289 \rcsection{extdiff}. Inside this section, you can define multiple
jerojasro@336 290 commands. Here's how to add a \texttt{kdiff3} command. Once you've
jerojasro@336 291 defined this, you can type ``\texttt{hg kdiff3}'' and the
jerojasro@336 292 \hgext{extdiff} extension will run \command{kdiff3} for you.
jerojasro@336 293 \begin{codesample2}
jerojasro@336 294 [extdiff]
jerojasro@336 295 cmd.kdiff3 =
jerojasro@336 296 \end{codesample2}
jerojasro@336 297 If you leave the right hand side of the definition empty, as above,
jerojasro@336 298 the \hgext{extdiff} extension uses the name of the command you defined
jerojasro@336 299 as the name of the external program to run. But these names don't
jerojasro@336 300 have to be the same. Here, we define a command named ``\texttt{hg
jerojasro@336 301 wibble}'', which runs \command{kdiff3}.
jerojasro@336 302 \begin{codesample2}
jerojasro@336 303 [extdiff]
jerojasro@336 304 cmd.wibble = kdiff3
jerojasro@336 305 \end{codesample2}
jerojasro@336 306
jerojasro@336 307 You can also specify the default options that you want to invoke your
jerojasro@336 308 diff viewing program with. The prefix to use is ``\texttt{opts.}'',
jerojasro@336 309 followed by the name of the command to which the options apply. This
jerojasro@336 310 example defines a ``\texttt{hg vimdiff}'' command that runs the
jerojasro@336 311 \command{vim} editor's \texttt{DirDiff} extension.
jerojasro@336 312 \begin{codesample2}
jerojasro@336 313 [extdiff]
jerojasro@336 314 cmd.vimdiff = vim
jerojasro@336 315 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
jerojasro@336 316 \end{codesample2}
jerojasro@336 317
jerojasro@336 318 \section{Cherrypicking changes with the \hgext{transplant} extension}
jerojasro@336 319 \label{sec:hgext:transplant}
jerojasro@336 320
jerojasro@336 321 Need to have a long chat with Brendan about this.
jerojasro@336 322
jerojasro@336 323 \section{Send changes via email with the \hgext{patchbomb} extension}
jerojasro@336 324 \label{sec:hgext:patchbomb}
jerojasro@336 325
jerojasro@336 326 Many projects have a culture of ``change review'', in which people
jerojasro@336 327 send their modifications to a mailing list for others to read and
jerojasro@336 328 comment on before they commit the final version to a shared
jerojasro@336 329 repository. Some projects have people who act as gatekeepers; they
jerojasro@336 330 apply changes from other people to a repository to which those others
jerojasro@336 331 don't have access.
jerojasro@336 332
jerojasro@336 333 Mercurial makes it easy to send changes over email for review or
jerojasro@336 334 application, via its \hgext{patchbomb} extension. The extension is so
jerojasro@336 335 namd because changes are formatted as patches, and it's usual to send
jerojasro@336 336 one changeset per email message. Sending a long series of changes by
jerojasro@336 337 email is thus much like ``bombing'' the recipient's inbox, hence
jerojasro@336 338 ``patchbomb''.
jerojasro@336 339
jerojasro@336 340 As usual, the basic configuration of the \hgext{patchbomb} extension
jerojasro@336 341 takes just one or two lines in your \hgrc.
jerojasro@336 342 \begin{codesample2}
jerojasro@336 343 [extensions]
jerojasro@336 344 patchbomb =
jerojasro@336 345 \end{codesample2}
jerojasro@336 346 Once you've enabled the extension, you will have a new command
jerojasro@336 347 available, named \hgxcmd{patchbomb}{email}.
jerojasro@336 348
jerojasro@336 349 The safest and best way to invoke the \hgxcmd{patchbomb}{email}
jerojasro@336 350 command is to \emph{always} run it first with the
jerojasro@336 351 \hgxopt{patchbomb}{email}{-n} option. This will show you what the
jerojasro@336 352 command \emph{would} send, without actually sending anything. Once
jerojasro@336 353 you've had a quick glance over the changes and verified that you are
jerojasro@336 354 sending the right ones, you can rerun the same command, with the
jerojasro@336 355 \hgxopt{patchbomb}{email}{-n} option removed.
jerojasro@336 356
jerojasro@336 357 The \hgxcmd{patchbomb}{email} command accepts the same kind of
jerojasro@336 358 revision syntax as every other Mercurial command. For example, this
jerojasro@336 359 command will send every revision between 7 and \texttt{tip},
jerojasro@336 360 inclusive.
jerojasro@336 361 \begin{codesample2}
jerojasro@336 362 hg email -n 7:tip
jerojasro@336 363 \end{codesample2}
jerojasro@336 364 You can also specify a \emph{repository} to compare with. If you
jerojasro@336 365 provide a repository but no revisions, the \hgxcmd{patchbomb}{email}
jerojasro@336 366 command will send all revisions in the local repository that are not
jerojasro@336 367 present in the remote repository. If you additionally specify
jerojasro@336 368 revisions or a branch name (the latter using the
jerojasro@336 369 \hgxopt{patchbomb}{email}{-b} option), this will constrain the
jerojasro@336 370 revisions sent.
jerojasro@336 371
jerojasro@336 372 It's perfectly safe to run the \hgxcmd{patchbomb}{email} command
jerojasro@336 373 without the names of the people you want to send to: if you do this,
jerojasro@336 374 it will just prompt you for those values interactively. (If you're
jerojasro@336 375 using a Linux or Unix-like system, you should have enhanced
jerojasro@336 376 \texttt{readline}-style editing capabilities when entering those
jerojasro@336 377 headers, too, which is useful.)
jerojasro@336 378
jerojasro@336 379 When you are sending just one revision, the \hgxcmd{patchbomb}{email}
jerojasro@336 380 command will by default use the first line of the changeset
jerojasro@336 381 description as the subject of the single email message it sends.
jerojasro@336 382
jerojasro@336 383 If you send multiple revisions, the \hgxcmd{patchbomb}{email} command
jerojasro@336 384 will usually send one message per changeset. It will preface the
jerojasro@336 385 series with an introductory message, in which you should describe the
jerojasro@336 386 purpose of the series of changes you're sending.
jerojasro@336 387
jerojasro@336 388 \subsection{Changing the behaviour of patchbombs}
jerojasro@336 389
jerojasro@336 390 Not every project has exactly the same conventions for sending changes
jerojasro@336 391 in email; the \hgext{patchbomb} extension tries to accommodate a
jerojasro@336 392 number of variations through command line options.
jerojasro@336 393 \begin{itemize}
jerojasro@336 394 \item You can write a subject for the introductory message on the
jerojasro@336 395 command line using the \hgxopt{patchbomb}{email}{-s} option. This
jerojasro@336 396 takes one argument, the text of the subject to use.
jerojasro@336 397 \item To change the email address from which the messages originate,
jerojasro@336 398 use the \hgxopt{patchbomb}{email}{-f} option. This takes one
jerojasro@336 399 argument, the email address to use.
jerojasro@336 400 \item The default behaviour is to send unified diffs (see
jerojasro@336 401 section~\ref{sec:mq:patch} for a description of the format), one per
jerojasro@336 402 message. You can send a binary bundle instead with the
jerojasro@336 403 \hgxopt{patchbomb}{email}{-b} option.
jerojasro@336 404 \item Unified diffs are normally prefaced with a metadata header. You
jerojasro@336 405 can omit this, and send unadorned diffs, with the
jerojasro@336 406 \hgxopt{patchbomb}{email}{--plain} option.
jerojasro@336 407 \item Diffs are normally sent ``inline'', in the same body part as the
jerojasro@336 408 description of a patch. This makes it easiest for the largest
jerojasro@336 409 number of readers to quote and respond to parts of a diff, as some
jerojasro@336 410 mail clients will only quote the first MIME body part in a message.
jerojasro@336 411 If you'd prefer to send the description and the diff in separate
jerojasro@336 412 body parts, use the \hgxopt{patchbomb}{email}{-a} option.
jerojasro@336 413 \item Instead of sending mail messages, you can write them to an
jerojasro@336 414 \texttt{mbox}-format mail folder using the
jerojasro@336 415 \hgxopt{patchbomb}{email}{-m} option. That option takes one
jerojasro@336 416 argument, the name of the file to write to.
jerojasro@336 417 \item If you would like to add a \command{diffstat}-format summary to
jerojasro@336 418 each patch, and one to the introductory message, use the
jerojasro@336 419 \hgxopt{patchbomb}{email}{-d} option. The \command{diffstat}
jerojasro@336 420 command displays a table containing the name of each file patched,
jerojasro@336 421 the number of lines affected, and a histogram showing how much each
jerojasro@336 422 file is modified. This gives readers a qualitative glance at how
jerojasro@336 423 complex a patch is.
jerojasro@336 424 \end{itemize}
jerojasro@336 425
jerojasro@336 426 %%% Local Variables:
jerojasro@336 427 %%% mode: latex
jerojasro@336 428 %%% TeX-master: "00book"
jerojasro@336 429 %%% End: