1.1 --- a/en/examples/bisect.commits.out	Sat Oct 18 14:35:43 2008 -0500
     1.2 +++ b/en/examples/bisect.commits.out	Sat Oct 18 15:44:41 2008 -0500
     1.3 @@ -8,38 +8,3 @@
     1.4  
     1.5  
     1.6  
     1.7 -
     1.8 -
     1.9 -
    1.10 -
    1.11 -
    1.12 -
    1.13 -
    1.14 -
    1.15 -
    1.16 -
    1.17 -
    1.18 -
    1.19 -
    1.20 -
    1.21 -
    1.22 -
    1.23 -
    1.24 -
    1.25 -
    1.26 -
    1.27 -
    1.28 -
    1.29 -
    1.30 -
    1.31 -
    1.32 -
    1.33 -
    1.34 -
    1.35 -
    1.36 -
    1.37 -
    1.38 -
    1.39 -
    1.40 -
    1.41 -

     2.1 --- a/en/examples/bisect.help.out	Sat Oct 18 14:35:43 2008 -0500
     2.2 +++ b/en/examples/bisect.help.out	Sat Oct 18 15:44:41 2008 -0500
     2.3 @@ -21,4 +21,3 @@
     2.4  
     2.5  
     2.6  
     2.7 -

     3.1 --- a/en/examples/bisect.init.out	Sat Oct 18 14:35:43 2008 -0500
     3.2 +++ b/en/examples/bisect.init.out	Sat Oct 18 15:44:41 2008 -0500
     3.3 @@ -1,3 +1,2 @@
     3.4  
     3.5  
     3.6 -

     4.1 --- a/en/examples/bisect.search.bad-init.out	Sat Oct 18 14:35:43 2008 -0500
     4.2 +++ b/en/examples/bisect.search.bad-init.out	Sat Oct 18 15:44:41 2008 -0500
     4.3 @@ -1,2 +1,1 @@
     4.4  
     4.5 -

     5.1 --- a/en/examples/bisect.search.good-init.out	Sat Oct 18 14:35:43 2008 -0500
     5.2 +++ b/en/examples/bisect.search.good-init.out	Sat Oct 18 15:44:41 2008 -0500
     5.3 @@ -1,4 +1,3 @@
     5.4  
     5.5  
     5.6  
     5.7 -

     6.1 --- a/en/examples/bisect.search.init.out	Sat Oct 18 14:35:43 2008 -0500
     6.2 +++ b/en/examples/bisect.search.init.out	Sat Oct 18 15:44:41 2008 -0500
     6.3 @@ -3,23 +3,3 @@
     6.4  
     6.5  
     6.6  
     6.7 -
     6.8 -
     6.9 -
    6.10 -
    6.11 -
    6.12 -
    6.13 -
    6.14 -
    6.15 -
    6.16 -
    6.17 -
    6.18 -
    6.19 -
    6.20 -
    6.21 -
    6.22 -
    6.23 -
    6.24 -
    6.25 -
    6.26 -

     7.1 --- a/en/examples/bisect.search.reset.out	Sat Oct 18 14:35:43 2008 -0500
     7.2 +++ b/en/examples/bisect.search.reset.out	Sat Oct 18 15:44:41 2008 -0500
     7.3 @@ -1,2 +1,1 @@
     7.4  
     7.5 -

     8.1 --- a/en/examples/bisect.search.rest.out	Sat Oct 18 14:35:43 2008 -0500
     8.2 +++ b/en/examples/bisect.search.rest.out	Sat Oct 18 15:44:41 2008 -0500
     8.3 @@ -14,6 +14,3 @@
     8.4  
     8.5  
     8.6  
     8.7 -
     8.8 -
     8.9 -

     9.1 --- a/en/examples/bisect.search.step1.out	Sat Oct 18 14:35:43 2008 -0500
     9.2 +++ b/en/examples/bisect.search.step1.out	Sat Oct 18 15:44:41 2008 -0500
     9.3 @@ -9,4 +9,3 @@
     9.4  
     9.5  
     9.6  
     9.7 -

    10.1 --- a/en/examples/bisect.search.step2.out	Sat Oct 18 14:35:43 2008 -0500
    10.2 +++ b/en/examples/bisect.search.step2.out	Sat Oct 18 15:44:41 2008 -0500
    10.3 @@ -2,4 +2,3 @@
    10.4  
    10.5  
    10.6  
    10.7 -

    11.1 --- a/en/examples/branch-repo.bugfix.out	Sat Oct 18 14:35:43 2008 -0500
    11.2 +++ b/en/examples/branch-repo.bugfix.out	Sat Oct 18 15:44:41 2008 -0500
    11.3 @@ -5,7 +5,7 @@
    11.4  $ \textbf{echo 'I fixed a bug using only echo!' >> myfile}
    11.5  $ \textbf{hg commit -m 'Important fix for 1.0.1'}
    11.6  $ \textbf{hg push}
    11.7 -pushing to /tmp/branch-repo4rF-PL/myproject-1.0.1
    11.8 +pushing to 
    11.9  searching for changes
   11.10  adding changesets
   11.11  adding manifests

    12.1 --- a/en/examples/branching.stable.out	Sat Oct 18 14:35:43 2008 -0500
    12.2 +++ b/en/examples/branching.stable.out	Sat Oct 18 15:44:41 2008 -0500
    12.3 @@ -5,7 +5,7 @@
    12.4  $ \textbf{echo 'This is a fix to a boring feature.' > myfile}
    12.5  $ \textbf{hg commit -m 'Fix a bug'}
    12.6  $ \textbf{hg push}
    12.7 -pushing to /tmp/branchingfJgZac/stable
    12.8 +pushing to 
    12.9  searching for changes
   12.10  adding changesets
   12.11  adding manifests

    13.1 --- a/es/hgext.tex	Sat Oct 18 14:35:43 2008 -0500
    13.2 +++ b/es/hgext.tex	Sat Oct 18 15:44:41 2008 -0500
    13.3 @@ -0,0 +1,429 @@
    13.4 +\chapter{Adding functionality with extensions}
    13.5 +\label{chap:hgext}
    13.6 +
    13.7 +While the core of Mercurial is quite complete from a functionality
    13.8 +standpoint, it's deliberately shorn of fancy features.  This approach
    13.9 +of preserving simplicity keeps the software easy to deal with for both
   13.10 +maintainers and users.
   13.11 +
   13.12 +However, Mercurial doesn't box you in with an inflexible command set:
   13.13 +you can add features to it as \emph{extensions} (sometimes known as
   13.14 +\emph{plugins}).  We've already discussed a few of these extensions in
   13.15 +earlier chapters.
   13.16 +\begin{itemize}
   13.17 +\item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch}
   13.18 +  extension; this combines pulling new changes and merging them with
   13.19 +  local changes into a single command, \hgxcmd{fetch}{fetch}.
   13.20 +\item In chapter~\ref{chap:hook}, we covered several extensions that
   13.21 +  are useful for hook-related functionality: \hgext{acl} adds access
   13.22 +  control lists; \hgext{bugzilla} adds integration with the Bugzilla
   13.23 +  bug tracking system; and \hgext{notify} sends notification emails on
   13.24 +  new changes.
   13.25 +\item The Mercurial Queues patch management extension is so invaluable
   13.26 +  that it merits two chapters and an appendix all to itself.
   13.27 +  Chapter~\ref{chap:mq} covers the basics;
   13.28 +  chapter~\ref{chap:mq-collab} discusses advanced topics; and
   13.29 +  appendix~\ref{chap:mqref} goes into detail on each command.
   13.30 +\end{itemize}
   13.31 +
   13.32 +In this chapter, we'll cover some of the other extensions that are
   13.33 +available for Mercurial, and briefly touch on some of the machinery
   13.34 +you'll need to know about if you want to write an extension of your
   13.35 +own.
   13.36 +\begin{itemize}
   13.37 +\item In section~\ref{sec:hgext:inotify}, we'll discuss the
   13.38 +  possibility of \emph{huge} performance improvements using the
   13.39 +  \hgext{inotify} extension.
   13.40 +\end{itemize}
   13.41 +
   13.42 +\section{Improve performance with the \hgext{inotify} extension}
   13.43 +\label{sec:hgext:inotify}
   13.44 +
   13.45 +Are you interested in having some of the most common Mercurial
   13.46 +operations run as much as a hundred times faster?  Read on!
   13.47 +
   13.48 +Mercurial has great performance under normal circumstances.  For
   13.49 +example, when you run the \hgcmd{status} command, Mercurial has to
   13.50 +scan almost every directory and file in your repository so that it can
   13.51 +display file status.  Many other Mercurial commands need to do the
   13.52 +same work behind the scenes; for example, the \hgcmd{diff} command
   13.53 +uses the status machinery to avoid doing an expensive comparison
   13.54 +operation on files that obviously haven't changed.
   13.55 +
   13.56 +Because obtaining file status is crucial to good performance, the
   13.57 +authors of Mercurial have optimised this code to within an inch of its
   13.58 +life.  However, there's no avoiding the fact that when you run
   13.59 +\hgcmd{status}, Mercurial is going to have to perform at least one
   13.60 +expensive system call for each managed file to determine whether it's
   13.61 +changed since the last time Mercurial checked.  For a sufficiently
   13.62 +large repository, this can take a long time.
   13.63 +
   13.64 +To put a number on the magnitude of this effect, I created a
   13.65 +repository containing 150,000 managed files.  I timed \hgcmd{status}
   13.66 +as taking ten seconds to run, even when \emph{none} of those files had
   13.67 +been modified.
   13.68 +
   13.69 +Many modern operating systems contain a file notification facility.
   13.70 +If a program signs up to an appropriate service, the operating system
   13.71 +will notify it every time a file of interest is created, modified, or
   13.72 +deleted.  On Linux systems, the kernel component that does this is
   13.73 +called \texttt{inotify}.
   13.74 +
   13.75 +Mercurial's \hgext{inotify} extension talks to the kernel's
   13.76 +\texttt{inotify} component to optimise \hgcmd{status} commands.  The
   13.77 +extension has two components.  A daemon sits in the background and
   13.78 +receives notifications from the \texttt{inotify} subsystem.  It also
   13.79 +listens for connections from a regular Mercurial command.  The
   13.80 +extension modifies Mercurial's behaviour so that instead of scanning
   13.81 +the filesystem, it queries the daemon.  Since the daemon has perfect
   13.82 +information about the state of the repository, it can respond with a
   13.83 +result instantaneously, avoiding the need to scan every directory and
   13.84 +file in the repository.
   13.85 +
   13.86 +Recall the ten seconds that I measured plain Mercurial as taking to
   13.87 +run \hgcmd{status} on a 150,000 file repository.  With the
   13.88 +\hgext{inotify} extension enabled, the time dropped to 0.1~seconds, a
   13.89 +factor of \emph{one hundred} faster.
   13.90 +
   13.91 +Before we continue, please pay attention to some caveats.
   13.92 +\begin{itemize}
   13.93 +\item The \hgext{inotify} extension is Linux-specific.  Because it
   13.94 +  interfaces directly to the Linux kernel's \texttt{inotify}
   13.95 +  subsystem, it does not work on other operating systems.
   13.96 +\item It should work on any Linux distribution that was released after
   13.97 +  early~2005.  Older distributions are likely to have a kernel that
   13.98 +  lacks \texttt{inotify}, or a version of \texttt{glibc} that does not
   13.99 +  have the necessary interfacing support.
  13.100 +\item Not all filesystems are suitable for use with the
  13.101 +  \hgext{inotify} extension.  Network filesystems such as NFS are a
  13.102 +  non-starter, for example, particularly if you're running Mercurial
  13.103 +  on several systems, all mounting the same network filesystem.  The
  13.104 +  kernel's \texttt{inotify} system has no way of knowing about changes
  13.105 +  made on another system.  Most local filesystems (e.g.~ext3, XFS,
  13.106 +  ReiserFS) should work fine.
  13.107 +\end{itemize}
  13.108 +
  13.109 +The \hgext{inotify} extension is not yet shipped with Mercurial as of
  13.110 +May~2007, so it's a little more involved to set up than other
  13.111 +extensions.  But the performance improvement is worth it!
  13.112 +
  13.113 +The extension currently comes in two parts: a set of patches to the
  13.114 +Mercurial source code, and a library of Python bindings to the
  13.115 +\texttt{inotify} subsystem.
  13.116 +\begin{note}
  13.117 +  There are \emph{two} Python \texttt{inotify} binding libraries.  One
  13.118 +  of them is called \texttt{pyinotify}, and is packaged by some Linux
  13.119 +  distributions as \texttt{python-inotify}.  This is \emph{not} the
  13.120 +  one you'll need, as it is too buggy and inefficient to be practical.
  13.121 +\end{note}
  13.122 +To get going, it's best to already have a functioning copy of
  13.123 +Mercurial installed.
  13.124 +\begin{note}
  13.125 +  If you follow the instructions below, you'll be \emph{replacing} and
  13.126 +  overwriting any existing installation of Mercurial that you might
  13.127 +  already have, using the latest ``bleeding edge'' Mercurial code.
  13.128 +  Don't say you weren't warned!
  13.129 +\end{note}
  13.130 +\begin{enumerate}
  13.131 +\item Clone the Python \texttt{inotify} binding repository.  Build and
  13.132 +  install it.
  13.133 +  \begin{codesample4}
  13.134 +    hg clone http://hg.kublai.com/python/inotify
  13.135 +    cd inotify
  13.136 +    python setup.py build --force
  13.137 +    sudo python setup.py install --skip-build
  13.138 +  \end{codesample4}
  13.139 +\item Clone the \dirname{crew} Mercurial repository.  Clone the
  13.140 +  \hgext{inotify} patch repository so that Mercurial Queues will be
  13.141 +  able to apply patches to your cope of the \dirname{crew} repository.
  13.142 +  \begin{codesample4}
  13.143 +    hg clone http://hg.intevation.org/mercurial/crew
  13.144 +    hg clone crew inotify
  13.145 +    hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
  13.146 +  \end{codesample4}
  13.147 +\item Make sure that you have the Mercurial Queues extension,
  13.148 +  \hgext{mq}, enabled.  If you've never used MQ, read
  13.149 +  section~\ref{sec:mq:start} to get started quickly.
  13.150 +\item Go into the \dirname{inotify} repo, and apply all of the
  13.151 +  \hgext{inotify} patches using the \hgxopt{mq}{qpush}{-a} option to
  13.152 +  the \hgxcmd{mq}{qpush} command.
  13.153 +  \begin{codesample4}
  13.154 +    cd inotify
  13.155 +    hg qpush -a
  13.156 +  \end{codesample4}
  13.157 +  If you get an error message from \hgxcmd{mq}{qpush}, you should not
  13.158 +  continue.  Instead, ask for help.
  13.159 +\item Build and install the patched version of Mercurial.
  13.160 +  \begin{codesample4}
  13.161 +    python setup.py build --force
  13.162 +    sudo python setup.py install --skip-build
  13.163 +  \end{codesample4}
  13.164 +\end{enumerate}
  13.165 +Once you've build a suitably patched version of Mercurial, all you
  13.166 +need to do to enable the \hgext{inotify} extension is add an entry to
  13.167 +your \hgrc.
  13.168 +\begin{codesample2}
  13.169 +  [extensions]
  13.170 +  inotify =
  13.171 +\end{codesample2}
  13.172 +When the \hgext{inotify} extension is enabled, Mercurial will
  13.173 +automatically and transparently start the status daemon the first time
  13.174 +you run a command that needs status in a repository.  It runs one
  13.175 +status daemon per repository.
  13.176 +
  13.177 +The status daemon is started silently, and runs in the background.  If
  13.178 +you look at a list of running processes after you've enabled the
  13.179 +\hgext{inotify} extension and run a few commands in different
  13.180 +repositories, you'll thus see a few \texttt{hg} processes sitting
  13.181 +around, waiting for updates from the kernel and queries from
  13.182 +Mercurial.
  13.183 +
  13.184 +The first time you run a Mercurial command in a repository when you
  13.185 +have the \hgext{inotify} extension enabled, it will run with about the
  13.186 +same performance as a normal Mercurial command.  This is because the
  13.187 +status daemon needs to perform a normal status scan so that it has a
  13.188 +baseline against which to apply later updates from the kernel.
  13.189 +However, \emph{every} subsequent command that does any kind of status
  13.190 +check should be noticeably faster on repositories of even fairly
  13.191 +modest size.  Better yet, the bigger your repository is, the greater a
  13.192 +performance advantage you'll see.  The \hgext{inotify} daemon makes
  13.193 +status operations almost instantaneous on repositories of all sizes!
  13.194 +
  13.195 +If you like, you can manually start a status daemon using the
  13.196 +\hgxcmd{inotify}{inserve} command.  This gives you slightly finer
  13.197 +control over how the daemon ought to run.  This command will of course
  13.198 +only be available when the \hgext{inotify} extension is enabled.
  13.199 +
  13.200 +When you're using the \hgext{inotify} extension, you should notice
  13.201 +\emph{no difference at all} in Mercurial's behaviour, with the sole
  13.202 +exception of status-related commands running a whole lot faster than
  13.203 +they used to.  You should specifically expect that commands will not
  13.204 +print different output; neither should they give different results.
  13.205 +If either of these situations occurs, please report a bug.
  13.206 +
  13.207 +\section{Flexible diff support with the \hgext{extdiff} extension}
  13.208 +\label{sec:hgext:extdiff}
  13.209 +
  13.210 +Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
  13.211 +diffs.
  13.212 +\interaction{extdiff.diff}
  13.213 +If you would like to use an external tool to display modifications,
  13.214 +you'll want to use the \hgext{extdiff} extension.  This will let you
  13.215 +use, for example, a graphical diff tool.
  13.216 +
  13.217 +The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
  13.218 +to set up.  In the \rcsection{extensions} section of your \hgrc,
  13.219 +simply add a one-line entry to enable the extension.
  13.220 +\begin{codesample2}
  13.221 +  [extensions]
  13.222 +  extdiff =
  13.223 +\end{codesample2}
  13.224 +This introduces a command named \hgxcmd{extdiff}{extdiff}, which by
  13.225 +default uses your system's \command{diff} command to generate a
  13.226 +unified diff in the same form as the built-in \hgcmd{diff} command.
  13.227 +\interaction{extdiff.extdiff}
  13.228 +The result won't be exactly the same as with the built-in \hgcmd{diff}
  13.229 +variations, because the output of \command{diff} varies from one
  13.230 +system to another, even when passed the same options.
  13.231 +
  13.232 +As the ``\texttt{making snapshot}'' lines of output above imply, the
  13.233 +\hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
  13.234 +your source tree.  The first snapshot is of the source revision; the
  13.235 +second, of the target revision or working directory.  The
  13.236 +\hgxcmd{extdiff}{extdiff} command generates these snapshots in a
  13.237 +temporary directory, passes the name of each directory to an external
  13.238 +diff viewer, then deletes the temporary directory.  For efficiency, it
  13.239 +only snapshots the directories and files that have changed between the
  13.240 +two revisions.
  13.241 +
  13.242 +Snapshot directory names have the same base name as your repository.
  13.243 +If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
  13.244 +will be the name of each snapshot directory.  Each snapshot directory
  13.245 +name has its changeset ID appended, if appropriate.  If a snapshot is
  13.246 +of revision \texttt{a631aca1083f}, the directory will be named
  13.247 +\dirname{foo.a631aca1083f}.  A snapshot of the working directory won't
  13.248 +have a changeset ID appended, so it would just be \dirname{foo} in
  13.249 +this example.  To see what this looks like in practice, look again at
  13.250 +the \hgxcmd{extdiff}{extdiff} example above.  Notice that the diff has
  13.251 +the snapshot directory names embedded in its header.
  13.252 +
  13.253 +The \hgxcmd{extdiff}{extdiff} command accepts two important options.
  13.254 +The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
  13.255 +view differences with, instead of \command{diff}.  With the
  13.256 +\hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
  13.257 +\hgxcmd{extdiff}{extdiff} passes to the program (by default, these
  13.258 +options are ``\texttt{-Npru}'', which only make sense if you're
  13.259 +running \command{diff}).  In other respects, the
  13.260 +\hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
  13.261 +\hgcmd{diff} command: you use the same option names, syntax, and
  13.262 +arguments to specify the revisions you want, the files you want, and
  13.263 +so on.
  13.264 +
  13.265 +As an example, here's how to run the normal system \command{diff}
  13.266 +command, getting it to generate context diffs (using the
  13.267 +\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
  13.268 +context instead of the default three (passing \texttt{5} as the
  13.269 +argument to the \cmdopt{diff}{-C} option).
  13.270 +\interaction{extdiff.extdiff-ctx}
  13.271 +
  13.272 +Launching a visual diff tool is just as easy.  Here's how to launch
  13.273 +the \command{kdiff3} viewer.
  13.274 +\begin{codesample2}
  13.275 +  hg extdiff -p kdiff3 -o ''
  13.276 +\end{codesample2}
  13.277 +
  13.278 +If your diff viewing command can't deal with directories, you can
  13.279 +easily work around this with a little scripting.  For an example of
  13.280 +such scripting in action with the \hgext{mq} extension and the
  13.281 +\command{interdiff} command, see
  13.282 +section~\ref{mq-collab:tips:interdiff}.
  13.283 +
  13.284 +\subsection{Defining command aliases}
  13.285 +
  13.286 +It can be cumbersome to remember the options to both the
  13.287 +\hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use,
  13.288 +so the \hgext{extdiff} extension lets you define \emph{new} commands
  13.289 +that will invoke your diff viewer with exactly the right options.
  13.290 +
  13.291 +All you need to do is edit your \hgrc, and add a section named
  13.292 +\rcsection{extdiff}.  Inside this section, you can define multiple
  13.293 +commands.  Here's how to add a \texttt{kdiff3} command.  Once you've
  13.294 +defined this, you can type ``\texttt{hg kdiff3}'' and the
  13.295 +\hgext{extdiff} extension will run \command{kdiff3} for you.
  13.296 +\begin{codesample2}
  13.297 +  [extdiff]
  13.298 +  cmd.kdiff3 =
  13.299 +\end{codesample2}
  13.300 +If you leave the right hand side of the definition empty, as above,
  13.301 +the \hgext{extdiff} extension uses the name of the command you defined
  13.302 +as the name of the external program to run.  But these names don't
  13.303 +have to be the same.  Here, we define a command named ``\texttt{hg
  13.304 +  wibble}'', which runs \command{kdiff3}.
  13.305 +\begin{codesample2}
  13.306 +  [extdiff]
  13.307 +  cmd.wibble = kdiff3
  13.308 +\end{codesample2}
  13.309 +
  13.310 +You can also specify the default options that you want to invoke your
  13.311 +diff viewing program with.  The prefix to use is ``\texttt{opts.}'',
  13.312 +followed by the name of the command to which the options apply.  This
  13.313 +example defines a ``\texttt{hg vimdiff}'' command that runs the
  13.314 +\command{vim} editor's \texttt{DirDiff} extension.
  13.315 +\begin{codesample2}
  13.316 +  [extdiff]  
  13.317 +  cmd.vimdiff = vim
  13.318 +  opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
  13.319 +\end{codesample2}
  13.320 +
  13.321 +\section{Cherrypicking changes with the \hgext{transplant} extension}
  13.322 +\label{sec:hgext:transplant}
  13.323 +
  13.324 +Need to have a long chat with Brendan about this.
  13.325 +
  13.326 +\section{Send changes via email with the \hgext{patchbomb} extension}
  13.327 +\label{sec:hgext:patchbomb}
  13.328 +
  13.329 +Many projects have a culture of ``change review'', in which people
  13.330 +send their modifications to a mailing list for others to read and
  13.331 +comment on before they commit the final version to a shared
  13.332 +repository.  Some projects have people who act as gatekeepers; they
  13.333 +apply changes from other people to a repository to which those others
  13.334 +don't have access.
  13.335 +
  13.336 +Mercurial makes it easy to send changes over email for review or
  13.337 +application, via its \hgext{patchbomb} extension.  The extension is so
  13.338 +namd because changes are formatted as patches, and it's usual to send
  13.339 +one changeset per email message.  Sending a long series of changes by
  13.340 +email is thus much like ``bombing'' the recipient's inbox, hence
  13.341 +``patchbomb''.
  13.342 +
  13.343 +As usual, the basic configuration of the \hgext{patchbomb} extension
  13.344 +takes just one or two lines in your \hgrc.
  13.345 +\begin{codesample2}
  13.346 +  [extensions]
  13.347 +  patchbomb =
  13.348 +\end{codesample2}
  13.349 +Once you've enabled the extension, you will have a new command
  13.350 +available, named \hgxcmd{patchbomb}{email}.
  13.351 +
  13.352 +The safest and best way to invoke the \hgxcmd{patchbomb}{email}
  13.353 +command is to \emph{always} run it first with the
  13.354 +\hgxopt{patchbomb}{email}{-n} option.  This will show you what the
  13.355 +command \emph{would} send, without actually sending anything.  Once
  13.356 +you've had a quick glance over the changes and verified that you are
  13.357 +sending the right ones, you can rerun the same command, with the
  13.358 +\hgxopt{patchbomb}{email}{-n} option removed.
  13.359 +
  13.360 +The \hgxcmd{patchbomb}{email} command accepts the same kind of
  13.361 +revision syntax as every other Mercurial command.  For example, this
  13.362 +command will send every revision between 7 and \texttt{tip},
  13.363 +inclusive.
  13.364 +\begin{codesample2}
  13.365 +  hg email -n 7:tip
  13.366 +\end{codesample2}
  13.367 +You can also specify a \emph{repository} to compare with.  If you
  13.368 +provide a repository but no revisions, the \hgxcmd{patchbomb}{email}
  13.369 +command will send all revisions in the local repository that are not
  13.370 +present in the remote repository.  If you additionally specify
  13.371 +revisions or a branch name (the latter using the
  13.372 +\hgxopt{patchbomb}{email}{-b} option), this will constrain the
  13.373 +revisions sent.
  13.374 +
  13.375 +It's perfectly safe to run the \hgxcmd{patchbomb}{email} command
  13.376 +without the names of the people you want to send to: if you do this,
  13.377 +it will just prompt you for those values interactively.  (If you're
  13.378 +using a Linux or Unix-like system, you should have enhanced
  13.379 +\texttt{readline}-style editing capabilities when entering those
  13.380 +headers, too, which is useful.)
  13.381 +
  13.382 +When you are sending just one revision, the \hgxcmd{patchbomb}{email}
  13.383 +command will by default use the first line of the changeset
  13.384 +description as the subject of the single email message it sends.
  13.385 +
  13.386 +If you send multiple revisions, the \hgxcmd{patchbomb}{email} command
  13.387 +will usually send one message per changeset.  It will preface the
  13.388 +series with an introductory message, in which you should describe the
  13.389 +purpose of the series of changes you're sending.
  13.390 +
  13.391 +\subsection{Changing the behaviour of patchbombs}
  13.392 +
  13.393 +Not every project has exactly the same conventions for sending changes
  13.394 +in email; the \hgext{patchbomb} extension tries to accommodate a
  13.395 +number of variations through command line options.
  13.396 +\begin{itemize}
  13.397 +\item You can write a subject for the introductory message on the
  13.398 +  command line using the \hgxopt{patchbomb}{email}{-s} option.  This
  13.399 +  takes one argument, the text of the subject to use.
  13.400 +\item To change the email address from which the messages originate,
  13.401 +  use the \hgxopt{patchbomb}{email}{-f} option.  This takes one
  13.402 +  argument, the email address to use.
  13.403 +\item The default behaviour is to send unified diffs (see
  13.404 +  section~\ref{sec:mq:patch} for a description of the format), one per
  13.405 +  message.  You can send a binary bundle instead with the
  13.406 +  \hgxopt{patchbomb}{email}{-b} option.  
  13.407 +\item Unified diffs are normally prefaced with a metadata header.  You
  13.408 +  can omit this, and send unadorned diffs, with the
  13.409 +  \hgxopt{patchbomb}{email}{--plain} option.
  13.410 +\item Diffs are normally sent ``inline'', in the same body part as the
  13.411 +  description of a patch.  This makes it easiest for the largest
  13.412 +  number of readers to quote and respond to parts of a diff, as some
  13.413 +  mail clients will only quote the first MIME body part in a message.
  13.414 +  If you'd prefer to send the description and the diff in separate
  13.415 +  body parts, use the \hgxopt{patchbomb}{email}{-a} option.
  13.416 +\item Instead of sending mail messages, you can write them to an
  13.417 +  \texttt{mbox}-format mail folder using the
  13.418 +  \hgxopt{patchbomb}{email}{-m} option.  That option takes one
  13.419 +  argument, the name of the file to write to.
  13.420 +\item If you would like to add a \command{diffstat}-format summary to
  13.421 +  each patch, and one to the introductory message, use the
  13.422 +  \hgxopt{patchbomb}{email}{-d} option.  The \command{diffstat}
  13.423 +  command displays a table containing the name of each file patched,
  13.424 +  the number of lines affected, and a histogram showing how much each
  13.425 +  file is modified.  This gives readers a qualitative glance at how
  13.426 +  complex a patch is.
  13.427 +\end{itemize}
  13.428 +
  13.429 +%%% Local Variables: 
  13.430 +%%% mode: latex
  13.431 +%%% TeX-master: "00book"
  13.432 +%%% End: 

    14.1 --- a/es/hook.tex	Sat Oct 18 14:35:43 2008 -0500
    14.2 +++ b/es/hook.tex	Sat Oct 18 15:44:41 2008 -0500
    14.3 @@ -0,0 +1,1413 @@
    14.4 +\chapter{Handling repository events with hooks}
    14.5 +\label{chap:hook}
    14.6 +
    14.7 +Mercurial offers a powerful mechanism to let you perform automated
    14.8 +actions in response to events that occur in a repository.  In some
    14.9 +cases, you can even control Mercurial's response to those events.
   14.10 +
   14.11 +The name Mercurial uses for one of these actions is a \emph{hook}.
   14.12 +Hooks are called ``triggers'' in some revision control systems, but
   14.13 +the two names refer to the same idea.
   14.14 +
   14.15 +\section{An overview of hooks in Mercurial}
   14.16 +
   14.17 +Here is a brief list of the hooks that Mercurial supports.  We will
   14.18 +revisit each of these hooks in more detail later, in
   14.19 +section~\ref{sec:hook:ref}.
   14.20 +
   14.21 +\begin{itemize}
   14.22 +\item[\small\hook{changegroup}] This is run after a group of
   14.23 +  changesets has been brought into the repository from elsewhere.
   14.24 +\item[\small\hook{commit}] This is run after a new changeset has been
   14.25 +  created in the local repository.
   14.26 +\item[\small\hook{incoming}] This is run once for each new changeset
   14.27 +  that is brought into the repository from elsewhere.  Notice the
   14.28 +  difference from \hook{changegroup}, which is run once per
   14.29 +  \emph{group} of changesets brought in.
   14.30 +\item[\small\hook{outgoing}] This is run after a group of changesets
   14.31 +  has been transmitted from this repository.
   14.32 +\item[\small\hook{prechangegroup}] This is run before starting to
   14.33 +  bring a group of changesets into the repository.
   14.34 +\item[\small\hook{precommit}] Controlling. This is run before starting
   14.35 +  a commit.
   14.36 +\item[\small\hook{preoutgoing}] Controlling. This is run before
   14.37 +  starting to transmit a group of changesets from this repository.
   14.38 +\item[\small\hook{pretag}] Controlling. This is run before creating a tag.
   14.39 +\item[\small\hook{pretxnchangegroup}] Controlling. This is run after a
   14.40 +  group of changesets has been brought into the local repository from
   14.41 +  another, but before the transaction completes that will make the
   14.42 +  changes permanent in the repository.
   14.43 +\item[\small\hook{pretxncommit}] Controlling. This is run after a new
   14.44 +  changeset has been created in the local repository, but before the
   14.45 +  transaction completes that will make it permanent.
   14.46 +\item[\small\hook{preupdate}] Controlling. This is run before starting
   14.47 +  an update or merge of the working directory.
   14.48 +\item[\small\hook{tag}] This is run after a tag is created.
   14.49 +\item[\small\hook{update}] This is run after an update or merge of the
   14.50 +  working directory has finished.
   14.51 +\end{itemize}
   14.52 +Each of the hooks whose description begins with the word
   14.53 +``Controlling'' has the ability to determine whether an activity can
   14.54 +proceed.  If the hook succeeds, the activity may proceed; if it fails,
   14.55 +the activity is either not permitted or undone, depending on the hook.
   14.56 +
   14.57 +\section{Hooks and security}
   14.58 +
   14.59 +\subsection{Hooks are run with your privileges}
   14.60 +
   14.61 +When you run a Mercurial command in a repository, and the command
   14.62 +causes a hook to run, that hook runs on \emph{your} system, under
   14.63 +\emph{your} user account, with \emph{your} privilege level.  Since
   14.64 +hooks are arbitrary pieces of executable code, you should treat them
   14.65 +with an appropriate level of suspicion.  Do not install a hook unless
   14.66 +you are confident that you know who created it and what it does.
   14.67 +
   14.68 +In some cases, you may be exposed to hooks that you did not install
   14.69 +yourself.  If you work with Mercurial on an unfamiliar system,
   14.70 +Mercurial will run hooks defined in that system's global \hgrc\ file.
   14.71 +
   14.72 +If you are working with a repository owned by another user, Mercurial
   14.73 +can run hooks defined in that user's repository, but it will still run
   14.74 +them as ``you''.  For example, if you \hgcmd{pull} from that
   14.75 +repository, and its \sfilename{.hg/hgrc} defines a local
   14.76 +\hook{outgoing} hook, that hook will run under your user account, even
   14.77 +though you don't own that repository.
   14.78 +
   14.79 +\begin{note}
   14.80 +  This only applies if you are pulling from a repository on a local or
   14.81 +  network filesystem.  If you're pulling over http or ssh, any
   14.82 +  \hook{outgoing} hook will run under whatever account is executing
   14.83 +  the server process, on the server.
   14.84 +\end{note}
   14.85 +
   14.86 +XXX To see what hooks are defined in a repository, use the
   14.87 +\hgcmdargs{config}{hooks} command.  If you are working in one
   14.88 +repository, but talking to another that you do not own (e.g.~using
   14.89 +\hgcmd{pull} or \hgcmd{incoming}), remember that it is the other
   14.90 +repository's hooks you should be checking, not your own.
   14.91 +
   14.92 +\subsection{Hooks do not propagate}
   14.93 +
   14.94 +In Mercurial, hooks are not revision controlled, and do not propagate
   14.95 +when you clone, or pull from, a repository.  The reason for this is
   14.96 +simple: a hook is a completely arbitrary piece of executable code.  It
   14.97 +runs under your user identity, with your privilege level, on your
   14.98 +machine.
   14.99 +
  14.100 +It would be extremely reckless for any distributed revision control
  14.101 +system to implement revision-controlled hooks, as this would offer an
  14.102 +easily exploitable way to subvert the accounts of users of the
  14.103 +revision control system.
  14.104 +
  14.105 +Since Mercurial does not propagate hooks, if you are collaborating
  14.106 +with other people on a common project, you should not assume that they
  14.107 +are using the same Mercurial hooks as you are, or that theirs are
  14.108 +correctly configured.  You should document the hooks you expect people
  14.109 +to use.
  14.110 +
  14.111 +In a corporate intranet, this is somewhat easier to control, as you
  14.112 +can for example provide a ``standard'' installation of Mercurial on an
  14.113 +NFS filesystem, and use a site-wide \hgrc\ file to define hooks that
  14.114 +all users will see.  However, this too has its limits; see below.
  14.115 +
  14.116 +\subsection{Hooks can be overridden}
  14.117 +
  14.118 +Mercurial allows you to override a hook definition by redefining the
  14.119 +hook.  You can disable it by setting its value to the empty string, or
  14.120 +change its behaviour as you wish.
  14.121 +
  14.122 +If you deploy a system-~or site-wide \hgrc\ file that defines some
  14.123 +hooks, you should thus understand that your users can disable or
  14.124 +override those hooks.
  14.125 +
  14.126 +\subsection{Ensuring that critical hooks are run}
  14.127 +
  14.128 +Sometimes you may want to enforce a policy that you do not want others
  14.129 +to be able to work around.  For example, you may have a requirement
  14.130 +that every changeset must pass a rigorous set of tests.  Defining this
  14.131 +requirement via a hook in a site-wide \hgrc\ won't work for remote
  14.132 +users on laptops, and of course local users can subvert it at will by
  14.133 +overriding the hook.
  14.134 +
  14.135 +Instead, you can set up your policies for use of Mercurial so that
  14.136 +people are expected to propagate changes through a well-known
  14.137 +``canonical'' server that you have locked down and configured
  14.138 +appropriately.
  14.139 +
  14.140 +One way to do this is via a combination of social engineering and
  14.141 +technology.  Set up a restricted-access account; users can push
  14.142 +changes over the network to repositories managed by this account, but
  14.143 +they cannot log into the account and run normal shell commands.  In
  14.144 +this scenario, a user can commit a changeset that contains any old
  14.145 +garbage they want.
  14.146 +
  14.147 +When someone pushes a changeset to the server that everyone pulls
  14.148 +from, the server will test the changeset before it accepts it as
  14.149 +permanent, and reject it if it fails to pass the test suite.  If
  14.150 +people only pull changes from this filtering server, it will serve to
  14.151 +ensure that all changes that people pull have been automatically
  14.152 +vetted.
  14.153 +
  14.154 +\section{Care with \texttt{pretxn} hooks in a shared-access repository}
  14.155 +
  14.156 +If you want to use hooks to do some automated work in a repository
  14.157 +that a number of people have shared access to, you need to be careful
  14.158 +in how you do this.
  14.159 +
  14.160 +Mercurial only locks a repository when it is writing to the
  14.161 +repository, and only the parts of Mercurial that write to the
  14.162 +repository pay attention to locks.  Write locks are necessary to
  14.163 +prevent multiple simultaneous writers from scribbling on each other's
  14.164 +work, corrupting the repository.
  14.165 +
  14.166 +Because Mercurial is careful with the order in which it reads and
  14.167 +writes data, it does not need to acquire a lock when it wants to read
  14.168 +data from the repository.  The parts of Mercurial that read from the
  14.169 +repository never pay attention to locks.  This lockless reading scheme
  14.170 +greatly increases performance and concurrency.
  14.171 +
  14.172 +With great performance comes a trade-off, though, one which has the
  14.173 +potential to cause you trouble unless you're aware of it.  To describe
  14.174 +this requires a little detail about how Mercurial adds changesets to a
  14.175 +repository and reads those changes.
  14.176 +
  14.177 +When Mercurial \emph{writes} metadata, it writes it straight into the
  14.178 +destination file.  It writes file data first, then manifest data
  14.179 +(which contains pointers to the new file data), then changelog data
  14.180 +(which contains pointers to the new manifest data).  Before the first
  14.181 +write to each file, it stores a record of where the end of the file
  14.182 +was in its transaction log.  If the transaction must be rolled back,
  14.183 +Mercurial simply truncates each file back to the size it was before the
  14.184 +transaction began.
  14.185 +
  14.186 +When Mercurial \emph{reads} metadata, it reads the changelog first,
  14.187 +then everything else.  Since a reader will only access parts of the
  14.188 +manifest or file metadata that it can see in the changelog, it can
  14.189 +never see partially written data.
  14.190 +
  14.191 +Some controlling hooks (\hook{pretxncommit} and
  14.192 +\hook{pretxnchangegroup}) run when a transaction is almost complete.
  14.193 +All of the metadata has been written, but Mercurial can still roll the
  14.194 +transaction back and cause the newly-written data to disappear.
  14.195 +
  14.196 +If one of these hooks runs for long, it opens a window of time during
  14.197 +which a reader can see the metadata for changesets that are not yet
  14.198 +permanent, and should not be thought of as ``really there''.  The
  14.199 +longer the hook runs, the longer that window is open.
  14.200 +
  14.201 +\subsection{The problem illustrated}
  14.202 +
  14.203 +In principle, a good use for the \hook{pretxnchangegroup} hook would
  14.204 +be to automatically build and test incoming changes before they are
  14.205 +accepted into a central repository.  This could let you guarantee that
  14.206 +nobody can push changes to this repository that ``break the build''.
  14.207 +But if a client can pull changes while they're being tested, the
  14.208 +usefulness of the test is zero; an unsuspecting someone can pull
  14.209 +untested changes, potentially breaking their build.
  14.210 +
  14.211 +The safest technological answer to this challenge is to set up such a
  14.212 +``gatekeeper'' repository as \emph{unidirectional}.  Let it take
  14.213 +changes pushed in from the outside, but do not allow anyone to pull
  14.214 +changes from it (use the \hook{preoutgoing} hook to lock it down).
  14.215 +Configure a \hook{changegroup} hook so that if a build or test
  14.216 +succeeds, the hook will push the new changes out to another repository
  14.217 +that people \emph{can} pull from.
  14.218 +
  14.219 +In practice, putting a centralised bottleneck like this in place is
  14.220 +not often a good idea, and transaction visibility has nothing to do
  14.221 +with the problem.  As the size of a project---and the time it takes to
  14.222 +build and test---grows, you rapidly run into a wall with this ``try
  14.223 +before you buy'' approach, where you have more changesets to test than
  14.224 +time in which to deal with them.  The inevitable result is frustration
  14.225 +on the part of all involved.
  14.226 +
  14.227 +An approach that scales better is to get people to build and test
  14.228 +before they push, then run automated builds and tests centrally
  14.229 +\emph{after} a push, to be sure all is well.  The advantage of this
  14.230 +approach is that it does not impose a limit on the rate at which the
  14.231 +repository can accept changes.
  14.232 +
  14.233 +\section{A short tutorial on using hooks}
  14.234 +\label{sec:hook:simple}
  14.235 +
  14.236 +It is easy to write a Mercurial hook.  Let's start with a hook that
  14.237 +runs when you finish a \hgcmd{commit}, and simply prints the hash of
  14.238 +the changeset you just created.  The hook is called \hook{commit}.
  14.239 +
  14.240 +\begin{figure}[ht]
  14.241 +  \interaction{hook.simple.init}
  14.242 +  \caption{A simple hook that runs when a changeset is committed}
  14.243 +  \label{ex:hook:init}
  14.244 +\end{figure}
  14.245 +
  14.246 +All hooks follow the pattern in example~\ref{ex:hook:init}.  You add
  14.247 +an entry to the \rcsection{hooks} section of your \hgrc.  On the left
  14.248 +is the name of the event to trigger on; on the right is the action to
  14.249 +take.  As you can see, you can run an arbitrary shell command in a
  14.250 +hook.  Mercurial passes extra information to the hook using
  14.251 +environment variables (look for \envar{HG\_NODE} in the example).
  14.252 +
  14.253 +\subsection{Performing multiple actions per event}
  14.254 +
  14.255 +Quite often, you will want to define more than one hook for a
  14.256 +particular kind of event, as shown in example~\ref{ex:hook:ext}.
  14.257 +Mercurial lets you do this by adding an \emph{extension} to the end of
  14.258 +a hook's name.  You extend a hook's name by giving the name of the
  14.259 +hook, followed by a full stop (the ``\texttt{.}'' character), followed
  14.260 +by some more text of your choosing.  For example, Mercurial will run
  14.261 +both \texttt{commit.foo} and \texttt{commit.bar} when the
  14.262 +\texttt{commit} event occurs.
  14.263 +
  14.264 +\begin{figure}[ht]
  14.265 +  \interaction{hook.simple.ext}
  14.266 +  \caption{Defining a second \hook{commit} hook}
  14.267 +  \label{ex:hook:ext}
  14.268 +\end{figure}
  14.269 +
  14.270 +To give a well-defined order of execution when there are multiple
  14.271 +hooks defined for an event, Mercurial sorts hooks by extension, and
  14.272 +executes the hook commands in this sorted order.  In the above
  14.273 +example, it will execute \texttt{commit.bar} before
  14.274 +\texttt{commit.foo}, and \texttt{commit} before both.
  14.275 +
  14.276 +It is a good idea to use a somewhat descriptive extension when you
  14.277 +define a new hook.  This will help you to remember what the hook was
  14.278 +for.  If the hook fails, you'll get an error message that contains the
  14.279 +hook name and extension, so using a descriptive extension could give
  14.280 +you an immediate hint as to why the hook failed (see
  14.281 +section~\ref{sec:hook:perm} for an example).
  14.282 +
  14.283 +\subsection{Controlling whether an activity can proceed}
  14.284 +\label{sec:hook:perm}
  14.285 +
  14.286 +In our earlier examples, we used the \hook{commit} hook, which is
  14.287 +run after a commit has completed.  This is one of several Mercurial
  14.288 +hooks that run after an activity finishes.  Such hooks have no way of
  14.289 +influencing the activity itself.
  14.290 +
  14.291 +Mercurial defines a number of events that occur before an activity
  14.292 +starts; or after it starts, but before it finishes.  Hooks that
  14.293 +trigger on these events have the added ability to choose whether the
  14.294 +activity can continue, or will abort.  
  14.295 +
  14.296 +The \hook{pretxncommit} hook runs after a commit has all but
  14.297 +completed.  In other words, the metadata representing the changeset
  14.298 +has been written out to disk, but the transaction has not yet been
  14.299 +allowed to complete.  The \hook{pretxncommit} hook has the ability to
  14.300 +decide whether the transaction can complete, or must be rolled back.
  14.301 +
  14.302 +If the \hook{pretxncommit} hook exits with a status code of zero, the
  14.303 +transaction is allowed to complete; the commit finishes; and the
  14.304 +\hook{commit} hook is run.  If the \hook{pretxncommit} hook exits with
  14.305 +a non-zero status code, the transaction is rolled back; the metadata
  14.306 +representing the changeset is erased; and the \hook{commit} hook is
  14.307 +not run.
  14.308 +
  14.309 +\begin{figure}[ht]
  14.310 +  \interaction{hook.simple.pretxncommit}
  14.311 +  \caption{Using the \hook{pretxncommit} hook to control commits}
  14.312 +  \label{ex:hook:pretxncommit}
  14.313 +\end{figure}
  14.314 +
  14.315 +The hook in example~\ref{ex:hook:pretxncommit} checks that a commit
  14.316 +comment contains a bug ID.  If it does, the commit can complete.  If
  14.317 +not, the commit is rolled back.
  14.318 +
  14.319 +\section{Writing your own hooks}
  14.320 +
  14.321 +When you are writing a hook, you might find it useful to run Mercurial
  14.322 +either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
  14.323 +item set to ``true''.  When you do so, Mercurial will print a message
  14.324 +before it calls each hook.
  14.325 +
  14.326 +\subsection{Choosing how your hook should run}
  14.327 +\label{sec:hook:lang}
  14.328 +
  14.329 +You can write a hook either as a normal program---typically a shell
  14.330 +script---or as a Python function that is executed within the Mercurial
  14.331 +process.
  14.332 +
  14.333 +Writing a hook as an external program has the advantage that it
  14.334 +requires no knowledge of Mercurial's internals.  You can call normal
  14.335 +Mercurial commands to get any added information you need.  The
  14.336 +trade-off is that external hooks are slower than in-process hooks.
  14.337 +
  14.338 +An in-process Python hook has complete access to the Mercurial API,
  14.339 +and does not ``shell out'' to another process, so it is inherently
  14.340 +faster than an external hook.  It is also easier to obtain much of the
  14.341 +information that a hook requires by using the Mercurial API than by
  14.342 +running Mercurial commands.
  14.343 +
  14.344 +If you are comfortable with Python, or require high performance,
  14.345 +writing your hooks in Python may be a good choice.  However, when you
  14.346 +have a straightforward hook to write and you don't need to care about
  14.347 +performance (probably the majority of hooks), a shell script is
  14.348 +perfectly fine.
  14.349 +
  14.350 +\subsection{Hook parameters}
  14.351 +\label{sec:hook:param}
  14.352 +
  14.353 +Mercurial calls each hook with a set of well-defined parameters.  In
  14.354 +Python, a parameter is passed as a keyword argument to your hook
  14.355 +function.  For an external program, a parameter is passed as an
  14.356 +environment variable.
  14.357 +
  14.358 +Whether your hook is written in Python or as a shell script, the
  14.359 +hook-specific parameter names and values will be the same.  A boolean
  14.360 +parameter will be represented as a boolean value in Python, but as the
  14.361 +number 1 (for ``true'') or 0 (for ``false'') as an environment
  14.362 +variable for an external hook.  If a hook parameter is named
  14.363 +\texttt{foo}, the keyword argument for a Python hook will also be
  14.364 +named \texttt{foo}, while the environment variable for an external
  14.365 +hook will be named \texttt{HG\_FOO}.
  14.366 +
  14.367 +\subsection{Hook return values and activity control}
  14.368 +
  14.369 +A hook that executes successfully must exit with a status of zero if
  14.370 +external, or return boolean ``false'' if in-process.  Failure is
  14.371 +indicated with a non-zero exit status from an external hook, or an
  14.372 +in-process hook returning boolean ``true''.  If an in-process hook
  14.373 +raises an exception, the hook is considered to have failed.
  14.374 +
  14.375 +For a hook that controls whether an activity can proceed, zero/false
  14.376 +means ``allow'', while non-zero/true/exception means ``deny''.
  14.377 +
  14.378 +\subsection{Writing an external hook}
  14.379 +
  14.380 +When you define an external hook in your \hgrc\ and the hook is run,
  14.381 +its value is passed to your shell, which interprets it.  This means
  14.382 +that you can use normal shell constructs in the body of the hook.
  14.383 +
  14.384 +An executable hook is always run with its current directory set to a
  14.385 +repository's root directory.
  14.386 +
  14.387 +Each hook parameter is passed in as an environment variable; the name
  14.388 +is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
  14.389 +
  14.390 +With the exception of hook parameters, Mercurial does not set or
  14.391 +modify any environment variables when running a hook.  This is useful
  14.392 +to remember if you are writing a site-wide hook that may be run by a
  14.393 +number of different users with differing environment variables set.
  14.394 +In multi-user situations, you should not rely on environment variables
  14.395 +being set to the values you have in your environment when testing the
  14.396 +hook.
  14.397 +
  14.398 +\subsection{Telling Mercurial to use an in-process hook}
  14.399 +
  14.400 +The \hgrc\ syntax for defining an in-process hook is slightly
  14.401 +different than for an executable hook.  The value of the hook must
  14.402 +start with the text ``\texttt{python:}'', and continue with the
  14.403 +fully-qualified name of a callable object to use as the hook's value.
  14.404 +
  14.405 +The module in which a hook lives is automatically imported when a hook
  14.406 +is run.  So long as you have the module name and \envar{PYTHONPATH}
  14.407 +right, it should ``just work''.
  14.408 +
  14.409 +The following \hgrc\ example snippet illustrates the syntax and
  14.410 +meaning of the notions we just described.
  14.411 +\begin{codesample2}
  14.412 +  [hooks]
  14.413 +  commit.example = python:mymodule.submodule.myhook
  14.414 +\end{codesample2}
  14.415 +When Mercurial runs the \texttt{commit.example} hook, it imports
  14.416 +\texttt{mymodule.submodule}, looks for the callable object named
  14.417 +\texttt{myhook}, and calls it.
  14.418 +
  14.419 +\subsection{Writing an in-process hook}
  14.420 +
  14.421 +The simplest in-process hook does nothing, but illustrates the basic
  14.422 +shape of the hook API:
  14.423 +\begin{codesample2}
  14.424 +  def myhook(ui, repo, **kwargs):
  14.425 +      pass
  14.426 +\end{codesample2}
  14.427 +The first argument to a Python hook is always a
  14.428 +\pymodclass{mercurial.ui}{ui} object.  The second is a repository object;
  14.429 +at the moment, it is always an instance of
  14.430 +\pymodclass{mercurial.localrepo}{localrepository}.  Following these two
  14.431 +arguments are other keyword arguments.  Which ones are passed in
  14.432 +depends on the hook being called, but a hook can ignore arguments it
  14.433 +doesn't care about by dropping them into a keyword argument dict, as
  14.434 +with \texttt{**kwargs} above.
  14.435 +
  14.436 +\section{Some hook examples}
  14.437 +
  14.438 +\subsection{Writing meaningful commit messages}
  14.439 +
  14.440 +It's hard to imagine a useful commit message being very short.  The
  14.441 +simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go}
  14.442 +will prevent you from committing a changeset with a message that is
  14.443 +less than ten bytes long.
  14.444 +
  14.445 +\begin{figure}[ht]
  14.446 +  \interaction{hook.msglen.go}
  14.447 +  \caption{A hook that forbids overly short commit messages}
  14.448 +  \label{ex:hook:msglen.go}
  14.449 +\end{figure}
  14.450 +
  14.451 +\subsection{Checking for trailing whitespace}
  14.452 +
  14.453 +An interesting use of a commit-related hook is to help you to write
  14.454 +cleaner code.  A simple example of ``cleaner code'' is the dictum that
  14.455 +a change should not add any new lines of text that contain ``trailing
  14.456 +whitespace''.  Trailing whitespace is a series of space and tab
  14.457 +characters at the end of a line of text.  In most cases, trailing
  14.458 +whitespace is unnecessary, invisible noise, but it is occasionally
  14.459 +problematic, and people often prefer to get rid of it.
  14.460 +
  14.461 +You can use either the \hook{precommit} or \hook{pretxncommit} hook to
  14.462 +tell whether you have a trailing whitespace problem.  If you use the
  14.463 +\hook{precommit} hook, the hook will not know which files you are
  14.464 +committing, so it will have to check every modified file in the
  14.465 +repository for trailing white space.  If you want to commit a change
  14.466 +to just the file \filename{foo}, but the file \filename{bar} contains
  14.467 +trailing whitespace, doing a check in the \hook{precommit} hook will
  14.468 +prevent you from committing \filename{foo} due to the problem with
  14.469 +\filename{bar}.  This doesn't seem right.
  14.470 +
  14.471 +Should you choose the \hook{pretxncommit} hook, the check won't occur
  14.472 +until just before the transaction for the commit completes.  This will
  14.473 +allow you to check for problems only the exact files that are being
  14.474 +committed.  However, if you entered the commit message interactively
  14.475 +and the hook fails, the transaction will roll back; you'll have to
  14.476 +re-enter the commit message after you fix the trailing whitespace and
  14.477 +run \hgcmd{commit} again.
  14.478 +
  14.479 +\begin{figure}[ht]
  14.480 +  \interaction{hook.ws.simple}
  14.481 +  \caption{A simple hook that checks for trailing whitespace}
  14.482 +  \label{ex:hook:ws.simple}
  14.483 +\end{figure}
  14.484 +
  14.485 +Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit}
  14.486 +hook that checks for trailing whitespace.  This hook is short, but not
  14.487 +very helpful.  It exits with an error status if a change adds a line
  14.488 +with trailing whitespace to any file, but does not print any
  14.489 +information that might help us to identify the offending file or
  14.490 +line.  It also has the nice property of not paying attention to
  14.491 +unmodified lines; only lines that introduce new trailing whitespace
  14.492 +cause problems.
  14.493 +
  14.494 +\begin{figure}[ht]
  14.495 +  \interaction{hook.ws.better}
  14.496 +  \caption{A better trailing whitespace hook}
  14.497 +  \label{ex:hook:ws.better}
  14.498 +\end{figure}
  14.499 +
  14.500 +The example of figure~\ref{ex:hook:ws.better} is much more complex,
  14.501 +but also more useful.  It parses a unified diff to see if any lines
  14.502 +add trailing whitespace, and prints the name of the file and the line
  14.503 +number of each such occurrence.  Even better, if the change adds
  14.504 +trailing whitespace, this hook saves the commit comment and prints the
  14.505 +name of the save file before exiting and telling Mercurial to roll the
  14.506 +transaction back, so you can use
  14.507 +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the
  14.508 +saved commit message once you've corrected the problem.
  14.509 +
  14.510 +As a final aside, note in figure~\ref{ex:hook:ws.better} the use of
  14.511 +\command{perl}'s in-place editing feature to get rid of trailing
  14.512 +whitespace from a file.  This is concise and useful enough that I will
  14.513 +reproduce it here.
  14.514 +\begin{codesample2}
  14.515 +  perl -pi -e 's,\\s+\$,,' filename
  14.516 +\end{codesample2}
  14.517 +
  14.518 +\section{Bundled hooks}
  14.519 +
  14.520 +Mercurial ships with several bundled hooks.  You can find them in the
  14.521 +\dirname{hgext} directory of a Mercurial source tree.  If you are
  14.522 +using a Mercurial binary package, the hooks will be located in the
  14.523 +\dirname{hgext} directory of wherever your package installer put
  14.524 +Mercurial.
  14.525 +
  14.526 +\subsection{\hgext{acl}---access control for parts of a repository}
  14.527 +
  14.528 +The \hgext{acl} extension lets you control which remote users are
  14.529 +allowed to push changesets to a networked server.  You can protect any
  14.530 +portion of a repository (including the entire repo), so that a
  14.531 +specific remote user can push changes that do not affect the protected
  14.532 +portion.
  14.533 +
  14.534 +This extension implements access control based on the identity of the
  14.535 +user performing a push, \emph{not} on who committed the changesets
  14.536 +they're pushing.  It makes sense to use this hook only if you have a
  14.537 +locked-down server environment that authenticates remote users, and
  14.538 +you want to be sure that only specific users are allowed to push
  14.539 +changes to that server.
  14.540 +
  14.541 +\subsubsection{Configuring the \hook{acl} hook}
  14.542 +
  14.543 +In order to manage incoming changesets, the \hgext{acl} hook must be
  14.544 +used as a \hook{pretxnchangegroup} hook.  This lets it see which files
  14.545 +are modified by each incoming changeset, and roll back a group of
  14.546 +changesets if they modify ``forbidden'' files.  Example:
  14.547 +\begin{codesample2}
  14.548 +  [hooks]
  14.549 +  pretxnchangegroup.acl = python:hgext.acl.hook
  14.550 +\end{codesample2}
  14.551 +
  14.552 +The \hgext{acl} extension is configured using three sections.  
  14.553 +
  14.554 +The \rcsection{acl} section has only one entry, \rcitem{acl}{sources},
  14.555 +which lists the sources of incoming changesets that the hook should
  14.556 +pay attention to.  You don't normally need to configure this section.
  14.557 +\begin{itemize}
  14.558 +\item[\rcitem{acl}{serve}] Control incoming changesets that are arriving
  14.559 +  from a remote repository over http or ssh.  This is the default
  14.560 +  value of \rcitem{acl}{sources}, and usually the only setting you'll
  14.561 +  need for this configuration item.
  14.562 +\item[\rcitem{acl}{pull}] Control incoming changesets that are
  14.563 +  arriving via a pull from a local repository.
  14.564 +\item[\rcitem{acl}{push}] Control incoming changesets that are
  14.565 +  arriving via a push from a local repository.
  14.566 +\item[\rcitem{acl}{bundle}] Control incoming changesets that are
  14.567 +  arriving from another repository via a bundle.
  14.568 +\end{itemize}
  14.569 +
  14.570 +The \rcsection{acl.allow} section controls the users that are allowed to
  14.571 +add changesets to the repository.  If this section is not present, all
  14.572 +users that are not explicitly denied are allowed.  If this section is
  14.573 +present, all users that are not explicitly allowed are denied (so an
  14.574 +empty section means that all users are denied).
  14.575 +
  14.576 +The \rcsection{acl.deny} section determines which users are denied
  14.577 +from adding changesets to the repository.  If this section is not
  14.578 +present or is empty, no users are denied.
  14.579 +
  14.580 +The syntaxes for the \rcsection{acl.allow} and \rcsection{acl.deny}
  14.581 +sections are identical.  On the left of each entry is a glob pattern
  14.582 +that matches files or directories, relative to the root of the
  14.583 +repository; on the right, a user name.
  14.584 +
  14.585 +In the following example, the user \texttt{docwriter} can only push
  14.586 +changes to the \dirname{docs} subtree of the repository, while
  14.587 +\texttt{intern} can push changes to any file or directory except
  14.588 +\dirname{source/sensitive}.
  14.589 +\begin{codesample2}
  14.590 +  [acl.allow]
  14.591 +  docs/** = docwriter
  14.592 +
  14.593 +  [acl.deny]
  14.594 +  source/sensitive/** = intern
  14.595 +\end{codesample2}
  14.596 +
  14.597 +\subsubsection{Testing and troubleshooting}
  14.598 +
  14.599 +If you want to test the \hgext{acl} hook, run it with Mercurial's
  14.600 +debugging output enabled.  Since you'll probably be running it on a
  14.601 +server where it's not convenient (or sometimes possible) to pass in
  14.602 +the \hggopt{--debug} option, don't forget that you can enable
  14.603 +debugging output in your \hgrc:
  14.604 +\begin{codesample2}
  14.605 +  [ui]
  14.606 +  debug = true
  14.607 +\end{codesample2}
  14.608 +With this enabled, the \hgext{acl} hook will print enough information
  14.609 +to let you figure out why it is allowing or forbidding pushes from
  14.610 +specific users.
  14.611 +
  14.612 +\subsection{\hgext{bugzilla}---integration with Bugzilla}
  14.613 +
  14.614 +The \hgext{bugzilla} extension adds a comment to a Bugzilla bug
  14.615 +whenever it finds a reference to that bug ID in a commit comment.  You
  14.616 +can install this hook on a shared server, so that any time a remote
  14.617 +user pushes changes to this server, the hook gets run.  
  14.618 +
  14.619 +It adds a comment to the bug that looks like this (you can configure
  14.620 +the contents of the comment---see below):
  14.621 +\begin{codesample2}
  14.622 +  Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in
  14.623 +  the frobnitz repository, refers to this bug.
  14.624 +
  14.625 +  For complete details, see
  14.626 +  http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
  14.627 +
  14.628 +  Changeset description:
  14.629 +        Fix bug 10483 by guarding against some NULL pointers
  14.630 +\end{codesample2}
  14.631 +The value of this hook is that it automates the process of updating a
  14.632 +bug any time a changeset refers to it.  If you configure the hook
  14.633 +properly, it makes it easy for people to browse straight from a
  14.634 +Bugzilla bug to a changeset that refers to that bug.
  14.635 +
  14.636 +You can use the code in this hook as a starting point for some more
  14.637 +exotic Bugzilla integration recipes.  Here are a few possibilities:
  14.638 +\begin{itemize}
  14.639 +\item Require that every changeset pushed to the server have a valid
  14.640 +  bug~ID in its commit comment.  In this case, you'd want to configure
  14.641 +  the hook as a \hook{pretxncommit} hook.  This would allow the hook
  14.642 +  to reject changes that didn't contain bug IDs.
  14.643 +\item Allow incoming changesets to automatically modify the
  14.644 +  \emph{state} of a bug, as well as simply adding a comment.  For
  14.645 +  example, the hook could recognise the string ``fixed bug 31337'' as
  14.646 +  indicating that it should update the state of bug 31337 to
  14.647 +  ``requires testing''.
  14.648 +\end{itemize}
  14.649 +
  14.650 +\subsubsection{Configuring the \hook{bugzilla} hook}
  14.651 +\label{sec:hook:bugzilla:config}
  14.652 +
  14.653 +You should configure this hook in your server's \hgrc\ as an
  14.654 +\hook{incoming} hook, for example as follows:
  14.655 +\begin{codesample2}
  14.656 +  [hooks]
  14.657 +  incoming.bugzilla = python:hgext.bugzilla.hook
  14.658 +\end{codesample2}
  14.659 +
  14.660 +Because of the specialised nature of this hook, and because Bugzilla
  14.661 +was not written with this kind of integration in mind, configuring
  14.662 +this hook is a somewhat involved process.
  14.663 +
  14.664 +Before you begin, you must install the MySQL bindings for Python on
  14.665 +the host(s) where you'll be running the hook.  If this is not
  14.666 +available as a binary package for your system, you can download it
  14.667 +from~\cite{web:mysql-python}.
  14.668 +
  14.669 +Configuration information for this hook lives in the
  14.670 +\rcsection{bugzilla} section of your \hgrc.
  14.671 +\begin{itemize}
  14.672 +\item[\rcitem{bugzilla}{version}] The version of Bugzilla installed on
  14.673 +  the server.  The database schema that Bugzilla uses changes
  14.674 +  occasionally, so this hook has to know exactly which schema to use.
  14.675 +  At the moment, the only version supported is \texttt{2.16}.
  14.676 +\item[\rcitem{bugzilla}{host}] The hostname of the MySQL server that
  14.677 +  stores your Bugzilla data.  The database must be configured to allow
  14.678 +  connections from whatever host you are running the \hook{bugzilla}
  14.679 +  hook on.
  14.680 +\item[\rcitem{bugzilla}{user}] The username with which to connect to
  14.681 +  the MySQL server.  The database must be configured to allow this
  14.682 +  user to connect from whatever host you are running the
  14.683 +  \hook{bugzilla} hook on.  This user must be able to access and
  14.684 +  modify Bugzilla tables.  The default value of this item is
  14.685 +  \texttt{bugs}, which is the standard name of the Bugzilla user in a
  14.686 +  MySQL database.
  14.687 +\item[\rcitem{bugzilla}{password}] The MySQL password for the user you
  14.688 +  configured above.  This is stored as plain text, so you should make
  14.689 +  sure that unauthorised users cannot read the \hgrc\ file where you
  14.690 +  store this information.
  14.691 +\item[\rcitem{bugzilla}{db}] The name of the Bugzilla database on the
  14.692 +  MySQL server.  The default value of this item is \texttt{bugs},
  14.693 +  which is the standard name of the MySQL database where Bugzilla
  14.694 +  stores its data.
  14.695 +\item[\rcitem{bugzilla}{notify}] If you want Bugzilla to send out a
  14.696 +  notification email to subscribers after this hook has added a
  14.697 +  comment to a bug, you will need this hook to run a command whenever
  14.698 +  it updates the database.  The command to run depends on where you
  14.699 +  have installed Bugzilla, but it will typically look something like
  14.700 +  this, if you have Bugzilla installed in
  14.701 +  \dirname{/var/www/html/bugzilla}:
  14.702 +  \begin{codesample4}
  14.703 +    cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com
  14.704 +  \end{codesample4}
  14.705 +  The Bugzilla \texttt{processmail} program expects to be given a
  14.706 +  bug~ID (the hook replaces ``\texttt{\%s}'' with the bug~ID) and an
  14.707 +  email address.  It also expects to be able to write to some files in
  14.708 +  the directory that it runs in.  If Bugzilla and this hook are not
  14.709 +  installed on the same machine, you will need to find a way to run
  14.710 +  \texttt{processmail} on the server where Bugzilla is installed.
  14.711 +\end{itemize}
  14.712 +
  14.713 +\subsubsection{Mapping committer names to Bugzilla user names}
  14.714 +
  14.715 +By default, the \hgext{bugzilla} hook tries to use the email address
  14.716 +of a changeset's committer as the Bugzilla user name with which to
  14.717 +update a bug.  If this does not suit your needs, you can map committer
  14.718 +email addresses to Bugzilla user names using a \rcsection{usermap}
  14.719 +section.
  14.720 +
  14.721 +Each item in the \rcsection{usermap} section contains an email address
  14.722 +on the left, and a Bugzilla user name on the right.
  14.723 +\begin{codesample2}
  14.724 +  [usermap]
  14.725 +  jane.user@example.com = jane
  14.726 +\end{codesample2}
  14.727 +You can either keep the \rcsection{usermap} data in a normal \hgrc, or
  14.728 +tell the \hgext{bugzilla} hook to read the information from an
  14.729 +external \filename{usermap} file.  In the latter case, you can store
  14.730 +\filename{usermap} data by itself in (for example) a user-modifiable
  14.731 +repository.  This makes it possible to let your users maintain their
  14.732 +own \rcitem{bugzilla}{usermap} entries.  The main \hgrc\ file might
  14.733 +look like this:
  14.734 +\begin{codesample2}
  14.735 +  # regular hgrc file refers to external usermap file
  14.736 +  [bugzilla]
  14.737 +  usermap = /home/hg/repos/userdata/bugzilla-usermap.conf
  14.738 +\end{codesample2}
  14.739 +While the \filename{usermap} file that it refers to might look like
  14.740 +this:
  14.741 +\begin{codesample2}
  14.742 +  # bugzilla-usermap.conf - inside a hg repository
  14.743 +  [usermap]
  14.744 +  stephanie@example.com = steph
  14.745 +\end{codesample2}
  14.746 +
  14.747 +\subsubsection{Configuring the text that gets added to a bug}
  14.748 +
  14.749 +You can configure the text that this hook adds as a comment; you
  14.750 +specify it in the form of a Mercurial template.  Several \hgrc\
  14.751 +entries (still in the \rcsection{bugzilla} section) control this
  14.752 +behaviour.
  14.753 +\begin{itemize}
  14.754 +\item[\texttt{strip}] The number of leading path elements to strip
  14.755 +  from a repository's path name to construct a partial path for a URL.
  14.756 +  For example, if the repositories on your server live under
  14.757 +  \dirname{/home/hg/repos}, and you have a repository whose path is
  14.758 +  \dirname{/home/hg/repos/app/tests}, then setting \texttt{strip} to
  14.759 +  \texttt{4} will give a partial path of \dirname{app/tests}.  The
  14.760 +  hook will make this partial path available when expanding a
  14.761 +  template, as \texttt{webroot}.
  14.762 +\item[\texttt{template}] The text of the template to use.  In addition
  14.763 +  to the usual changeset-related variables, this template can use
  14.764 +  \texttt{hgweb} (the value of the \texttt{hgweb} configuration item
  14.765 +  above) and \texttt{webroot} (the path constructed using
  14.766 +  \texttt{strip} above).
  14.767 +\end{itemize}
  14.768 +
  14.769 +In addition, you can add a \rcitem{web}{baseurl} item to the
  14.770 +\rcsection{web} section of your \hgrc.  The \hgext{bugzilla} hook will
  14.771 +make this available when expanding a template, as the base string to
  14.772 +use when constructing a URL that will let users browse from a Bugzilla
  14.773 +comment to view a changeset.  Example:
  14.774 +\begin{codesample2}
  14.775 +  [web]
  14.776 +  baseurl = http://hg.domain.com/
  14.777 +\end{codesample2}
  14.778 +
  14.779 +Here is an example set of \hgext{bugzilla} hook config information.
  14.780 +\begin{codesample2}
  14.781 +  [bugzilla]
  14.782 +  host = bugzilla.example.com
  14.783 +  password = mypassword
  14.784 +  version = 2.16
  14.785 +  # server-side repos live in /home/hg/repos, so strip 4 leading
  14.786 +  # separators
  14.787 +  strip = 4
  14.788 +  hgweb = http://hg.example.com/
  14.789 +  usermap = /home/hg/repos/notify/bugzilla.conf
  14.790 +  template = Changeset \{node|short\}, made by \{author\} in the \{webroot\}
  14.791 +    repo, refers to this bug.\\nFor complete details, see 
  14.792 +    \{hgweb\}\{webroot\}?cmd=changeset;node=\{node|short\}\\nChangeset
  14.793 +    description:\\n\\t\{desc|tabindent\}
  14.794 +\end{codesample2}
  14.795 +
  14.796 +\subsubsection{Testing and troubleshooting}
  14.797 +
  14.798 +The most common problems with configuring the \hgext{bugzilla} hook
  14.799 +relate to running Bugzilla's \filename{processmail} script and mapping
  14.800 +committer names to user names.
  14.801 +
  14.802 +Recall from section~\ref{sec:hook:bugzilla:config} above that the user
  14.803 +that runs the Mercurial process on the server is also the one that
  14.804 +will run the \filename{processmail} script.  The
  14.805 +\filename{processmail} script sometimes causes Bugzilla to write to
  14.806 +files in its configuration directory, and Bugzilla's configuration
  14.807 +files are usually owned by the user that your web server runs under.
  14.808 +
  14.809 +You can cause \filename{processmail} to be run with the suitable
  14.810 +user's identity using the \command{sudo} command.  Here is an example
  14.811 +entry for a \filename{sudoers} file.
  14.812 +\begin{codesample2}
  14.813 +  hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s
  14.814 +\end{codesample2}
  14.815 +This allows the \texttt{hg\_user} user to run a
  14.816 +\filename{processmail-wrapper} program under the identity of
  14.817 +\texttt{httpd\_user}.
  14.818 +
  14.819 +This indirection through a wrapper script is necessary, because
  14.820 +\filename{processmail} expects to be run with its current directory
  14.821 +set to wherever you installed Bugzilla; you can't specify that kind of
  14.822 +constraint in a \filename{sudoers} file.  The contents of the wrapper
  14.823 +script are simple:
  14.824 +\begin{codesample2}
  14.825 +  #!/bin/sh
  14.826 +  cd `dirname $0` && ./processmail "$1" nobody@example.com
  14.827 +\end{codesample2}
  14.828 +It doesn't seem to matter what email address you pass to
  14.829 +\filename{processmail}.
  14.830 +
  14.831 +If your \rcsection{usermap} is not set up correctly, users will see an
  14.832 +error message from the \hgext{bugzilla} hook when they push changes
  14.833 +to the server.  The error message will look like this:
  14.834 +\begin{codesample2}
  14.835 +  cannot find bugzilla user id for john.q.public@example.com
  14.836 +\end{codesample2}
  14.837 +What this means is that the committer's address,
  14.838 +\texttt{john.q.public@example.com}, is not a valid Bugzilla user name,
  14.839 +nor does it have an entry in your \rcsection{usermap} that maps it to
  14.840 +a valid Bugzilla user name.
  14.841 +
  14.842 +\subsection{\hgext{notify}---send email notifications}
  14.843 +
  14.844 +Although Mercurial's built-in web server provides RSS feeds of changes
  14.845 +in every repository, many people prefer to receive change
  14.846 +notifications via email.  The \hgext{notify} hook lets you send out
  14.847 +notifications to a set of email addresses whenever changesets arrive
  14.848 +that those subscribers are interested in.
  14.849 +
  14.850 +As with the \hgext{bugzilla} hook, the \hgext{notify} hook is
  14.851 +template-driven, so you can customise the contents of the notification
  14.852 +messages that it sends.
  14.853 +
  14.854 +By default, the \hgext{notify} hook includes a diff of every changeset
  14.855 +that it sends out; you can limit the size of the diff, or turn this
  14.856 +feature off entirely.  It is useful for letting subscribers review
  14.857 +changes immediately, rather than clicking to follow a URL.
  14.858 +
  14.859 +\subsubsection{Configuring the \hgext{notify} hook}
  14.860 +
  14.861 +You can set up the \hgext{notify} hook to send one email message per
  14.862 +incoming changeset, or one per incoming group of changesets (all those
  14.863 +that arrived in a single pull or push).
  14.864 +\begin{codesample2}
  14.865 +  [hooks]
  14.866 +  # send one email per group of changes
  14.867 +  changegroup.notify = python:hgext.notify.hook
  14.868 +  # send one email per change
  14.869 +  incoming.notify = python:hgext.notify.hook
  14.870 +\end{codesample2}
  14.871 +
  14.872 +Configuration information for this hook lives in the
  14.873 +\rcsection{notify} section of a \hgrc\ file.
  14.874 +\begin{itemize}
  14.875 +\item[\rcitem{notify}{test}] By default, this hook does not send out
  14.876 +  email at all; instead, it prints the message that it \emph{would}
  14.877 +  send.  Set this item to \texttt{false} to allow email to be sent.
  14.878 +  The reason that sending of email is turned off by default is that it
  14.879 +  takes several tries to configure this extension exactly as you would
  14.880 +  like, and it would be bad form to spam subscribers with a number of
  14.881 +  ``broken'' notifications while you debug your configuration.
  14.882 +\item[\rcitem{notify}{config}] The path to a configuration file that
  14.883 +  contains subscription information.  This is kept separate from the
  14.884 +  main \hgrc\ so that you can maintain it in a repository of its own.
  14.885 +  People can then clone that repository, update their subscriptions,
  14.886 +  and push the changes back to your server.
  14.887 +\item[\rcitem{notify}{strip}] The number of leading path separator
  14.888 +  characters to strip from a repository's path, when deciding whether
  14.889 +  a repository has subscribers.  For example, if the repositories on
  14.890 +  your server live in \dirname{/home/hg/repos}, and \hgext{notify} is
  14.891 +  considering a repository named \dirname{/home/hg/repos/shared/test},
  14.892 +  setting \rcitem{notify}{strip} to \texttt{4} will cause
  14.893 +  \hgext{notify} to trim the path it considers down to
  14.894 +  \dirname{shared/test}, and it will match subscribers against that.
  14.895 +\item[\rcitem{notify}{template}] The template text to use when sending
  14.896 +  messages.  This specifies both the contents of the message header
  14.897 +  and its body.
  14.898 +\item[\rcitem{notify}{maxdiff}] The maximum number of lines of diff
  14.899 +  data to append to the end of a message.  If a diff is longer than
  14.900 +  this, it is truncated.  By default, this is set to 300.  Set this to
  14.901 +  \texttt{0} to omit diffs from notification emails.
  14.902 +\item[\rcitem{notify}{sources}] A list of sources of changesets to
  14.903 +  consider.  This lets you limit \hgext{notify} to only sending out
  14.904 +  email about changes that remote users pushed into this repository
  14.905 +  via a server, for example.  See section~\ref{sec:hook:sources} for
  14.906 +  the sources you can specify here.
  14.907 +\end{itemize}
  14.908 +
  14.909 +If you set the \rcitem{web}{baseurl} item in the \rcsection{web}
  14.910 +section, you can use it in a template; it will be available as
  14.911 +\texttt{webroot}.
  14.912 +
  14.913 +Here is an example set of \hgext{notify} configuration information.
  14.914 +\begin{codesample2}
  14.915 +  [notify]
  14.916 +  # really send email
  14.917 +  test = false
  14.918 +  # subscriber data lives in the notify repo
  14.919 +  config = /home/hg/repos/notify/notify.conf
  14.920 +  # repos live in /home/hg/repos on server, so strip 4 "/" chars
  14.921 +  strip = 4
  14.922 +  template = X-Hg-Repo: \{webroot\}
  14.923 +    Subject: \{webroot\}: \{desc|firstline|strip\}
  14.924 +    From: \{author\}
  14.925 +
  14.926 +    changeset \{node|short\} in \{root\}
  14.927 +    details: \{baseurl\}\{webroot\}?cmd=changeset;node=\{node|short\}
  14.928 +    description:
  14.929 +      \{desc|tabindent|strip\}
  14.930 +
  14.931 +  [web]
  14.932 +  baseurl = http://hg.example.com/
  14.933 +\end{codesample2}
  14.934 +
  14.935 +This will produce a message that looks like the following:
  14.936 +\begin{codesample2}
  14.937 +  X-Hg-Repo: tests/slave
  14.938 +  Subject: tests/slave: Handle error case when slave has no buffers
  14.939 +  Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
  14.940 +
  14.941 +  changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
  14.942 +  details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
  14.943 +  description:
  14.944 +          Handle error case when slave has no buffers
  14.945 +  diffs (54 lines):
  14.946 +
  14.947 +  diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
  14.948 +  --- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
  14.949 +  +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
  14.950 +  @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h)
  14.951 +  [...snip...]
  14.952 +\end{codesample2}
  14.953 +
  14.954 +\subsubsection{Testing and troubleshooting}
  14.955 +
  14.956 +Do not forget that by default, the \hgext{notify} extension \emph{will
  14.957 +  not send any mail} until you explicitly configure it to do so, by
  14.958 +setting \rcitem{notify}{test} to \texttt{false}.  Until you do that,
  14.959 +it simply prints the message it \emph{would} send.
  14.960 +
  14.961 +\section{Information for writers of hooks}
  14.962 +\label{sec:hook:ref}
  14.963 +
  14.964 +\subsection{In-process hook execution}
  14.965 +
  14.966 +An in-process hook is called with arguments of the following form:
  14.967 +\begin{codesample2}
  14.968 +  def myhook(ui, repo, **kwargs):
  14.969 +      pass
  14.970 +\end{codesample2}
  14.971 +The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
  14.972 +The \texttt{repo} parameter is a
  14.973 +\pymodclass{mercurial.localrepo}{localrepository} object.  The
  14.974 +names and values of the \texttt{**kwargs} parameters depend on the
  14.975 +hook being invoked, with the following common features:
  14.976 +\begin{itemize}
  14.977 +\item If a parameter is named \texttt{node} or
  14.978 +  \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
  14.979 +  The empty string is used to represent ``null changeset ID'' instead
  14.980 +  of a string of zeroes.
  14.981 +\item If a parameter is named \texttt{url}, it will contain the URL of
  14.982 +  a remote repository, if that can be determined.
  14.983 +\item Boolean-valued parameters are represented as Python
  14.984 +  \texttt{bool} objects.
  14.985 +\end{itemize}
  14.986 +
  14.987 +An in-process hook is called without a change to the process's working
  14.988 +directory (unlike external hooks, which are run in the root of the
  14.989 +repository).  It must not change the process's working directory, or
  14.990 +it will cause any calls it makes into the Mercurial API to fail.
  14.991 +
  14.992 +If a hook returns a boolean ``false'' value, it is considered to have
  14.993 +succeeded.  If it returns a boolean ``true'' value or raises an
  14.994 +exception, it is considered to have failed.  A useful way to think of
  14.995 +the calling convention is ``tell me if you fail''.
  14.996 +
  14.997 +Note that changeset IDs are passed into Python hooks as hexadecimal
  14.998 +strings, not the binary hashes that Mercurial's APIs normally use.  To
  14.999 +convert a hash from hex to binary, use the
 14.1000 +\pymodfunc{mercurial.node}{bin} function.
 14.1001 +
 14.1002 +\subsection{External hook execution}
 14.1003 +
 14.1004 +An external hook is passed to the shell of the user running Mercurial.
 14.1005 +Features of that shell, such as variable substitution and command
 14.1006 +redirection, are available.  The hook is run in the root directory of
 14.1007 +the repository (unlike in-process hooks, which are run in the same
 14.1008 +directory that Mercurial was run in).
 14.1009 +
 14.1010 +Hook parameters are passed to the hook as environment variables.  Each
 14.1011 +environment variable's name is converted in upper case and prefixed
 14.1012 +with the string ``\texttt{HG\_}''.  For example, if the name of a
 14.1013 +parameter is ``\texttt{node}'', the name of the environment variable
 14.1014 +representing that parameter will be ``\texttt{HG\_NODE}''.
 14.1015 +
 14.1016 +A boolean parameter is represented as the string ``\texttt{1}'' for
 14.1017 +``true'', ``\texttt{0}'' for ``false''.  If an environment variable is
 14.1018 +named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
 14.1019 +contains a changeset ID represented as a hexadecimal string.  The
 14.1020 +empty string is used to represent ``null changeset ID'' instead of a
 14.1021 +string of zeroes.  If an environment variable is named
 14.1022 +\envar{HG\_URL}, it will contain the URL of a remote repository, if
 14.1023 +that can be determined.
 14.1024 +
 14.1025 +If a hook exits with a status of zero, it is considered to have
 14.1026 +succeeded.  If it exits with a non-zero status, it is considered to
 14.1027 +have failed.
 14.1028 +
 14.1029 +\subsection{Finding out where changesets come from}
 14.1030 +
 14.1031 +A hook that involves the transfer of changesets between a local
 14.1032 +repository and another may be able to find out information about the
 14.1033 +``far side''.  Mercurial knows \emph{how} changes are being
 14.1034 +transferred, and in many cases \emph{where} they are being transferred
 14.1035 +to or from.
 14.1036 +
 14.1037 +\subsubsection{Sources of changesets}
 14.1038 +\label{sec:hook:sources}
 14.1039 +
 14.1040 +Mercurial will tell a hook what means are, or were, used to transfer
 14.1041 +changesets between repositories.  This is provided by Mercurial in a
 14.1042 +Python parameter named \texttt{source}, or an environment variable named
 14.1043 +\envar{HG\_SOURCE}.
 14.1044 +
 14.1045 +\begin{itemize}
 14.1046 +\item[\texttt{serve}] Changesets are transferred to or from a remote
 14.1047 +  repository over http or ssh.
 14.1048 +\item[\texttt{pull}] Changesets are being transferred via a pull from
 14.1049 +  one repository into another.
 14.1050 +\item[\texttt{push}] Changesets are being transferred via a push from
 14.1051 +  one repository into another.
 14.1052 +\item[\texttt{bundle}] Changesets are being transferred to or from a
 14.1053 +  bundle.
 14.1054 +\end{itemize}
 14.1055 +
 14.1056 +\subsubsection{Where changes are going---remote repository URLs}
 14.1057 +\label{sec:hook:url}
 14.1058 +
 14.1059 +When possible, Mercurial will tell a hook the location of the ``far
 14.1060 +side'' of an activity that transfers changeset data between
 14.1061 +repositories.  This is provided by Mercurial in a Python parameter
 14.1062 +named \texttt{url}, or an environment variable named \envar{HG\_URL}.
 14.1063 +
 14.1064 +This information is not always known.  If a hook is invoked in a
 14.1065 +repository that is being served via http or ssh, Mercurial cannot tell
 14.1066 +where the remote repository is, but it may know where the client is
 14.1067 +connecting from.  In such cases, the URL will take one of the
 14.1068 +following forms:
 14.1069 +\begin{itemize}
 14.1070 +\item \texttt{remote:ssh:\emph{ip-address}}---remote ssh client, at
 14.1071 +  the given IP address.
 14.1072 +\item \texttt{remote:http:\emph{ip-address}}---remote http client, at
 14.1073 +  the given IP address.  If the client is using SSL, this will be of
 14.1074 +  the form \texttt{remote:https:\emph{ip-address}}.
 14.1075 +\item Empty---no information could be discovered about the remote
 14.1076 +  client.
 14.1077 +\end{itemize}
 14.1078 +
 14.1079 +\section{Hook reference}
 14.1080 +
 14.1081 +\subsection{\hook{changegroup}---after remote changesets added}
 14.1082 +\label{sec:hook:changegroup}
 14.1083 +
 14.1084 +This hook is run after a group of pre-existing changesets has been
 14.1085 +added to the repository, for example via a \hgcmd{pull} or
 14.1086 +\hgcmd{unbundle}.  This hook is run once per operation that added one
 14.1087 +or more changesets.  This is in contrast to the \hook{incoming} hook,
 14.1088 +which is run once per changeset, regardless of whether the changesets
 14.1089 +arrive in a group.
 14.1090 +
 14.1091 +Some possible uses for this hook include kicking off an automated
 14.1092 +build or test of the added changesets, updating a bug database, or
 14.1093 +notifying subscribers that a repository contains new changes.
 14.1094 +
 14.1095 +Parameters to this hook:
 14.1096 +\begin{itemize}
 14.1097 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
 14.1098 +  changeset in the group that was added.  All changesets between this
 14.1099 +  and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
 14.1100 +  a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
 14.1101 +\item[\texttt{source}] A string.  The source of these changes.  See
 14.1102 +  section~\ref{sec:hook:sources} for details.
 14.1103 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1104 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1105 +\end{itemize}
 14.1106 +
 14.1107 +See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
 14.1108 +\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
 14.1109 +\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
 14.1110 +
 14.1111 +\subsection{\hook{commit}---after a new changeset is created}
 14.1112 +\label{sec:hook:commit}
 14.1113 +
 14.1114 +This hook is run after a new changeset has been created.
 14.1115 +
 14.1116 +Parameters to this hook:
 14.1117 +\begin{itemize}
 14.1118 +\item[\texttt{node}] A changeset ID.  The changeset ID of the newly
 14.1119 +  committed changeset.
 14.1120 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
 14.1121 +  parent of the newly committed changeset.
 14.1122 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
 14.1123 +  parent of the newly committed changeset.
 14.1124 +\end{itemize}
 14.1125 +
 14.1126 +See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
 14.1127 +\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
 14.1128 +
 14.1129 +\subsection{\hook{incoming}---after one remote changeset is added}
 14.1130 +\label{sec:hook:incoming}
 14.1131 +
 14.1132 +This hook is run after a pre-existing changeset has been added to the
 14.1133 +repository, for example via a \hgcmd{push}.  If a group of changesets
 14.1134 +was added in a single operation, this hook is called once for each
 14.1135 +added changeset.
 14.1136 +
 14.1137 +You can use this hook for the same purposes as the \hook{changegroup}
 14.1138 +hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
 14.1139 +sometimes to run a hook once per group of changesets, while other
 14.1140 +times it's handier once per changeset.
 14.1141 +
 14.1142 +Parameters to this hook:
 14.1143 +\begin{itemize}
 14.1144 +\item[\texttt{node}] A changeset ID.  The ID of the newly added
 14.1145 +  changeset.
 14.1146 +\item[\texttt{source}] A string.  The source of these changes.  See
 14.1147 +  section~\ref{sec:hook:sources} for details.
 14.1148 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1149 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1150 +\end{itemize}
 14.1151 +
 14.1152 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
 14.1153 +
 14.1154 +\subsection{\hook{outgoing}---after changesets are propagated}
 14.1155 +\label{sec:hook:outgoing}
 14.1156 +
 14.1157 +This hook is run after a group of changesets has been propagated out
 14.1158 +of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
 14.1159 +command.
 14.1160 +
 14.1161 +One possible use for this hook is to notify administrators that
 14.1162 +changes have been pulled.
 14.1163 +
 14.1164 +Parameters to this hook:
 14.1165 +\begin{itemize}
 14.1166 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
 14.1167 +  changeset of the group that was sent.
 14.1168 +\item[\texttt{source}] A string.  The source of the of the operation
 14.1169 +  (see section~\ref{sec:hook:sources}).  If a remote client pulled
 14.1170 +  changes from this repository, \texttt{source} will be
 14.1171 +  \texttt{serve}.  If the client that obtained changes from this
 14.1172 +  repository was local, \texttt{source} will be \texttt{bundle},
 14.1173 +  \texttt{pull}, or \texttt{push}, depending on the operation the
 14.1174 +  client performed.
 14.1175 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1176 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1177 +\end{itemize}
 14.1178 +
 14.1179 +See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
 14.1180 +
 14.1181 +\subsection{\hook{prechangegroup}---before starting to add remote changesets}
 14.1182 +\label{sec:hook:prechangegroup}
 14.1183 +
 14.1184 +This controlling hook is run before Mercurial begins to add a group of
 14.1185 +changesets from another repository.
 14.1186 +
 14.1187 +This hook does not have any information about the changesets to be
 14.1188 +added, because it is run before transmission of those changesets is
 14.1189 +allowed to begin.  If this hook fails, the changesets will not be
 14.1190 +transmitted.
 14.1191 +
 14.1192 +One use for this hook is to prevent external changes from being added
 14.1193 +to a repository.  For example, you could use this to ``freeze'' a
 14.1194 +server-hosted branch temporarily or permanently so that users cannot
 14.1195 +push to it, while still allowing a local administrator to modify the
 14.1196 +repository.
 14.1197 +
 14.1198 +Parameters to this hook:
 14.1199 +\begin{itemize}
 14.1200 +\item[\texttt{source}] A string.  The source of these changes.  See
 14.1201 +  section~\ref{sec:hook:sources} for details.
 14.1202 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1203 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1204 +\end{itemize}
 14.1205 +
 14.1206 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
 14.1207 +\hook{incoming} (section~\ref{sec:hook:incoming}), ,
 14.1208 +\hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
 14.1209 +
 14.1210 +\subsection{\hook{precommit}---before starting to commit a changeset}
 14.1211 +\label{sec:hook:precommit}
 14.1212 +
 14.1213 +This hook is run before Mercurial begins to commit a new changeset.
 14.1214 +It is run before Mercurial has any of the metadata for the commit,
 14.1215 +such as the files to be committed, the commit message, or the commit
 14.1216 +date.
 14.1217 +
 14.1218 +One use for this hook is to disable the ability to commit new
 14.1219 +changesets, while still allowing incoming changesets.  Another is to
 14.1220 +run a build or test, and only allow the commit to begin if the build
 14.1221 +or test succeeds.
 14.1222 +
 14.1223 +Parameters to this hook:
 14.1224 +\begin{itemize}
 14.1225 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
 14.1226 +  parent of the working directory.
 14.1227 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
 14.1228 +  parent of the working directory.
 14.1229 +\end{itemize}
 14.1230 +If the commit proceeds, the parents of the working directory will
 14.1231 +become the parents of the new changeset.
 14.1232 +
 14.1233 +See also: \hook{commit} (section~\ref{sec:hook:commit}),
 14.1234 +\hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
 14.1235 +
 14.1236 +\subsection{\hook{preoutgoing}---before starting to propagate changesets}
 14.1237 +\label{sec:hook:preoutgoing}
 14.1238 +
 14.1239 +This hook is invoked before Mercurial knows the identities of the
 14.1240 +changesets to be transmitted.
 14.1241 +
 14.1242 +One use for this hook is to prevent changes from being transmitted to
 14.1243 +another repository.
 14.1244 +
 14.1245 +Parameters to this hook:
 14.1246 +\begin{itemize}
 14.1247 +\item[\texttt{source}] A string.  The source of the operation that is
 14.1248 +  attempting to obtain changes from this repository (see
 14.1249 +  section~\ref{sec:hook:sources}).  See the documentation for the
 14.1250 +  \texttt{source} parameter to the \hook{outgoing} hook, in
 14.1251 +  section~\ref{sec:hook:outgoing}, for possible values of this
 14.1252 +  parameter.
 14.1253 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1254 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1255 +\end{itemize}
 14.1256 +
 14.1257 +See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
 14.1258 +
 14.1259 +\subsection{\hook{pretag}---before tagging a changeset}
 14.1260 +\label{sec:hook:pretag}
 14.1261 +
 14.1262 +This controlling hook is run before a tag is created.  If the hook
 14.1263 +succeeds, creation of the tag proceeds.  If the hook fails, the tag is
 14.1264 +not created.
 14.1265 +
 14.1266 +Parameters to this hook:
 14.1267 +\begin{itemize}
 14.1268 +\item[\texttt{local}] A boolean.  Whether the tag is local to this
 14.1269 +  repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
 14.1270 +  managed by Mercurial (stored in \sfilename{.hgtags}).
 14.1271 +\item[\texttt{node}] A changeset ID.  The ID of the changeset to be tagged.
 14.1272 +\item[\texttt{tag}] A string.  The name of the tag to be created.
 14.1273 +\end{itemize}
 14.1274 +
 14.1275 +If the tag to be created is revision-controlled, the \hook{precommit}
 14.1276 +and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
 14.1277 +and~\ref{sec:hook:pretxncommit}) will also be run.
 14.1278 +
 14.1279 +See also: \hook{tag} (section~\ref{sec:hook:tag})
 14.1280 +
 14.1281 +\subsection{\hook{pretxnchangegroup}---before completing addition of
 14.1282 +  remote changesets}
 14.1283 +\label{sec:hook:pretxnchangegroup}
 14.1284 +
 14.1285 +This controlling hook is run before a transaction---that manages the
 14.1286 +addition of a group of new changesets from outside the
 14.1287 +repository---completes.  If the hook succeeds, the transaction
 14.1288 +completes, and all of the changesets become permanent within this
 14.1289 +repository.  If the hook fails, the transaction is rolled back, and
 14.1290 +the data for the changesets is erased.
 14.1291 +
 14.1292 +This hook can access the metadata associated with the almost-added
 14.1293 +changesets, but it should not do anything permanent with this data.
 14.1294 +It must also not modify the working directory.
 14.1295 +
 14.1296 +While this hook is running, if other Mercurial processes access this
 14.1297 +repository, they will be able to see the almost-added changesets as if
 14.1298 +they are permanent.  This may lead to race conditions if you do not
 14.1299 +take steps to avoid them.
 14.1300 +
 14.1301 +This hook can be used to automatically vet a group of changesets.  If
 14.1302 +the hook fails, all of the changesets are ``rejected'' when the
 14.1303 +transaction rolls back.
 14.1304 +
 14.1305 +Parameters to this hook:
 14.1306 +\begin{itemize}
 14.1307 +\item[\texttt{node}] A changeset ID.  The changeset ID of the first
 14.1308 +  changeset in the group that was added.  All changesets between this
 14.1309 +  and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
 14.1310 +  a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
 14.1311 +\item[\texttt{source}] A string.  The source of these changes.  See
 14.1312 +  section~\ref{sec:hook:sources} for details.
 14.1313 +\item[\texttt{url}] A URL.  The location of the remote repository, if
 14.1314 +  known.  See section~\ref{sec:hook:url} for more information.
 14.1315 +\end{itemize}
 14.1316 +
 14.1317 +See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
 14.1318 +\hook{incoming} (section~\ref{sec:hook:incoming}),
 14.1319 +\hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
 14.1320 +
 14.1321 +\subsection{\hook{pretxncommit}---before completing commit of new changeset}
 14.1322 +\label{sec:hook:pretxncommit}
 14.1323 +
 14.1324 +This controlling hook is run before a transaction---that manages a new
 14.1325 +commit---completes.  If the hook succeeds, the transaction completes
 14.1326 +and the changeset becomes permanent within this repository.  If the
 14.1327 +hook fails, the transaction is rolled back, and the commit data is
 14.1328 +erased.
 14.1329 +
 14.1330 +This hook can access the metadata associated with the almost-new
 14.1331 +changeset, but it should not do anything permanent with this data.  It
 14.1332 +must also not modify the working directory.
 14.1333 +
 14.1334 +While this hook is running, if other Mercurial processes access this
 14.1335 +repository, they will be able to see the almost-new changeset as if it
 14.1336 +is permanent.  This may lead to race conditions if you do not take
 14.1337 +steps to avoid them.
 14.1338 +
 14.1339 +Parameters to this hook:
 14.1340 +\begin{itemize}
 14.1341 +\item[\texttt{node}] A changeset ID.  The changeset ID of the newly
 14.1342 +  committed changeset.
 14.1343 +\item[\texttt{parent1}] A changeset ID.  The changeset ID of the first
 14.1344 +  parent of the newly committed changeset.
 14.1345 +\item[\texttt{parent2}] A changeset ID.  The changeset ID of the second
 14.1346 +  parent of the newly committed changeset.
 14.1347 +\end{itemize}
 14.1348 +
 14.1349 +See also: \hook{precommit} (section~\ref{sec:hook:precommit})
 14.1350 +
 14.1351 +\subsection{\hook{preupdate}---before updating or merging working directory}
 14.1352 +\label{sec:hook:preupdate}
 14.1353 +
 14.1354 +This controlling hook is run before an update or merge of the working
 14.1355 +directory begins.  It is run only if Mercurial's normal pre-update
 14.1356 +checks determine that the update or merge can proceed.  If the hook
 14.1357 +succeeds, the update or merge may proceed; if it fails, the update or
 14.1358 +merge does not start.
 14.1359 +
 14.1360 +Parameters to this hook:
 14.1361 +\begin{itemize}
 14.1362 +\item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
 14.1363 +  working directory is to be updated to.  If the working directory is
 14.1364 +  being merged, it will not change this parent.
 14.1365 +\item[\texttt{parent2}] A changeset ID.  Only set if the working
 14.1366 +  directory is being merged.  The ID of the revision that the working
 14.1367 +  directory is being merged with.
 14.1368 +\end{itemize}
 14.1369 +
 14.1370 +See also: \hook{update} (section~\ref{sec:hook:update})
 14.1371 +
 14.1372 +\subsection{\hook{tag}---after tagging a changeset}
 14.1373 +\label{sec:hook:tag}
 14.1374 +
 14.1375 +This hook is run after a tag has been created.
 14.1376 +
 14.1377 +Parameters to this hook:
 14.1378 +\begin{itemize}
 14.1379 +\item[\texttt{local}] A boolean.  Whether the new tag is local to this
 14.1380 +  repository instance (i.e.~stored in \sfilename{.hg/localtags}) or
 14.1381 +  managed by Mercurial (stored in \sfilename{.hgtags}).
 14.1382 +\item[\texttt{node}] A changeset ID.  The ID of the changeset that was
 14.1383 +  tagged.
 14.1384 +\item[\texttt{tag}] A string.  The name of the tag that was created.
 14.1385 +\end{itemize}
 14.1386 +
 14.1387 +If the created tag is revision-controlled, the \hook{commit} hook
 14.1388 +(section~\ref{sec:hook:commit}) is run before this hook.
 14.1389 +
 14.1390 +See also: \hook{pretag} (section~\ref{sec:hook:pretag})
 14.1391 +
 14.1392 +\subsection{\hook{update}---after updating or merging working directory}
 14.1393 +\label{sec:hook:update}
 14.1394 +
 14.1395 +This hook is run after an update or merge of the working directory
 14.1396 +completes.  Since a merge can fail (if the external \command{hgmerge}
 14.1397 +command fails to resolve conflicts in a file), this hook communicates
 14.1398 +whether the update or merge completed cleanly.
 14.1399 +
 14.1400 +\begin{itemize}
 14.1401 +\item[\texttt{error}] A boolean.  Indicates whether the update or
 14.1402 +  merge completed successfully.
 14.1403 +\item[\texttt{parent1}] A changeset ID.  The ID of the parent that the
 14.1404 +  working directory was updated to.  If the working directory was
 14.1405 +  merged, it will not have changed this parent.
 14.1406 +\item[\texttt{parent2}] A changeset ID.  Only set if the working
 14.1407 +  directory was merged.  The ID of the revision that the working
 14.1408 +  directory was merged with.
 14.1409 +\end{itemize}
 14.1410 +
 14.1411 +See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
 14.1412 +
 14.1413 +%%% Local Variables: 
 14.1414 +%%% mode: latex
 14.1415 +%%% TeX-master: "00book"
 14.1416 +%%% End: 

    15.1 Binary file es/kdiff3.png has changed

    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/es/license.tex	Sat Oct 18 15:44:41 2008 -0500
    16.3 @@ -0,0 +1,138 @@
    16.4 +\chapter{Open Publication License}
    16.5 +\label{cha:opl}
    16.6 +
    16.7 +Version 1.0, 8 June 1999
    16.8 +
    16.9 +\section{Requirements on both unmodified and modified versions}
   16.10 +
   16.11 +The Open Publication works may be reproduced and distributed in whole
   16.12 +or in part, in any medium physical or electronic, provided that the
   16.13 +terms of this license are adhered to, and that this license or an
   16.14 +incorporation of it by reference (with any options elected by the
   16.15 +author(s) and/or publisher) is displayed in the reproduction.
   16.16 +
   16.17 +Proper form for an incorporation by reference is as follows:
   16.18 +
   16.19 +\begin{quote}
   16.20 +  Copyright (c) \emph{year} by \emph{author's name or designee}. This
   16.21 +  material may be distributed only subject to the terms and conditions
   16.22 +  set forth in the Open Publication License, v\emph{x.y} or later (the
   16.23 +  latest version is presently available at
   16.24 +  \url{http://www.opencontent.org/openpub/}).
   16.25 +\end{quote}
   16.26 +
   16.27 +The reference must be immediately followed with any options elected by
   16.28 +the author(s) and/or publisher of the document (see
   16.29 +section~\ref{sec:opl:options}).
   16.30 +
   16.31 +Commercial redistribution of Open Publication-licensed material is
   16.32 +permitted.
   16.33 +
   16.34 +Any publication in standard (paper) book form shall require the
   16.35 +citation of the original publisher and author. The publisher and
   16.36 +author's names shall appear on all outer surfaces of the book. On all
   16.37 +outer surfaces of the book the original publisher's name shall be as
   16.38 +large as the title of the work and cited as possessive with respect to
   16.39 +the title.
   16.40 +
   16.41 +\section{Copyright}
   16.42 +
   16.43 +The copyright to each Open Publication is owned by its author(s) or
   16.44 +designee.
   16.45 +
   16.46 +\section{Scope of license}
   16.47 +
   16.48 +The following license terms apply to all Open Publication works,
   16.49 +unless otherwise explicitly stated in the document.
   16.50 +
   16.51 +Mere aggregation of Open Publication works or a portion of an Open
   16.52 +Publication work with other works or programs on the same media shall
   16.53 +not cause this license to apply to those other works. The aggregate
   16.54 +work shall contain a notice specifying the inclusion of the Open
   16.55 +Publication material and appropriate copyright notice.
   16.56 +
   16.57 +\textbf{Severability}. If any part of this license is found to be
   16.58 +unenforceable in any jurisdiction, the remaining portions of the
   16.59 +license remain in force.
   16.60 +
   16.61 +\textbf{No warranty}. Open Publication works are licensed and provided
   16.62 +``as is'' without warranty of any kind, express or implied, including,
   16.63 +but not limited to, the implied warranties of merchantability and
   16.64 +fitness for a particular purpose or a warranty of non-infringement.
   16.65 +
   16.66 +\section{Requirements on modified works}
   16.67 +
   16.68 +All modified versions of documents covered by this license, including
   16.69 +translations, anthologies, compilations and partial documents, must
   16.70 +meet the following requirements:
   16.71 +
   16.72 +\begin{enumerate}
   16.73 +\item The modified version must be labeled as such.
   16.74 +\item The person making the modifications must be identified and the
   16.75 +  modifications dated.
   16.76 +\item Acknowledgement of the original author and publisher if
   16.77 +  applicable must be retained according to normal academic citation
   16.78 +  practices.
   16.79 +\item The location of the original unmodified document must be
   16.80 +  identified.
   16.81 +\item The original author's (or authors') name(s) may not be used to
   16.82 +  assert or imply endorsement of the resulting document without the
   16.83 +  original author's (or authors') permission.
   16.84 +\end{enumerate}
   16.85 +
   16.86 +\section{Good-practice recommendations}
   16.87 +
   16.88 +In addition to the requirements of this license, it is requested from
   16.89 +and strongly recommended of redistributors that:
   16.90 +
   16.91 +\begin{enumerate}
   16.92 +\item If you are distributing Open Publication works on hardcopy or
   16.93 +  CD-ROM, you provide email notification to the authors of your intent
   16.94 +  to redistribute at least thirty days before your manuscript or media
   16.95 +  freeze, to give the authors time to provide updated documents. This
   16.96 +  notification should describe modifications, if any, made to the
   16.97 +  document.
   16.98 +\item All substantive modifications (including deletions) be either
   16.99 +  clearly marked up in the document or else described in an attachment
  16.100 +  to the document.
  16.101 +\item Finally, while it is not mandatory under this license, it is
  16.102 +  considered good form to offer a free copy of any hardcopy and CD-ROM
  16.103 +  expression of an Open Publication-licensed work to its author(s).
  16.104 +\end{enumerate}
  16.105 +
  16.106 +\section{License options}
  16.107 +\label{sec:opl:options}
  16.108 +
  16.109 +The author(s) and/or publisher of an Open Publication-licensed
  16.110 +document may elect certain options by appending language to the
  16.111 +reference to or copy of the license. These options are considered part
  16.112 +of the license instance and must be included with the license (or its
  16.113 +incorporation by reference) in derived works.
  16.114 +
  16.115 +\begin{enumerate}[A]
  16.116 +\item To prohibit distribution of substantively modified versions
  16.117 +  without the explicit permission of the author(s). ``Substantive
  16.118 +  modification'' is defined as a change to the semantic content of the
  16.119 +  document, and excludes mere changes in format or typographical
  16.120 +  corrections.
  16.121 +
  16.122 +  To accomplish this, add the phrase ``Distribution of substantively
  16.123 +  modified versions of this document is prohibited without the
  16.124 +  explicit permission of the copyright holder.'' to the license
  16.125 +  reference or copy.
  16.126 +
  16.127 +\item To prohibit any publication of this work or derivative works in
  16.128 +  whole or in part in standard (paper) book form for commercial
  16.129 +  purposes is prohibited unless prior permission is obtained from the
  16.130 +  copyright holder.
  16.131 +
  16.132 +  To accomplish this, add the phrase ``Distribution of the work or
  16.133 +  derivative of the work in any standard (paper) book form is
  16.134 +  prohibited unless prior permission is obtained from the copyright
  16.135 +  holder.'' to the license reference or copy.
  16.136 +\end{enumerate}
  16.137 +
  16.138 +%%% Local Variables: 
  16.139 +%%% mode: latex
  16.140 +%%% TeX-master: "00book"
  16.141 +%%% End: 

    17.1 --- a/es/mq-collab.tex	Sat Oct 18 14:35:43 2008 -0500
    17.2 +++ b/es/mq-collab.tex	Sat Oct 18 15:44:41 2008 -0500
    17.3 @@ -0,0 +1,393 @@
    17.4 +\chapter{Advanced uses of Mercurial Queues}
    17.5 +\label{chap:mq-collab}
    17.6 +
    17.7 +While it's easy to pick up straightforward uses of Mercurial Queues,
    17.8 +use of a little discipline and some of MQ's less frequently used
    17.9 +capabilities makes it possible to work in complicated development
   17.10 +environments.
   17.11 +
   17.12 +In this chapter, I will use as an example a technique I have used to
   17.13 +manage the development of an Infiniband device driver for the Linux
   17.14 +kernel.  The driver in question is large (at least as drivers go),
   17.15 +with 25,000 lines of code spread across 35 source files.  It is
   17.16 +maintained by a small team of developers.
   17.17 +
   17.18 +While much of the material in this chapter is specific to Linux, the
   17.19 +same principles apply to any code base for which you're not the
   17.20 +primary owner, and upon which you need to do a lot of development.
   17.21 +
   17.22 +\section{The problem of many targets}
   17.23 +
   17.24 +The Linux kernel changes rapidly, and has never been internally
   17.25 +stable; developers frequently make drastic changes between releases.
   17.26 +This means that a version of the driver that works well with a
   17.27 +particular released version of the kernel will not even \emph{compile}
   17.28 +correctly against, typically, any other version.
   17.29 +
   17.30 +To maintain a driver, we have to keep a number of distinct versions of
   17.31 +Linux in mind.
   17.32 +\begin{itemize}
   17.33 +\item One target is the main Linux kernel development tree.
   17.34 +  Maintenance of the code is in this case partly shared by other
   17.35 +  developers in the kernel community, who make ``drive-by''
   17.36 +  modifications to the driver as they develop and refine kernel
   17.37 +  subsystems.
   17.38 +\item We also maintain a number of ``backports'' to older versions of
   17.39 +  the Linux kernel, to support the needs of customers who are running
   17.40 +  older Linux distributions that do not incorporate our drivers.  (To
   17.41 +  \emph{backport} a piece of code is to modify it to work in an older
   17.42 +  version of its target environment than the version it was developed
   17.43 +  for.)
   17.44 +\item Finally, we make software releases on a schedule that is
   17.45 +  necessarily not aligned with those used by Linux distributors and
   17.46 +  kernel developers, so that we can deliver new features to customers
   17.47 +  without forcing them to upgrade their entire kernels or
   17.48 +  distributions.
   17.49 +\end{itemize}
   17.50 +
   17.51 +\subsection{Tempting approaches that don't work well}
   17.52 +
   17.53 +There are two ``standard'' ways to maintain a piece of software that
   17.54 +has to target many different environments.
   17.55 +
   17.56 +The first is to maintain a number of branches, each intended for a
   17.57 +single target.  The trouble with this approach is that you must
   17.58 +maintain iron discipline in the flow of changes between repositories.
   17.59 +A new feature or bug fix must start life in a ``pristine'' repository,
   17.60 +then percolate out to every backport repository.  Backport changes are
   17.61 +more limited in the branches they should propagate to; a backport
   17.62 +change that is applied to a branch where it doesn't belong will
   17.63 +probably stop the driver from compiling.
   17.64 +
   17.65 +The second is to maintain a single source tree filled with conditional
   17.66 +statements that turn chunks of code on or off depending on the
   17.67 +intended target.  Because these ``ifdefs'' are not allowed in the
   17.68 +Linux kernel tree, a manual or automatic process must be followed to
   17.69 +strip them out and yield a clean tree.  A code base maintained in this
   17.70 +fashion rapidly becomes a rat's nest of conditional blocks that are
   17.71 +difficult to understand and maintain.
   17.72 +
   17.73 +Neither of these approaches is well suited to a situation where you
   17.74 +don't ``own'' the canonical copy of a source tree.  In the case of a
   17.75 +Linux driver that is distributed with the standard kernel, Linus's
   17.76 +tree contains the copy of the code that will be treated by the world
   17.77 +as canonical.  The upstream version of ``my'' driver can be modified
   17.78 +by people I don't know, without me even finding out about it until
   17.79 +after the changes show up in Linus's tree.  
   17.80 +
   17.81 +These approaches have the added weakness of making it difficult to
   17.82 +generate well-formed patches to submit upstream.
   17.83 +
   17.84 +In principle, Mercurial Queues seems like a good candidate to manage a
   17.85 +development scenario such as the above.  While this is indeed the
   17.86 +case, MQ contains a few added features that make the job more
   17.87 +pleasant.
   17.88 +
   17.89 +\section{Conditionally applying patches with 
   17.90 +  guards}
   17.91 +
   17.92 +Perhaps the best way to maintain sanity with so many targets is to be
   17.93 +able to choose specific patches to apply for a given situation.  MQ
   17.94 +provides a feature called ``guards'' (which originates with quilt's
   17.95 +\texttt{guards} command) that does just this.  To start off, let's
   17.96 +create a simple repository for experimenting in.
   17.97 +\interaction{mq.guards.init}
   17.98 +This gives us a tiny repository that contains two patches that don't
   17.99 +have any dependencies on each other, because they touch different files.
  17.100 +
  17.101 +The idea behind conditional application is that you can ``tag'' a
  17.102 +patch with a \emph{guard}, which is simply a text string of your
  17.103 +choosing, then tell MQ to select specific guards to use when applying
  17.104 +patches.  MQ will then either apply, or skip over, a guarded patch,
  17.105 +depending on the guards that you have selected.
  17.106 +
  17.107 +A patch can have an arbitrary number of guards;
  17.108 +each one is \emph{positive} (``apply this patch if this guard is
  17.109 +selected'') or \emph{negative} (``skip this patch if this guard is
  17.110 +selected'').  A patch with no guards is always applied.
  17.111 +
  17.112 +\section{Controlling the guards on a patch}
  17.113 +
  17.114 +The \hgxcmd{mq}{qguard} command lets you determine which guards should
  17.115 +apply to a patch, or display the guards that are already in effect.
  17.116 +Without any arguments, it displays the guards on the current topmost
  17.117 +patch.
  17.118 +\interaction{mq.guards.qguard}
  17.119 +To set a positive guard on a patch, prefix the name of the guard with
  17.120 +a ``\texttt{+}''.
  17.121 +\interaction{mq.guards.qguard.pos}
  17.122 +To set a negative guard on a patch, prefix the name of the guard with
  17.123 +a ``\texttt{-}''.
  17.124 +\interaction{mq.guards.qguard.neg}
  17.125 +
  17.126 +\begin{note}
  17.127 +  The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it
  17.128 +  doesn't \emph{modify} them.  What this means is that if you run
  17.129 +  \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on
  17.130 +  the same patch, the \emph{only} guard that will be set on it
  17.131 +  afterwards is \texttt{+c}.
  17.132 +\end{note}
  17.133 +
  17.134 +Mercurial stores guards in the \sfilename{series} file; the form in
  17.135 +which they are stored is easy both to understand and to edit by hand.
  17.136 +(In other words, you don't have to use the \hgxcmd{mq}{qguard} command if
  17.137 +you don't want to; it's okay to simply edit the \sfilename{series}
  17.138 +file.)
  17.139 +\interaction{mq.guards.series}
  17.140 +
  17.141 +\section{Selecting the guards to use}
  17.142 +
  17.143 +The \hgxcmd{mq}{qselect} command determines which guards are active at a
  17.144 +given time.  The effect of this is to determine which patches MQ will
  17.145 +apply the next time you run \hgxcmd{mq}{qpush}.  It has no other effect; in
  17.146 +particular, it doesn't do anything to patches that are already
  17.147 +applied.
  17.148 +
  17.149 +With no arguments, the \hgxcmd{mq}{qselect} command lists the guards
  17.150 +currently in effect, one per line of output.  Each argument is treated
  17.151 +as the name of a guard to apply.
  17.152 +\interaction{mq.guards.qselect.foo}
  17.153 +In case you're interested, the currently selected guards are stored in
  17.154 +the \sfilename{guards} file.
  17.155 +\interaction{mq.guards.qselect.cat}
  17.156 +We can see the effect the selected guards have when we run
  17.157 +\hgxcmd{mq}{qpush}.
  17.158 +\interaction{mq.guards.qselect.qpush}
  17.159 +
  17.160 +A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}''
  17.161 +character.  The name of a guard must not contain white space, but most
  17.162 +other characters are acceptable.  If you try to use a guard with an
  17.163 +invalid name, MQ will complain:
  17.164 +\interaction{mq.guards.qselect.error} 
  17.165 +Changing the selected guards changes the patches that are applied.
  17.166 +\interaction{mq.guards.qselect.quux} 
  17.167 +You can see in the example below that negative guards take precedence
  17.168 +over positive guards.
  17.169 +\interaction{mq.guards.qselect.foobar}
  17.170 +
  17.171 +\section{MQ's rules for applying patches}
  17.172 +
  17.173 +The rules that MQ uses when deciding whether to apply a patch
  17.174 +are as follows.
  17.175 +\begin{itemize}
  17.176 +\item A patch that has no guards is always applied.
  17.177 +\item If the patch has any negative guard that matches any currently
  17.178 +  selected guard, the patch is skipped.
  17.179 +\item If the patch has any positive guard that matches any currently
  17.180 +  selected guard, the patch is applied.
  17.181 +\item If the patch has positive or negative guards, but none matches
  17.182 +  any currently selected guard, the patch is skipped.
  17.183 +\end{itemize}
  17.184 +
  17.185 +\section{Trimming the work environment}
  17.186 +
  17.187 +In working on the device driver I mentioned earlier, I don't apply the
  17.188 +patches to a normal Linux kernel tree.  Instead, I use a repository
  17.189 +that contains only a snapshot of the source files and headers that are
  17.190 +relevant to Infiniband development.  This repository is~1\% the size
  17.191 +of a kernel repository, so it's easier to work with.
  17.192 +
  17.193 +I then choose a ``base'' version on top of which the patches are
  17.194 +applied.  This is a snapshot of the Linux kernel tree as of a revision
  17.195 +of my choosing.  When I take the snapshot, I record the changeset ID
  17.196 +from the kernel repository in the commit message.  Since the snapshot
  17.197 +preserves the ``shape'' and content of the relevant parts of the
  17.198 +kernel tree, I can apply my patches on top of either my tiny
  17.199 +repository or a normal kernel tree.
  17.200 +
  17.201 +Normally, the base tree atop which the patches apply should be a
  17.202 +snapshot of a very recent upstream tree.  This best facilitates the
  17.203 +development of patches that can easily be submitted upstream with few
  17.204 +or no modifications.
  17.205 +
  17.206 +\section{Dividing up the \sfilename{series} file}
  17.207 +
  17.208 +I categorise the patches in the \sfilename{series} file into a number
  17.209 +of logical groups.  Each section of like patches begins with a block
  17.210 +of comments that describes the purpose of the patches that follow.
  17.211 +
  17.212 +The sequence of patch groups that I maintain follows.  The ordering of
  17.213 +these groups is important; I'll describe why after I introduce the
  17.214 +groups.
  17.215 +\begin{itemize}
  17.216 +\item The ``accepted'' group.  Patches that the development team has
  17.217 +  submitted to the maintainer of the Infiniband subsystem, and which
  17.218 +  he has accepted, but which are not present in the snapshot that the
  17.219 +  tiny repository is based on.  These are ``read only'' patches,
  17.220 +  present only to transform the tree into a similar state as it is in
  17.221 +  the upstream maintainer's repository.
  17.222 +\item The ``rework'' group.  Patches that I have submitted, but that
  17.223 +  the upstream maintainer has requested modifications to before he
  17.224 +  will accept them.
  17.225 +\item The ``pending'' group.  Patches that I have not yet submitted to
  17.226 +  the upstream maintainer, but which we have finished working on.
  17.227 +  These will be ``read only'' for a while.  If the upstream maintainer
  17.228 +  accepts them upon submission, I'll move them to the end of the
  17.229 +  ``accepted'' group.  If he requests that I modify any, I'll move
  17.230 +  them to the beginning of the ``rework'' group.
  17.231 +\item The ``in progress'' group.  Patches that are actively being
  17.232 +  developed, and should not be submitted anywhere yet.
  17.233 +\item The ``backport'' group.  Patches that adapt the source tree to
  17.234 +  older versions of the kernel tree.
  17.235 +\item The ``do not ship'' group.  Patches that for some reason should
  17.236 +  never be submitted upstream.  For example, one such patch might
  17.237 +  change embedded driver identification strings to make it easier to
  17.238 +  distinguish, in the field, between an out-of-tree version of the
  17.239 +  driver and a version shipped by a distribution vendor.
  17.240 +\end{itemize}
  17.241 +
  17.242 +Now to return to the reasons for ordering groups of patches in this
  17.243 +way.  We would like the lowest patches in the stack to be as stable as
  17.244 +possible, so that we will not need to rework higher patches due to
  17.245 +changes in context.  Putting patches that will never be changed first
  17.246 +in the \sfilename{series} file serves this purpose.
  17.247 +
  17.248 +We would also like the patches that we know we'll need to modify to be
  17.249 +applied on top of a source tree that resembles the upstream tree as
  17.250 +closely as possible.  This is why we keep accepted patches around for
  17.251 +a while.
  17.252 +
  17.253 +The ``backport'' and ``do not ship'' patches float at the end of the
  17.254 +\sfilename{series} file.  The backport patches must be applied on top
  17.255 +of all other patches, and the ``do not ship'' patches might as well
  17.256 +stay out of harm's way.
  17.257 +
  17.258 +\section{Maintaining the patch series}
  17.259 +
  17.260 +In my work, I use a number of guards to control which patches are to
  17.261 +be applied.
  17.262 +
  17.263 +\begin{itemize}
  17.264 +\item ``Accepted'' patches are guarded with \texttt{accepted}.  I
  17.265 +  enable this guard most of the time.  When I'm applying the patches
  17.266 +  on top of a tree where the patches are already present, I can turn
  17.267 +  this patch off, and the patches that follow it will apply cleanly.
  17.268 +\item Patches that are ``finished'', but not yet submitted, have no
  17.269 +  guards.  If I'm applying the patch stack to a copy of the upstream
  17.270 +  tree, I don't need to enable any guards in order to get a reasonably
  17.271 +  safe source tree.
  17.272 +\item Those patches that need reworking before being resubmitted are
  17.273 +  guarded with \texttt{rework}.
  17.274 +\item For those patches that are still under development, I use
  17.275 +  \texttt{devel}.
  17.276 +\item A backport patch may have several guards, one for each version
  17.277 +  of the kernel to which it applies.  For example, a patch that
  17.278 +  backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard.
  17.279 +\end{itemize}
  17.280 +This variety of guards gives me considerable flexibility in
  17.281 +qdetermining what kind of source tree I want to end up with.  For most
  17.282 +situations, the selection of appropriate guards is automated during
  17.283 +the build process, but I can manually tune the guards to use for less
  17.284 +common circumstances.
  17.285 +
  17.286 +\subsection{The art of writing backport patches}
  17.287 +
  17.288 +Using MQ, writing a backport patch is a simple process.  All such a
  17.289 +patch has to do is modify a piece of code that uses a kernel feature
  17.290 +not present in the older version of the kernel, so that the driver
  17.291 +continues to work correctly under that older version.
  17.292 +
  17.293 +A useful goal when writing a good backport patch is to make your code
  17.294 +look as if it was written for the older version of the kernel you're
  17.295 +targeting.  The less obtrusive the patch, the easier it will be to
  17.296 +understand and maintain.  If you're writing a collection of backport
  17.297 +patches to avoid the ``rat's nest'' effect of lots of
  17.298 +\texttt{\#ifdef}s (hunks of source code that are only used
  17.299 +conditionally) in your code, don't introduce version-dependent
  17.300 +\texttt{\#ifdef}s into the patches.  Instead, write several patches,
  17.301 +each of which makes unconditional changes, and control their
  17.302 +application using guards.
  17.303 +
  17.304 +There are two reasons to divide backport patches into a distinct
  17.305 +group, away from the ``regular'' patches whose effects they modify.
  17.306 +The first is that intermingling the two makes it more difficult to use
  17.307 +a tool like the \hgext{patchbomb} extension to automate the process of
  17.308 +submitting the patches to an upstream maintainer.  The second is that
  17.309 +a backport patch could perturb the context in which a subsequent
  17.310 +regular patch is applied, making it impossible to apply the regular
  17.311 +patch cleanly \emph{without} the earlier backport patch already being
  17.312 +applied.
  17.313 +
  17.314 +\section{Useful tips for developing with MQ}
  17.315 +
  17.316 +\subsection{Organising patches in directories}
  17.317 +
  17.318 +If you're working on a substantial project with MQ, it's not difficult
  17.319 +to accumulate a large number of patches.  For example, I have one
  17.320 +patch repository that contains over 250 patches.
  17.321 +
  17.322 +If you can group these patches into separate logical categories, you
  17.323 +can if you like store them in different directories; MQ has no
  17.324 +problems with patch names that contain path separators.
  17.325 +
  17.326 +\subsection{Viewing the history of a patch}
  17.327 +\label{mq-collab:tips:interdiff}
  17.328 +
  17.329 +If you're developing a set of patches over a long time, it's a good
  17.330 +idea to maintain them in a repository, as discussed in
  17.331 +section~\ref{sec:mq:repo}.  If you do so, you'll quickly discover that
  17.332 +using the \hgcmd{diff} command to look at the history of changes to a
  17.333 +patch is unworkable.  This is in part because you're looking at the
  17.334 +second derivative of the real code (a diff of a diff), but also
  17.335 +because MQ adds noise to the process by modifying time stamps and
  17.336 +directory names when it updates a patch.
  17.337 +
  17.338 +However, you can use the \hgext{extdiff} extension, which is bundled
  17.339 +with Mercurial, to turn a diff of two versions of a patch into
  17.340 +something readable.  To do this, you will need a third-party package
  17.341 +called \package{patchutils}~\cite{web:patchutils}.  This provides a
  17.342 +command named \command{interdiff}, which shows the differences between
  17.343 +two diffs as a diff.  Used on two versions of the same diff, it
  17.344 +generates a diff that represents the diff from the first to the second
  17.345 +version.
  17.346 +
  17.347 +You can enable the \hgext{extdiff} extension in the usual way, by
  17.348 +adding a line to the \rcsection{extensions} section of your \hgrc.
  17.349 +\begin{codesample2}
  17.350 +  [extensions]
  17.351 +  extdiff =
  17.352 +\end{codesample2}
  17.353 +The \command{interdiff} command expects to be passed the names of two
  17.354 +files, but the \hgext{extdiff} extension passes the program it runs a
  17.355 +pair of directories, each of which can contain an arbitrary number of
  17.356 +files.  We thus need a small program that will run \command{interdiff}
  17.357 +on each pair of files in these two directories.  This program is
  17.358 +available as \sfilename{hg-interdiff} in the \dirname{examples}
  17.359 +directory of the source code repository that accompanies this book.
  17.360 +\excode{hg-interdiff}
  17.361 +
  17.362 +With the \sfilename{hg-interdiff} program in your shell's search path,
  17.363 +you can run it as follows, from inside an MQ patch directory:
  17.364 +\begin{codesample2}
  17.365 +  hg extdiff -p hg-interdiff -r A:B my-change.patch
  17.366 +\end{codesample2}
  17.367 +Since you'll probably want to use this long-winded command a lot, you
  17.368 +can get \hgext{hgext} to make it available as a normal Mercurial
  17.369 +command, again by editing your \hgrc.
  17.370 +\begin{codesample2}
  17.371 +  [extdiff]
  17.372 +  cmd.interdiff = hg-interdiff
  17.373 +\end{codesample2}
  17.374 +This directs \hgext{hgext} to make an \texttt{interdiff} command
  17.375 +available, so you can now shorten the previous invocation of
  17.376 +\hgxcmd{extdiff}{extdiff} to something a little more wieldy.
  17.377 +\begin{codesample2}
  17.378 +  hg interdiff -r A:B my-change.patch
  17.379 +\end{codesample2}
  17.380 +
  17.381 +\begin{note}
  17.382 +  The \command{interdiff} command works well only if the underlying
  17.383 +  files against which versions of a patch are generated remain the
  17.384 +  same.  If you create a patch, modify the underlying files, and then
  17.385 +  regenerate the patch, \command{interdiff} may not produce useful
  17.386 +  output.
  17.387 +\end{note}
  17.388 +
  17.389 +The \hgext{extdiff} extension is useful for more than merely improving
  17.390 +the presentation of MQ~patches.  To read more about it, go to
  17.391 +section~\ref{sec:hgext:extdiff}.
  17.392 +
  17.393 +%%% Local Variables: 
  17.394 +%%% mode: latex
  17.395 +%%% TeX-master: "00book"
  17.396 +%%% End: 

    18.1 --- a/es/mq-ref.tex	Sat Oct 18 14:35:43 2008 -0500
    18.2 +++ b/es/mq-ref.tex	Sat Oct 18 15:44:41 2008 -0500
    18.3 @@ -0,0 +1,349 @@
    18.4 +\chapter{Mercurial Queues reference}
    18.5 +\label{chap:mqref}
    18.6 +
    18.7 +\section{MQ command reference}
    18.8 +\label{sec:mqref:cmdref}
    18.9 +
   18.10 +For an overview of the commands provided by MQ, use the command
   18.11 +\hgcmdargs{help}{mq}.
   18.12 +
   18.13 +\subsection{\hgxcmd{mq}{qapplied}---print applied patches}
   18.14 +
   18.15 +The \hgxcmd{mq}{qapplied} command prints the current stack of applied
   18.16 +patches.  Patches are printed in oldest-to-newest order, so the last
   18.17 +patch in the list is the ``top'' patch.
   18.18 +
   18.19 +\subsection{\hgxcmd{mq}{qcommit}---commit changes in the queue repository}
   18.20 +
   18.21 +The \hgxcmd{mq}{qcommit} command commits any outstanding changes in the
   18.22 +\sdirname{.hg/patches} repository.  This command only works if the
   18.23 +\sdirname{.hg/patches} directory is a repository, i.e.~you created the
   18.24 +directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran
   18.25 +\hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}.
   18.26 +
   18.27 +This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
   18.28 +
   18.29 +\subsection{\hgxcmd{mq}{qdelete}---delete a patch from the
   18.30 +  \sfilename{series} file}
   18.31 +
   18.32 +The \hgxcmd{mq}{qdelete} command removes the entry for a patch from the
   18.33 +\sfilename{series} file in the \sdirname{.hg/patches} directory.  It
   18.34 +does not pop the patch if the patch is already applied.  By default,
   18.35 +it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to
   18.36 +do that.
   18.37 +
   18.38 +Options:
   18.39 +\begin{itemize}
   18.40 +\item[\hgxopt{mq}{qdel}{-f}] Delete the patch file.
   18.41 +\end{itemize}
   18.42 +
   18.43 +\subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch}
   18.44 +
   18.45 +The \hgxcmd{mq}{qdiff} command prints a diff of the topmost applied patch.
   18.46 +It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
   18.47 +
   18.48 +\subsection{\hgxcmd{mq}{qfold}---merge (``fold'') several patches into one}
   18.49 +
   18.50 +The \hgxcmd{mq}{qfold} command merges multiple patches into the topmost
   18.51 +applied patch, so that the topmost applied patch makes the union of
   18.52 +all of the changes in the patches in question.
   18.53 +
   18.54 +The patches to fold must not be applied; \hgxcmd{mq}{qfold} will exit with
   18.55 +an error if any is.  The order in which patches are folded is
   18.56 +significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
   18.57 +patch, followed by \texttt{a}, followed by \texttt{b}''.
   18.58 +
   18.59 +The comments from the folded patches are appended to the comments of
   18.60 +the destination patch, with each block of comments separated by three
   18.61 +asterisk (``\texttt{*}'') characters.  Use the \hgxopt{mq}{qfold}{-e}
   18.62 +option to edit the commit message for the combined patch/changeset
   18.63 +after the folding has completed.
   18.64 +
   18.65 +Options:
   18.66 +\begin{itemize}
   18.67 +\item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description
   18.68 +  for the newly folded patch.
   18.69 +\item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new
   18.70 +  commit message and patch description for the folded patch.
   18.71 +\item[\hgxopt{mq}{qfold}{-m}] Use the given text as the new commit message
   18.72 +  and patch description for the folded patch.
   18.73 +\end{itemize}
   18.74 +
   18.75 +\subsection{\hgxcmd{mq}{qheader}---display the header/description of a patch}
   18.76 +
   18.77 +The \hgxcmd{mq}{qheader} command prints the header, or description, of a
   18.78 +patch.  By default, it prints the header of the topmost applied patch.
   18.79 +Given an argument, it prints the header of the named patch.
   18.80 +
   18.81 +\subsection{\hgxcmd{mq}{qimport}---import a third-party patch into the queue}
   18.82 +
   18.83 +The \hgxcmd{mq}{qimport} command adds an entry for an external patch to the
   18.84 +\sfilename{series} file, and copies the patch into the
   18.85 +\sdirname{.hg/patches} directory.  It adds the entry immediately after
   18.86 +the topmost applied patch, but does not push the patch.
   18.87 +
   18.88 +If the \sdirname{.hg/patches} directory is a repository,
   18.89 +\hgxcmd{mq}{qimport} automatically does an \hgcmd{add} of the imported
   18.90 +patch.
   18.91 +
   18.92 +\subsection{\hgxcmd{mq}{qinit}---prepare a repository to work with MQ}
   18.93 +
   18.94 +The \hgxcmd{mq}{qinit} command prepares a repository to work with MQ.  It
   18.95 +creates a directory called \sdirname{.hg/patches}.
   18.96 +
   18.97 +Options:
   18.98 +\begin{itemize}
   18.99 +\item[\hgxopt{mq}{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
  18.100 +  in its own right.  Also creates a \sfilename{.hgignore} file that
  18.101 +  will ignore the \sfilename{status} file.
  18.102 +\end{itemize}
  18.103 +
  18.104 +When the \sdirname{.hg/patches} directory is a repository, the
  18.105 +\hgxcmd{mq}{qimport} and \hgxcmd{mq}{qnew} commands automatically \hgcmd{add}
  18.106 +new patches.
  18.107 +
  18.108 +\subsection{\hgxcmd{mq}{qnew}---create a new patch}
  18.109 +
  18.110 +The \hgxcmd{mq}{qnew} command creates a new patch.  It takes one mandatory
  18.111 +argument, the name to use for the patch file.  The newly created patch
  18.112 +is created empty by default.  It is added to the \sfilename{series}
  18.113 +file after the current topmost applied patch, and is immediately
  18.114 +pushed on top of that patch.
  18.115 +
  18.116 +If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will
  18.117 +refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is
  18.118 +used (see below).  This behaviour allows you to \hgxcmd{mq}{qrefresh} your
  18.119 +topmost applied patch before you apply a new patch on top of it.
  18.120 +
  18.121 +Options:
  18.122 +\begin{itemize}
  18.123 +\item[\hgxopt{mq}{qnew}{-f}] Create a new patch if the contents of the
  18.124 +  working directory are modified.  Any outstanding modifications are
  18.125 +  added to the newly created patch, so after this command completes,
  18.126 +  the working directory will no longer be modified.
  18.127 +\item[\hgxopt{mq}{qnew}{-m}] Use the given text as the commit message.
  18.128 +  This text will be stored at the beginning of the patch file, before
  18.129 +  the patch data.
  18.130 +\end{itemize}
  18.131 +
  18.132 +\subsection{\hgxcmd{mq}{qnext}---print the name of the next patch}
  18.133 +
  18.134 +The \hgxcmd{mq}{qnext} command prints the name name of the next patch in
  18.135 +the \sfilename{series} file after the topmost applied patch.  This
  18.136 +patch will become the topmost applied patch if you run \hgxcmd{mq}{qpush}.
  18.137 +
  18.138 +\subsection{\hgxcmd{mq}{qpop}---pop patches off the stack}
  18.139 +
  18.140 +The \hgxcmd{mq}{qpop} command removes applied patches from the top of the
  18.141 +stack of applied patches.  By default, it removes only one patch.
  18.142 +
  18.143 +This command removes the changesets that represent the popped patches
  18.144 +from the repository, and updates the working directory to undo the
  18.145 +effects of the patches.
  18.146 +
  18.147 +This command takes an optional argument, which it uses as the name or
  18.148 +index of the patch to pop to.  If given a name, it will pop patches
  18.149 +until the named patch is the topmost applied patch.  If given a
  18.150 +number, \hgxcmd{mq}{qpop} treats the number as an index into the entries in
  18.151 +the series file, counting from zero (empty lines and lines containing
  18.152 +only comments do not count).  It pops patches until the patch
  18.153 +identified by the given index is the topmost applied patch.
  18.154 +
  18.155 +The \hgxcmd{mq}{qpop} command does not read or write patches or the
  18.156 +\sfilename{series} file.  It is thus safe to \hgxcmd{mq}{qpop} a patch that
  18.157 +you have removed from the \sfilename{series} file, or a patch that you
  18.158 +have renamed or deleted entirely.  In the latter two cases, use the
  18.159 +name of the patch as it was when you applied it.
  18.160 +
  18.161 +By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the
  18.162 +working directory has been modified.  You can override this behaviour
  18.163 +using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in
  18.164 +the working directory.
  18.165 +
  18.166 +Options:
  18.167 +\begin{itemize}
  18.168 +\item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches.  This returns the
  18.169 +  repository to its state before you applied any patches.
  18.170 +\item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the
  18.171 +  working directory when popping.
  18.172 +\item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue.
  18.173 +\end{itemize}
  18.174 +
  18.175 +The \hgxcmd{mq}{qpop} command removes one line from the end of the
  18.176 +\sfilename{status} file for each patch that it pops.
  18.177 +
  18.178 +\subsection{\hgxcmd{mq}{qprev}---print the name of the previous patch}
  18.179 +
  18.180 +The \hgxcmd{mq}{qprev} command prints the name of the patch in the
  18.181 +\sfilename{series} file that comes before the topmost applied patch.
  18.182 +This will become the topmost applied patch if you run \hgxcmd{mq}{qpop}.
  18.183 +
  18.184 +\subsection{\hgxcmd{mq}{qpush}---push patches onto the stack}
  18.185 +\label{sec:mqref:cmd:qpush}
  18.186 +
  18.187 +The \hgxcmd{mq}{qpush} command adds patches onto the applied stack.  By
  18.188 +default, it adds only one patch.
  18.189 +
  18.190 +This command creates a new changeset to represent each applied patch,
  18.191 +and updates the working directory to apply the effects of the patches.
  18.192 +
  18.193 +The default data used when creating a changeset are as follows:
  18.194 +\begin{itemize}
  18.195 +\item The commit date and time zone are the current date and time
  18.196 +  zone.  Because these data are used to compute the identity of a
  18.197 +  changeset, this means that if you \hgxcmd{mq}{qpop} a patch and
  18.198 +  \hgxcmd{mq}{qpush} it again, the changeset that you push will have a
  18.199 +  different identity than the changeset you popped.
  18.200 +\item The author is the same as the default used by the \hgcmd{commit}
  18.201 +  command.
  18.202 +\item The commit message is any text from the patch file that comes
  18.203 +  before the first diff header.  If there is no such text, a default
  18.204 +  commit message is used that identifies the name of the patch.
  18.205 +\end{itemize}
  18.206 +If a patch contains a Mercurial patch header (XXX add link), the
  18.207 +information in the patch header overrides these defaults.
  18.208 +
  18.209 +Options:
  18.210 +\begin{itemize}
  18.211 +\item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the
  18.212 +  \sfilename{series} file until there are none left to push.
  18.213 +\item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end
  18.214 +  of the commit message.
  18.215 +\item[\hgxopt{mq}{qpush}{-m}] If a patch fails to apply cleanly, use the
  18.216 +  entry for the patch in another saved queue to compute the parameters
  18.217 +  for a three-way merge, and perform a three-way merge using the
  18.218 +  normal Mercurial merge machinery.  Use the resolution of the merge
  18.219 +  as the new patch content.
  18.220 +\item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing.
  18.221 +\end{itemize}
  18.222 +
  18.223 +The \hgxcmd{mq}{qpush} command reads, but does not modify, the
  18.224 +\sfilename{series} file.  It appends one line to the \hgcmd{status}
  18.225 +file for each patch that it pushes.
  18.226 +
  18.227 +\subsection{\hgxcmd{mq}{qrefresh}---update the topmost applied patch}
  18.228 +
  18.229 +The \hgxcmd{mq}{qrefresh} command updates the topmost applied patch.  It
  18.230 +modifies the patch, removes the old changeset that represented the
  18.231 +patch, and creates a new changeset to represent the modified patch.
  18.232 +
  18.233 +The \hgxcmd{mq}{qrefresh} command looks for the following modifications:
  18.234 +\begin{itemize}
  18.235 +\item Changes to the commit message, i.e.~the text before the first
  18.236 +  diff header in the patch file, are reflected in the new changeset
  18.237 +  that represents the patch.
  18.238 +\item Modifications to tracked files in the working directory are
  18.239 +  added to the patch.
  18.240 +\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
  18.241 +  \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
  18.242 +  destinations are added to the patch, while removed files and rename
  18.243 +  sources are removed.
  18.244 +\end{itemize}
  18.245 +
  18.246 +Even if \hgxcmd{mq}{qrefresh} detects no changes, it still recreates the
  18.247 +changeset that represents the patch.  This causes the identity of the
  18.248 +changeset to differ from the previous changeset that identified the
  18.249 +patch.
  18.250 +
  18.251 +Options:
  18.252 +\begin{itemize}
  18.253 +\item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description,
  18.254 +  using the preferred text editor.
  18.255 +\item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch
  18.256 +  description, using the given text.
  18.257 +\item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch
  18.258 +  description, using text from the given file.
  18.259 +\end{itemize}
  18.260 +
  18.261 +\subsection{\hgxcmd{mq}{qrename}---rename a patch}
  18.262 +
  18.263 +The \hgxcmd{mq}{qrename} command renames a patch, and changes the entry for
  18.264 +the patch in the \sfilename{series} file.
  18.265 +
  18.266 +With a single argument, \hgxcmd{mq}{qrename} renames the topmost applied
  18.267 +patch.  With two arguments, it renames its first argument to its
  18.268 +second.
  18.269 +
  18.270 +\subsection{\hgxcmd{mq}{qrestore}---restore saved queue state}
  18.271 +
  18.272 +XXX No idea what this does.
  18.273 +
  18.274 +\subsection{\hgxcmd{mq}{qsave}---save current queue state}
  18.275 +
  18.276 +XXX Likewise.
  18.277 +
  18.278 +\subsection{\hgxcmd{mq}{qseries}---print the entire patch series}
  18.279 +
  18.280 +The \hgxcmd{mq}{qseries} command prints the entire patch series from the
  18.281 +\sfilename{series} file.  It prints only patch names, not empty lines
  18.282 +or comments.  It prints in order from first to be applied to last.
  18.283 +
  18.284 +\subsection{\hgxcmd{mq}{qtop}---print the name of the current patch}
  18.285 +
  18.286 +The \hgxcmd{mq}{qtop} prints the name of the topmost currently applied
  18.287 +patch.
  18.288 +
  18.289 +\subsection{\hgxcmd{mq}{qunapplied}---print patches not yet applied}
  18.290 +
  18.291 +The \hgxcmd{mq}{qunapplied} command prints the names of patches from the
  18.292 +\sfilename{series} file that are not yet applied.  It prints them in
  18.293 +order from the next patch that will be pushed to the last.
  18.294 +
  18.295 +\subsection{\hgcmd{strip}---remove a revision and descendants}
  18.296 +
  18.297 +The \hgcmd{strip} command removes a revision, and all of its
  18.298 +descendants, from the repository.  It undoes the effects of the
  18.299 +removed revisions from the repository, and updates the working
  18.300 +directory to the first parent of the removed revision.
  18.301 +
  18.302 +The \hgcmd{strip} command saves a backup of the removed changesets in
  18.303 +a bundle, so that they can be reapplied if removed in error.
  18.304 +
  18.305 +Options:
  18.306 +\begin{itemize}
  18.307 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
  18.308 +  with the stripped changesets in the backup bundle.
  18.309 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
  18.310 +  heads. XXX This should be renamed, and use \texttt{-f} to strip revs
  18.311 +  when there are pending changes.
  18.312 +\item[\hgopt{strip}{-n}] Do not save a backup bundle.
  18.313 +\end{itemize}
  18.314 +
  18.315 +\section{MQ file reference}
  18.316 +
  18.317 +\subsection{The \sfilename{series} file}
  18.318 +
  18.319 +The \sfilename{series} file contains a list of the names of all
  18.320 +patches that MQ can apply.  It is represented as a list of names, with
  18.321 +one name saved per line.  Leading and trailing white space in each
  18.322 +line are ignored.
  18.323 +
  18.324 +Lines may contain comments.  A comment begins with the ``\texttt{\#}''
  18.325 +character, and extends to the end of the line.  Empty lines, and lines
  18.326 +that contain only comments, are ignored.
  18.327 +
  18.328 +You will often need to edit the \sfilename{series} file by hand, hence
  18.329 +the support for comments and empty lines noted above.  For example,
  18.330 +you can comment out a patch temporarily, and \hgxcmd{mq}{qpush} will skip
  18.331 +over that patch when applying patches.  You can also change the order
  18.332 +in which patches are applied by reordering their entries in the
  18.333 +\sfilename{series} file.
  18.334 +
  18.335 +Placing the \sfilename{series} file under revision control is also
  18.336 +supported; it is a good idea to place all of the patches that it
  18.337 +refers to under revision control, as well.  If you create a patch
  18.338 +directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{qinit}, this
  18.339 +will be done for you automatically.
  18.340 +
  18.341 +\subsection{The \sfilename{status} file}
  18.342 +
  18.343 +The \sfilename{status} file contains the names and changeset hashes of
  18.344 +all patches that MQ currently has applied.  Unlike the
  18.345 +\sfilename{series} file, this file is not intended for editing.  You
  18.346 +should not place this file under revision control, or modify it in any
  18.347 +way.  It is used by MQ strictly for internal book-keeping.
  18.348 +
  18.349 +%%% Local Variables: 
  18.350 +%%% mode: latex
  18.351 +%%% TeX-master: "00book"
  18.352 +%%% End: 

    19.1 --- a/es/mq.tex	Sat Oct 18 14:35:43 2008 -0500
    19.2 +++ b/es/mq.tex	Sat Oct 18 15:44:41 2008 -0500
    19.3 @@ -0,0 +1,1043 @@
    19.4 +\chapter{Managing change with Mercurial Queues}
    19.5 +\label{chap:mq}
    19.6 +
    19.7 +\section{The patch management problem}
    19.8 +\label{sec:mq:patch-mgmt}
    19.9 +
   19.10 +Here is a common scenario: you need to install a software package from
   19.11 +source, but you find a bug that you must fix in the source before you
   19.12 +can start using the package.  You make your changes, forget about the
   19.13 +package for a while, and a few months later you need to upgrade to a
   19.14 +newer version of the package.  If the newer version of the package
   19.15 +still has the bug, you must extract your fix from the older source
   19.16 +tree and apply it against the newer version.  This is a tedious task,
   19.17 +and it's easy to make mistakes.
   19.18 +
   19.19 +This is a simple case of the ``patch management'' problem.  You have
   19.20 +an ``upstream'' source tree that you can't change; you need to make
   19.21 +some local changes on top of the upstream tree; and you'd like to be
   19.22 +able to keep those changes separate, so that you can apply them to
   19.23 +newer versions of the upstream source.
   19.24 +
   19.25 +The patch management problem arises in many situations.  Probably the
   19.26 +most visible is that a user of an open source software project will
   19.27 +contribute a bug fix or new feature to the project's maintainers in the
   19.28 +form of a patch.
   19.29 +
   19.30 +Distributors of operating systems that include open source software
   19.31 +often need to make changes to the packages they distribute so that
   19.32 +they will build properly in their environments.
   19.33 +
   19.34 +When you have few changes to maintain, it is easy to manage a single
   19.35 +patch using the standard \command{diff} and \command{patch} programs
   19.36 +(see section~\ref{sec:mq:patch} for a discussion of these tools).
   19.37 +Once the number of changes grows, it starts to make sense to maintain
   19.38 +patches as discrete ``chunks of work,'' so that for example a single
   19.39 +patch will contain only one bug fix (the patch might modify several
   19.40 +files, but it's doing ``only one thing''), and you may have a number
   19.41 +of such patches for different bugs you need fixed and local changes
   19.42 +you require.  In this situation, if you submit a bug fix patch to the
   19.43 +upstream maintainers of a package and they include your fix in a
   19.44 +subsequent release, you can simply drop that single patch when you're
   19.45 +updating to the newer release.
   19.46 +
   19.47 +Maintaining a single patch against an upstream tree is a little
   19.48 +tedious and error-prone, but not difficult.  However, the complexity
   19.49 +of the problem grows rapidly as the number of patches you have to
   19.50 +maintain increases.  With more than a tiny number of patches in hand,
   19.51 +understanding which ones you have applied and maintaining them moves
   19.52 +from messy to overwhelming.
   19.53 +
   19.54 +Fortunately, Mercurial includes a powerful extension, Mercurial Queues
   19.55 +(or simply ``MQ''), that massively simplifies the patch management
   19.56 +problem.
   19.57 +
   19.58 +\section{The prehistory of Mercurial Queues}
   19.59 +\label{sec:mq:history}
   19.60 +
   19.61 +During the late 1990s, several Linux kernel developers started to
   19.62 +maintain ``patch series'' that modified the behaviour of the Linux
   19.63 +kernel.  Some of these series were focused on stability, some on
   19.64 +feature coverage, and others were more speculative.
   19.65 +
   19.66 +The sizes of these patch series grew rapidly.  In 2002, Andrew Morton
   19.67 +published some shell scripts he had been using to automate the task of
   19.68 +managing his patch queues.  Andrew was successfully using these
   19.69 +scripts to manage hundreds (sometimes thousands) of patches on top of
   19.70 +the Linux kernel.
   19.71 +
   19.72 +\subsection{A patchwork quilt}
   19.73 +\label{sec:mq:quilt}
   19.74 +
   19.75 +In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
   19.76 +approach of Andrew's scripts and published a tool called ``patchwork
   19.77 +quilt''~\cite{web:quilt}, or simply ``quilt''
   19.78 +(see~\cite{gruenbacher:2005} for a paper describing it).  Because
   19.79 +quilt substantially automated patch management, it rapidly gained a
   19.80 +large following among open source software developers.
   19.81 +
   19.82 +Quilt manages a \emph{stack of patches} on top of a directory tree.
   19.83 +To begin, you tell quilt to manage a directory tree, and tell it which
   19.84 +files you want to manage; it stores away the names and contents of
   19.85 +those files.  To fix a bug, you create a new patch (using a single
   19.86 +command), edit the files you need to fix, then ``refresh'' the patch.
   19.87 +
   19.88 +The refresh step causes quilt to scan the directory tree; it updates
   19.89 +the patch with all of the changes you have made.  You can create
   19.90 +another patch on top of the first, which will track the changes
   19.91 +required to modify the tree from ``tree with one patch applied'' to
   19.92 +``tree with two patches applied''.
   19.93 +
   19.94 +You can \emph{change} which patches are applied to the tree.  If you
   19.95 +``pop'' a patch, the changes made by that patch will vanish from the
   19.96 +directory tree.  Quilt remembers which patches you have popped,
   19.97 +though, so you can ``push'' a popped patch again, and the directory
   19.98 +tree will be restored to contain the modifications in the patch.  Most
   19.99 +importantly, you can run the ``refresh'' command at any time, and the
  19.100 +topmost applied patch will be updated.  This means that you can, at
  19.101 +any time, change both which patches are applied and what
  19.102 +modifications those patches make.
  19.103 +
  19.104 +Quilt knows nothing about revision control tools, so it works equally
  19.105 +well on top of an unpacked tarball or a Subversion working copy.
  19.106 +
  19.107 +\subsection{From patchwork quilt to Mercurial Queues}
  19.108 +\label{sec:mq:quilt-mq}
  19.109 +
  19.110 +In mid-2005, Chris Mason took the features of quilt and wrote an
  19.111 +extension that he called Mercurial Queues, which added quilt-like
  19.112 +behaviour to Mercurial.
  19.113 +
  19.114 +The key difference between quilt and MQ is that quilt knows nothing
  19.115 +about revision control systems, while MQ is \emph{integrated} into
  19.116 +Mercurial.  Each patch that you push is represented as a Mercurial
  19.117 +changeset.  Pop a patch, and the changeset goes away.
  19.118 +
  19.119 +Because quilt does not care about revision control tools, it is still
  19.120 +a tremendously useful piece of software to know about for situations
  19.121 +where you cannot use Mercurial and MQ.
  19.122 +
  19.123 +\section{The huge advantage of MQ}
  19.124 +
  19.125 +I cannot overstate the value that MQ offers through the unification of
  19.126 +patches and revision control.
  19.127 +
  19.128 +A major reason that patches have persisted in the free software and
  19.129 +open source world---in spite of the availability of increasingly
  19.130 +capable revision control tools over the years---is the \emph{agility}
  19.131 +they offer.  
  19.132 +
  19.133 +Traditional revision control tools make a permanent, irreversible
  19.134 +record of everything that you do.  While this has great value, it's
  19.135 +also somewhat stifling.  If you want to perform a wild-eyed
  19.136 +experiment, you have to be careful in how you go about it, or you risk
  19.137 +leaving unneeded---or worse, misleading or destabilising---traces of
  19.138 +your missteps and errors in the permanent revision record.
  19.139 +
  19.140 +By contrast, MQ's marriage of distributed revision control with
  19.141 +patches makes it much easier to isolate your work.  Your patches live
  19.142 +on top of normal revision history, and you can make them disappear or
  19.143 +reappear at will.  If you don't like a patch, you can drop it.  If a
  19.144 +patch isn't quite as you want it to be, simply fix it---as many times
  19.145 +as you need to, until you have refined it into the form you desire.
  19.146 +
  19.147 +As an example, the integration of patches with revision control makes
  19.148 +understanding patches and debugging their effects---and their
  19.149 +interplay with the code they're based on---\emph{enormously} easier.
  19.150 +Since every applied patch has an associated changeset, you can use
  19.151 +\hgcmdargs{log}{\emph{filename}} to see which changesets and patches
  19.152 +affected a file.  You can use the \hgext{bisect} command to
  19.153 +binary-search through all changesets and applied patches to see where
  19.154 +a bug got introduced or fixed.  You can use the \hgcmd{annotate}
  19.155 +command to see which changeset or patch modified a particular line of
  19.156 +a source file.  And so on.
  19.157 +
  19.158 +\section{Understanding patches}
  19.159 +\label{sec:mq:patch}
  19.160 +
  19.161 +Because MQ doesn't hide its patch-oriented nature, it is helpful to
  19.162 +understand what patches are, and a little about the tools that work
  19.163 +with them.
  19.164 +
  19.165 +The traditional Unix \command{diff} command compares two files, and
  19.166 +prints a list of differences between them. The \command{patch} command
  19.167 +understands these differences as \emph{modifications} to make to a
  19.168 +file.  Take a look at figure~\ref{ex:mq:diff} for a simple example of
  19.169 +these commands in action.
  19.170 +
  19.171 +\begin{figure}[ht]
  19.172 +  \interaction{mq.dodiff.diff}
  19.173 +  \caption{Simple uses of the \command{diff} and \command{patch} commands}
  19.174 +  \label{ex:mq:diff}
  19.175 +\end{figure}
  19.176 +
  19.177 +The type of file that \command{diff} generates (and \command{patch}
  19.178 +takes as input) is called a ``patch'' or a ``diff''; there is no
  19.179 +difference between a patch and a diff.  (We'll use the term ``patch'',
  19.180 +since it's more commonly used.)
  19.181 +
  19.182 +A patch file can start with arbitrary text; the \command{patch}
  19.183 +command ignores this text, but MQ uses it as the commit message when
  19.184 +creating changesets.  To find the beginning of the patch content,
  19.185 +\command{patch} searches for the first line that starts with the
  19.186 +string ``\texttt{diff~-}''.
  19.187 +
  19.188 +MQ works with \emph{unified} diffs (\command{patch} can accept several
  19.189 +other diff formats, but MQ doesn't).  A unified diff contains two
  19.190 +kinds of header.  The \emph{file header} describes the file being
  19.191 +modified; it contains the name of the file to modify.  When
  19.192 +\command{patch} sees a new file header, it looks for a file with that
  19.193 +name to start modifying.
  19.194 +
  19.195 +After the file header comes a series of \emph{hunks}.  Each hunk
  19.196 +starts with a header; this identifies the range of line numbers within
  19.197 +the file that the hunk should modify.  Following the header, a hunk
  19.198 +starts and ends with a few (usually three) lines of text from the
  19.199 +unmodified file; these are called the \emph{context} for the hunk.  If
  19.200 +there's only a small amount of context between successive hunks,
  19.201 +\command{diff} doesn't print a new hunk header; it just runs the hunks
  19.202 +together, with a few lines of context between modifications.
  19.203 +
  19.204 +Each line of context begins with a space character.  Within the hunk,
  19.205 +a line that begins with ``\texttt{-}'' means ``remove this line,''
  19.206 +while a line that begins with ``\texttt{+}'' means ``insert this
  19.207 +line.''  For example, a line that is modified is represented by one
  19.208 +deletion and one insertion.
  19.209 +
  19.210 +We will return to some of the more subtle aspects of patches later (in
  19.211 +section~\ref{sec:mq:adv-patch}), but you should have enough information
  19.212 +now to use MQ.
  19.213 +
  19.214 +\section{Getting started with Mercurial Queues}
  19.215 +\label{sec:mq:start}
  19.216 +
  19.217 +Because MQ is implemented as an extension, you must explicitly enable
  19.218 +before you can use it.  (You don't need to download anything; MQ ships
  19.219 +with the standard Mercurial distribution.)  To enable MQ, edit your
  19.220 +\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.
  19.221 +
  19.222 +\begin{figure}[ht]
  19.223 +  \begin{codesample4}
  19.224 +    [extensions]
  19.225 +    hgext.mq =
  19.226 +  \end{codesample4}
  19.227 +  \label{ex:mq:config}
  19.228 +  \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension}
  19.229 +\end{figure}
  19.230 +
  19.231 +Once the extension is enabled, it will make a number of new commands
  19.232 +available.  To verify that the extension is working, you can use
  19.233 +\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see
  19.234 +the example in figure~\ref{ex:mq:enabled}.
  19.235 +
  19.236 +\begin{figure}[ht]
  19.237 +  \interaction{mq.qinit-help.help}
  19.238 +  \caption{How to verify that MQ is enabled}
  19.239 +  \label{ex:mq:enabled}
  19.240 +\end{figure}
  19.241 +
  19.242 +You can use MQ with \emph{any} Mercurial repository, and its commands
  19.243 +only operate within that repository.  To get started, simply prepare
  19.244 +the repository using the \hgxcmd{mq}{qinit} command (see
  19.245 +figure~\ref{ex:mq:qinit}).  This command creates an empty directory
  19.246 +called \sdirname{.hg/patches}, where MQ will keep its metadata.  As
  19.247 +with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing
  19.248 +if it succeeds.
  19.249 +
  19.250 +\begin{figure}[ht]
  19.251 +  \interaction{mq.tutorial.qinit}
  19.252 +  \caption{Preparing a repository for use with MQ}
  19.253 +  \label{ex:mq:qinit}
  19.254 +\end{figure}
  19.255 +
  19.256 +\begin{figure}[ht]
  19.257 +  \interaction{mq.tutorial.qnew}
  19.258 +  \caption{Creating a new patch}
  19.259 +  \label{ex:mq:qnew}
  19.260 +\end{figure}
  19.261 +
  19.262 +\subsection{Creating a new patch}
  19.263 +
  19.264 +To begin work on a new patch, use the \hgxcmd{mq}{qnew} command.  This
  19.265 +command takes one argument, the name of the patch to create.  MQ will
  19.266 +use this as the name of an actual file in the \sdirname{.hg/patches}
  19.267 +directory, as you can see in figure~\ref{ex:mq:qnew}.
  19.268 +
  19.269 +Also newly present in the \sdirname{.hg/patches} directory are two
  19.270 +other files, \sfilename{series} and \sfilename{status}.  The
  19.271 +\sfilename{series} file lists all of the patches that MQ knows about
  19.272 +for this repository, with one patch per line.  Mercurial uses the
  19.273 +\sfilename{status} file for internal book-keeping; it tracks all of the
  19.274 +patches that MQ has \emph{applied} in this repository.
  19.275 +
  19.276 +\begin{note}
  19.277 +  You may sometimes want to edit the \sfilename{series} file by hand;
  19.278 +  for example, to change the sequence in which some patches are
  19.279 +  applied.  However, manually editing the \sfilename{status} file is
  19.280 +  almost always a bad idea, as it's easy to corrupt MQ's idea of what
  19.281 +  is happening.
  19.282 +\end{note}
  19.283 +
  19.284 +Once you have created your new patch, you can edit files in the
  19.285 +working directory as you usually would.  All of the normal Mercurial
  19.286 +commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
  19.287 +they did before.
  19.288 +
  19.289 +\subsection{Refreshing a patch}
  19.290 +
  19.291 +When you reach a point where you want to save your work, use the
  19.292 +\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
  19.293 +you are working on.  This command folds the changes you have made in
  19.294 +the working directory into your patch, and updates its corresponding
  19.295 +changeset to contain those changes.
  19.296 +
  19.297 +\begin{figure}[ht]
  19.298 +  \interaction{mq.tutorial.qrefresh}
  19.299 +  \caption{Refreshing a patch}
  19.300 +  \label{ex:mq:qrefresh}
  19.301 +\end{figure}
  19.302 +
  19.303 +You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way
  19.304 +to ``checkpoint'' your work.  Refresh your patch at an opportune
  19.305 +time; try an experiment; and if the experiment doesn't work out,
  19.306 +\hgcmd{revert} your modifications back to the last time you refreshed.
  19.307 +
  19.308 +\begin{figure}[ht]
  19.309 +  \interaction{mq.tutorial.qrefresh2}
  19.310 +  \caption{Refresh a patch many times to accumulate changes}
  19.311 +  \label{ex:mq:qrefresh2}
  19.312 +\end{figure}
  19.313 +
  19.314 +\subsection{Stacking and tracking patches}
  19.315 +
  19.316 +Once you have finished working on a patch, or need to work on another,
  19.317 +you can use the \hgxcmd{mq}{qnew} command again to create a new patch.
  19.318 +Mercurial will apply this patch on top of your existing patch.  See
  19.319 +figure~\ref{ex:mq:qnew2} for an example.  Notice that the patch
  19.320 +contains the changes in our prior patch as part of its context (you
  19.321 +can see this more clearly in the output of \hgcmd{annotate}).
  19.322 +
  19.323 +\begin{figure}[ht]
  19.324 +  \interaction{mq.tutorial.qnew2}
  19.325 +  \caption{Stacking a second patch on top of the first}
  19.326 +  \label{ex:mq:qnew2}
  19.327 +\end{figure}
  19.328 +
  19.329 +So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've
  19.330 +been careful to only use regular Mercurial commands.  However, MQ
  19.331 +provides many commands that are easier to use when you are thinking
  19.332 +about patches, as illustrated in figure~\ref{ex:mq:qseries}:
  19.333 +
  19.334 +\begin{itemize}
  19.335 +\item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows
  19.336 +  about in this repository, from oldest to newest (most recently
  19.337 +  \emph{created}).
  19.338 +\item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has
  19.339 +  \emph{applied} in this repository, again from oldest to newest (most
  19.340 +  recently applied).
  19.341 +\end{itemize}
  19.342 +
  19.343 +\begin{figure}[ht]
  19.344 +  \interaction{mq.tutorial.qseries}
  19.345 +  \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and
  19.346 +    \hgxcmd{mq}{qapplied}}
  19.347 +  \label{ex:mq:qseries}
  19.348 +\end{figure}
  19.349 +
  19.350 +\subsection{Manipulating the patch stack}
  19.351 +
  19.352 +The previous discussion implied that there must be a difference
  19.353 +between ``known'' and ``applied'' patches, and there is.  MQ can
  19.354 +manage a patch without it being applied in the repository.
  19.355 +
  19.356 +An \emph{applied} patch has a corresponding changeset in the
  19.357 +repository, and the effects of the patch and changeset are visible in
  19.358 +the working directory.  You can undo the application of a patch using
  19.359 +the \hgxcmd{mq}{qpop} command.  MQ still \emph{knows about}, or manages, a
  19.360 +popped patch, but the patch no longer has a corresponding changeset in
  19.361 +the repository, and the working directory does not contain the changes
  19.362 +made by the patch.  Figure~\ref{fig:mq:stack} illustrates the
  19.363 +difference between applied and tracked patches.
  19.364 +
  19.365 +\begin{figure}[ht]
  19.366 +  \centering
  19.367 +  \grafix{mq-stack}
  19.368 +  \caption{Applied and unapplied patches in the MQ patch stack}
  19.369 +  \label{fig:mq:stack}
  19.370 +\end{figure}
  19.371 +
  19.372 +You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush}
  19.373 +command.  This creates a new changeset to correspond to the patch, and
  19.374 +the patch's changes once again become present in the working
  19.375 +directory.  See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop}
  19.376 +and \hgxcmd{mq}{qpush} in action.  Notice that once we have popped a patch
  19.377 +or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while
  19.378 +that of \hgxcmd{mq}{qapplied} has changed.
  19.379 +
  19.380 +\begin{figure}[ht]
  19.381 +  \interaction{mq.tutorial.qpop}
  19.382 +  \caption{Modifying the stack of applied patches}
  19.383 +  \label{ex:mq:qpop}
  19.384 +\end{figure}
  19.385 +
  19.386 +\subsection{Pushing and popping many patches}
  19.387 +
  19.388 +While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at
  19.389 +a time by default, you can push and pop many patches in one go.  The
  19.390 +\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all
  19.391 +unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop}
  19.392 +causes it to pop all applied patches.  (For some more ways to push and
  19.393 +pop many patches, see section~\ref{sec:mq:perf} below.)
  19.394 +
  19.395 +\begin{figure}[ht]
  19.396 +  \interaction{mq.tutorial.qpush-a}
  19.397 +  \caption{Pushing all unapplied patches}
  19.398 +  \label{ex:mq:qpush-a}
  19.399 +\end{figure}
  19.400 +
  19.401 +\subsection{Safety checks, and overriding them}
  19.402 +
  19.403 +Several MQ commands check the working directory before they do
  19.404 +anything, and fail if they find any modifications.  They do this to
  19.405 +ensure that you won't lose any changes that you have made, but not yet
  19.406 +incorporated into a patch.  Figure~\ref{ex:mq:add} illustrates this;
  19.407 +the \hgxcmd{mq}{qnew} command will not create a new patch if there are
  19.408 +outstanding changes, caused in this case by the \hgcmd{add} of
  19.409 +\filename{file3}.
  19.410 +
  19.411 +\begin{figure}[ht]
  19.412 +  \interaction{mq.tutorial.add}
  19.413 +  \caption{Forcibly creating a patch}
  19.414 +  \label{ex:mq:add}
  19.415 +\end{figure}
  19.416 +
  19.417 +Commands that check the working directory all take an ``I know what
  19.418 +I'm doing'' option, which is always named \option{-f}.  The exact
  19.419 +meaning of \option{-f} depends on the command.  For example,
  19.420 +\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding
  19.421 +changes into the new patch it creates, but
  19.422 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any
  19.423 +files affected by the patch that it is popping.  Be sure to read the
  19.424 +documentation for a command's \option{-f} option before you use it!
  19.425 +
  19.426 +\subsection{Working on several patches at once}
  19.427 +
  19.428 +The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost}
  19.429 +applied patch.  This means that you can suspend work on one patch (by
  19.430 +refreshing it), pop or push to make a different patch the top, and
  19.431 +work on \emph{that} patch for a while.
  19.432 +
  19.433 +Here's an example that illustrates how you can use this ability.
  19.434 +Let's say you're developing a new feature as two patches.  The first
  19.435 +is a change to the core of your software, and the second---layered on
  19.436 +top of the first---changes the user interface to use the code you just
  19.437 +added to the core.  If you notice a bug in the core while you're
  19.438 +working on the UI patch, it's easy to fix the core.  Simply
  19.439 +\hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and
  19.440 +\hgxcmd{mq}{qpop} down to the core patch.  Fix the core bug,
  19.441 +\hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI
  19.442 +patch to continue where you left off.
  19.443 +
  19.444 +\section{More about patches}
  19.445 +\label{sec:mq:adv-patch}
  19.446 +
  19.447 +MQ uses the GNU \command{patch} command to apply patches, so it's
  19.448 +helpful to know a few more detailed aspects of how \command{patch}
  19.449 +works, and about patches themselves.
  19.450 +
  19.451 +\subsection{The strip count}
  19.452 +
  19.453 +If you look at the file headers in a patch, you will notice that the
  19.454 +pathnames usually have an extra component on the front that isn't
  19.455 +present in the actual path name.  This is a holdover from the way that
  19.456 +people used to generate patches (people still do this, but it's
  19.457 +somewhat rare with modern revision control tools).  
  19.458 +
  19.459 +Alice would unpack a tarball, edit her files, then decide that she
  19.460 +wanted to create a patch.  So she'd rename her working directory,
  19.461 +unpack the tarball again (hence the need for the rename), and use the
  19.462 +\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to
  19.463 +recursively generate a patch between the unmodified directory and the
  19.464 +modified one.  The result would be that the name of the unmodified
  19.465 +directory would be at the front of the left-hand path in every file
  19.466 +header, and the name of the modified directory would be at the front
  19.467 +of the right-hand path.
  19.468 +
  19.469 +Since someone receiving a patch from the Alices of the net would be
  19.470 +unlikely to have unmodified and modified directories with exactly the
  19.471 +same names, the \command{patch} command has a \cmdopt{patch}{-p}
  19.472 +option that indicates the number of leading path name components to
  19.473 +strip when trying to apply a patch.  This number is called the
  19.474 +\emph{strip count}.
  19.475 +
  19.476 +An option of ``\texttt{-p1}'' means ``use a strip count of one''.  If
  19.477 +\command{patch} sees a file name \filename{foo/bar/baz} in a file
  19.478 +header, it will strip \filename{foo} and try to patch a file named
  19.479 +\filename{bar/baz}.  (Strictly speaking, the strip count refers to the
  19.480 +number of \emph{path separators} (and the components that go with them
  19.481 +) to strip.  A strip count of one will turn \filename{foo/bar} into
  19.482 +\filename{bar}, but \filename{/foo/bar} (notice the extra leading
  19.483 +slash) into \filename{foo/bar}.)
  19.484 +
  19.485 +The ``standard'' strip count for patches is one; almost all patches
  19.486 +contain one leading path name component that needs to be stripped.
  19.487 +Mercurial's \hgcmd{diff} command generates path names in this form,
  19.488 +and the \hgcmd{import} command and MQ expect patches to have a strip
  19.489 +count of one.
  19.490 +
  19.491 +If you receive a patch from someone that you want to add to your patch
  19.492 +queue, and the patch needs a strip count other than one, you cannot
  19.493 +just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet
  19.494 +have a \texttt{-p} option (see~\bug{311}).  Your best bet is to
  19.495 +\hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}}
  19.496 +to apply their patch, followed by \hgcmd{addremove} to pick up any
  19.497 +files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}.
  19.498 +This complexity may become unnecessary; see~\bug{311} for details.
  19.499 +\subsection{Strategies for applying a patch}
  19.500 +
  19.501 +When \command{patch} applies a hunk, it tries a handful of
  19.502 +successively less accurate strategies to try to make the hunk apply.
  19.503 +This falling-back technique often makes it possible to take a patch
  19.504 +that was generated against an old version of a file, and apply it
  19.505 +against a newer version of that file.
  19.506 +
  19.507 +First, \command{patch} tries an exact match, where the line numbers,
  19.508 +the context, and the text to be modified must apply exactly.  If it
  19.509 +cannot make an exact match, it tries to find an exact match for the
  19.510 +context, without honouring the line numbering information.  If this
  19.511 +succeeds, it prints a line of output saying that the hunk was applied,
  19.512 +but at some \emph{offset} from the original line number.
  19.513 +
  19.514 +If a context-only match fails, \command{patch} removes the first and
  19.515 +last lines of the context, and tries a \emph{reduced} context-only
  19.516 +match.  If the hunk with reduced context succeeds, it prints a message
  19.517 +saying that it applied the hunk with a \emph{fuzz factor} (the number
  19.518 +after the fuzz factor indicates how many lines of context
  19.519 +\command{patch} had to trim before the patch applied).
  19.520 +
  19.521 +When neither of these techniques works, \command{patch} prints a
  19.522 +message saying that the hunk in question was rejected.  It saves
  19.523 +rejected hunks (also simply called ``rejects'') to a file with the
  19.524 +same name, and an added \sfilename{.rej} extension.  It also saves an
  19.525 +unmodified copy of the file with a \sfilename{.orig} extension; the
  19.526 +copy of the file without any extensions will contain any changes made
  19.527 +by hunks that \emph{did} apply cleanly.  If you have a patch that
  19.528 +modifies \filename{foo} with six hunks, and one of them fails to
  19.529 +apply, you will have: an unmodified \filename{foo.orig}, a
  19.530 +\filename{foo.rej} containing one hunk, and \filename{foo}, containing
  19.531 +the changes made by the five successful five hunks.
  19.532 +
  19.533 +\subsection{Some quirks of patch representation}
  19.534 +
  19.535 +There are a few useful things to know about how \command{patch} works
  19.536 +with files.
  19.537 +\begin{itemize}
  19.538 +\item This should already be obvious, but \command{patch} cannot
  19.539 +  handle binary files.
  19.540 +\item Neither does it care about the executable bit; it creates new
  19.541 +  files as readable, but not executable.
  19.542 +\item \command{patch} treats the removal of a file as a diff between
  19.543 +  the file to be removed and the empty file.  So your idea of ``I
  19.544 +  deleted this file'' looks like ``every line of this file was
  19.545 +  deleted'' in a patch.
  19.546 +\item It treats the addition of a file as a diff between the empty
  19.547 +  file and the file to be added.  So in a patch, your idea of ``I
  19.548 +  added this file'' looks like ``every line of this file was added''.
  19.549 +\item It treats a renamed file as the removal of the old name, and the
  19.550 +  addition of the new name.  This means that renamed files have a big
  19.551 +  footprint in patches.  (Note also that Mercurial does not currently
  19.552 +  try to infer when files have been renamed or copied in a patch.)
  19.553 +\item \command{patch} cannot represent empty files, so you cannot use
  19.554 +  a patch to represent the notion ``I added this empty file to the
  19.555 +  tree''.
  19.556 +\end{itemize}
  19.557 +\subsection{Beware the fuzz}
  19.558 +
  19.559 +While applying a hunk at an offset, or with a fuzz factor, will often
  19.560 +be completely successful, these inexact techniques naturally leave
  19.561 +open the possibility of corrupting the patched file.  The most common
  19.562 +cases typically involve applying a patch twice, or at an incorrect
  19.563 +location in the file.  If \command{patch} or \hgxcmd{mq}{qpush} ever
  19.564 +mentions an offset or fuzz factor, you should make sure that the
  19.565 +modified files are correct afterwards.  
  19.566 +
  19.567 +It's often a good idea to refresh a patch that has applied with an
  19.568 +offset or fuzz factor; refreshing the patch generates new context
  19.569 +information that will make it apply cleanly.  I say ``often,'' not
  19.570 +``always,'' because sometimes refreshing a patch will make it fail to
  19.571 +apply against a different revision of the underlying files.  In some
  19.572 +cases, such as when you're maintaining a patch that must sit on top of
  19.573 +multiple versions of a source tree, it's acceptable to have a patch
  19.574 +apply with some fuzz, provided you've verified the results of the
  19.575 +patching process in such cases.
  19.576 +
  19.577 +\subsection{Handling rejection}
  19.578 +
  19.579 +If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
  19.580 +message and exit.  If it has left \sfilename{.rej} files behind, it is
  19.581 +usually best to fix up the rejected hunks before you push more patches
  19.582 +or do any further work.
  19.583 +
  19.584 +If your patch \emph{used to} apply cleanly, and no longer does because
  19.585 +you've changed the underlying code that your patches are based on,
  19.586 +Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.
  19.587 +
  19.588 +Unfortunately, there aren't any great techniques for dealing with
  19.589 +rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
  19.590 +file and edit the target file, applying the rejected hunks by hand.
  19.591 +
  19.592 +If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
  19.593 +wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
  19.594 +vigorous than \command{patch} in its attempts to make a patch apply.
  19.595 +
  19.596 +Another Linux kernel hacker, Chris Mason (the author of Mercurial
  19.597 +Queues), wrote a similar tool called
  19.598 +\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
  19.599 +automating the application of hunks rejected by \command{patch}.  The
  19.600 +\command{mpatch} command can help with four common reasons that a hunk
  19.601 +may be rejected:
  19.602 +
  19.603 +\begin{itemize}
  19.604 +\item The context in the middle of a hunk has changed.
  19.605 +\item A hunk is missing some context at the beginning or end.
  19.606 +\item A large hunk might apply better---either entirely or in
  19.607 +  part---if it was broken up into smaller hunks.
  19.608 +\item A hunk removes lines with slightly different content than those
  19.609 +  currently present in the file.
  19.610 +\end{itemize}
  19.611 +
  19.612 +If you use \command{wiggle} or \command{mpatch}, you should be doubly
  19.613 +careful to check your results when you're done.  In fact,
  19.614 +\command{mpatch} enforces this method of double-checking the tool's
  19.615 +output, by automatically dropping you into a merge program when it has
  19.616 +done its job, so that you can verify its work and finish off any
  19.617 +remaining merges.
  19.618 +
  19.619 +\section{Getting the best performance out of MQ}
  19.620 +\label{sec:mq:perf}
  19.621 +
  19.622 +MQ is very efficient at handling a large number of patches.  I ran
  19.623 +some performance experiments in mid-2006 for a talk that I gave at the
  19.624 +2006 EuroPython conference~\cite{web:europython}.  I used as my data
  19.625 +set the Linux 2.6.17-mm1 patch series, which consists of 1,738
  19.626 +patches.  I applied these on top of a Linux kernel repository
  19.627 +containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
  19.628 +2.6.17.
  19.629 +
  19.630 +On my old, slow laptop, I was able to
  19.631 +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
  19.632 +and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds.  (On a
  19.633 +newer laptop, the time to push all patches dropped to two minutes.)  I
  19.634 +could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
  19.635 +lines of changes to 287 files) in 6.6 seconds.
  19.636 +
  19.637 +Clearly, MQ is well suited to working in large trees, but there are a
  19.638 +few tricks you can use to get the best performance of it.
  19.639 +
  19.640 +First of all, try to ``batch'' operations together.  Every time you
  19.641 +run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
  19.642 +directory once to make sure you haven't made some changes and then
  19.643 +forgotten to run \hgxcmd{mq}{qrefresh}.  On a small tree, the time that
  19.644 +this scan takes is unnoticeable.  However, on a medium-sized tree
  19.645 +(containing tens of thousands of files), it can take a second or more.
  19.646 +
  19.647 +The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
  19.648 +multiple patches at a time.  You can identify the ``destination
  19.649 +patch'' that you want to end up at.  When you \hgxcmd{mq}{qpush} with a
  19.650 +destination specified, it will push patches until that patch is at the
  19.651 +top of the applied stack.  When you \hgxcmd{mq}{qpop} to a destination, MQ
  19.652 +will pop patches until the destination patch is at the top.
  19.653 +
  19.654 +You can identify a destination patch using either the name of the
  19.655 +patch, or by number.  If you use numeric addressing, patches are
  19.656 +counted from zero; this means that the first patch is zero, the second
  19.657 +is one, and so on.
  19.658 +
  19.659 +\section{Updating your patches when the underlying code changes}
  19.660 +\label{sec:mq:merge}
  19.661 +
  19.662 +It's common to have a stack of patches on top of an underlying
  19.663 +repository that you don't modify directly.  If you're working on
  19.664 +changes to third-party code, or on a feature that is taking longer to
  19.665 +develop than the rate of change of the code beneath, you will often
  19.666 +need to sync up with the underlying code, and fix up any hunks in your
  19.667 +patches that no longer apply.  This is called \emph{rebasing} your
  19.668 +patch series.
  19.669 +
  19.670 +The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}
  19.671 +your patches, then \hgcmd{pull} changes into the underlying
  19.672 +repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your
  19.673 +patches again.  MQ will stop pushing any time it runs across a patch
  19.674 +that fails to apply during conflicts, allowing you to fix your
  19.675 +conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing
  19.676 +until you have fixed your entire stack.
  19.677 +
  19.678 +This approach is easy to use and works well if you don't expect
  19.679 +changes to the underlying code to affect how well your patches apply.
  19.680 +If your patch stack touches code that is modified frequently or
  19.681 +invasively in the underlying repository, however, fixing up rejected
  19.682 +hunks by hand quickly becomes tiresome.
  19.683 +
  19.684 +It's possible to partially automate the rebasing process.  If your
  19.685 +patches apply cleanly against some revision of the underlying repo, MQ
  19.686 +can use this information to help you to resolve conflicts between your
  19.687 +patches and a different revision.
  19.688 +
  19.689 +The process is a little involved.
  19.690 +\begin{enumerate}
  19.691 +\item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of
  19.692 +  the revision where you know that they apply cleanly.
  19.693 +\item Save a backup copy of your patch directory using
  19.694 +  \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}.  This prints
  19.695 +  the name of the directory that it has saved the patches in.  It will
  19.696 +  save the patches to a directory called
  19.697 +  \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small
  19.698 +  integer.  It also commits a ``save changeset'' on top of your
  19.699 +  applied patches; this is for internal book-keeping, and records the
  19.700 +  states of the \sfilename{series} and \sfilename{status} files.
  19.701 +\item Use \hgcmd{pull} to bring new changes into the underlying
  19.702 +  repository.  (Don't run \hgcmdargs{pull}{-u}; see below for why.)
  19.703 +\item Update to the new tip revision, using
  19.704 +  \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
  19.705 +  have pushed.
  19.706 +\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}
  19.707 +    \hgxopt{mq}{qpush}{-a}}.  The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush}
  19.708 +  tells MQ to perform a three-way merge if the patch fails to apply.
  19.709 +\end{enumerate}
  19.710 +
  19.711 +During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the
  19.712 +\sfilename{series} file is applied normally.  If a patch applies with
  19.713 +fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and
  19.714 +performs a three-way merge with the corresponding changeset.  This
  19.715 +merge uses Mercurial's normal merge machinery, so it may pop up a GUI
  19.716 +merge tool to help you to resolve problems.
  19.717 +
  19.718 +When you finish resolving the effects of a patch, MQ refreshes your
  19.719 +patch based on the result of the merge.
  19.720 +
  19.721 +At the end of this process, your repository will have one extra head
  19.722 +from the old patch queue, and a copy of the old patch queue will be in
  19.723 +\sdirname{.hg/patches.\emph{N}}. You can remove the extra head using
  19.724 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}
  19.725 +or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
  19.726 +you are sure that you no longer need it as a backup.
  19.727 +
  19.728 +\section{Identifying patches}
  19.729 +
  19.730 +MQ commands that work with patches let you refer to a patch either by
  19.731 +using its name or by a number.  By name is obvious enough; pass the
  19.732 +name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will
  19.733 +push patches until \filename{foo.patch} is applied.  
  19.734 +
  19.735 +As a shortcut, you can refer to a patch using both a name and a
  19.736 +numeric offset; \texttt{foo.patch-2} means ``two patches before
  19.737 +\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
  19.738 +after \texttt{bar.patch}''.
  19.739 +
  19.740 +Referring to a patch by index isn't much different.  The first patch
  19.741 +printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one
  19.742 +of those start-at-zero counting systems); the second is patch one; and
  19.743 +so on.
  19.744 +
  19.745 +MQ also makes it easy to work with patches when you are using normal
  19.746 +Mercurial commands.  Every command that accepts a changeset ID will
  19.747 +also accept the name of an applied patch.  MQ augments the tags
  19.748 +normally in the repository with an eponymous one for each applied
  19.749 +patch.  In addition, the special tags \index{tags!special tag
  19.750 +  names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
  19.751 +  names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
  19.752 +topmost applied patches, respectively.
  19.753 +
  19.754 +These additions to Mercurial's normal tagging capabilities make
  19.755 +dealing with patches even more of a breeze.
  19.756 +\begin{itemize}
  19.757 +\item Want to patchbomb a mailing list with your latest series of
  19.758 +  changes?
  19.759 +  \begin{codesample4}
  19.760 +    hg email qbase:qtip
  19.761 +  \end{codesample4}
  19.762 +  (Don't know what ``patchbombing'' is?  See
  19.763 +  section~\ref{sec:hgext:patchbomb}.)
  19.764 +\item Need to see all of the patches since \texttt{foo.patch} that
  19.765 +  have touched files in a subdirectory of your tree?
  19.766 +  \begin{codesample4}
  19.767 +    hg log -r foo.patch:qtip \emph{subdir}
  19.768 +  \end{codesample4}
  19.769 +\end{itemize}
  19.770 +
  19.771 +Because MQ makes the names of patches available to the rest of
  19.772 +Mercurial through its normal internal tag machinery, you don't need to
  19.773 +type in the entire name of a patch when you want to identify it by
  19.774 +name.
  19.775 +
  19.776 +\begin{figure}[ht]
  19.777 +  \interaction{mq.id.output}
  19.778 +  \caption{Using MQ's tag features to work with patches}
  19.779 +  \label{ex:mq:id}
  19.780 +\end{figure}
  19.781 +
  19.782 +Another nice consequence of representing patch names as tags is that
  19.783 +when you run the \hgcmd{log} command, it will display a patch's name
  19.784 +as a tag, simply as part of its normal output.  This makes it easy to
  19.785 +visually distinguish applied patches from underlying ``normal''
  19.786 +revisions.  Figure~\ref{ex:mq:id} shows a few normal Mercurial
  19.787 +commands in use with applied patches.
  19.788 +
  19.789 +\section{Useful things to know about}
  19.790 +
  19.791 +There are a number of aspects of MQ usage that don't fit tidily into
  19.792 +sections of their own, but that are good to know.  Here they are, in
  19.793 +one place.
  19.794 +
  19.795 +\begin{itemize}
  19.796 +\item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it
  19.797 +  again, the changeset that represents the patch after the pop/push
  19.798 +  will have a \emph{different identity} than the changeset that
  19.799 +  represented the hash beforehand.  See
  19.800 +  section~\ref{sec:mqref:cmd:qpush} for information as to why this is.
  19.801 +\item It's not a good idea to \hgcmd{merge} changes from another
  19.802 +  branch with a patch changeset, at least if you want to maintain the
  19.803 +  ``patchiness'' of that changeset and changesets below it on the
  19.804 +  patch stack.  If you try to do this, it will appear to succeed, but
  19.805 +  MQ will become confused.
  19.806 +\end{itemize}
  19.807 +
  19.808 +\section{Managing patches in a repository}
  19.809 +\label{sec:mq:repo}
  19.810 +
  19.811 +Because MQ's \sdirname{.hg/patches} directory resides outside a
  19.812 +Mercurial repository's working directory, the ``underlying'' Mercurial
  19.813 +repository knows nothing about the management or presence of patches.
  19.814 +
  19.815 +This presents the interesting possibility of managing the contents of
  19.816 +the patch directory as a Mercurial repository in its own right.  This
  19.817 +can be a useful way to work.  For example, you can work on a patch for
  19.818 +a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of
  19.819 +the patch.  This lets you ``roll back'' to that version of the patch
  19.820 +later on.
  19.821 +
  19.822 +You can then share different versions of the same patch stack among
  19.823 +multiple underlying repositories.  I use this when I am developing a
  19.824 +Linux kernel feature.  I have a pristine copy of my kernel sources for
  19.825 +each of several CPU architectures, and a cloned repository under each
  19.826 +that contains the patches I am working on.  When I want to test a
  19.827 +change on a different architecture, I push my current patches to the
  19.828 +patch repository associated with that kernel tree, pop and push all of
  19.829 +my patches, and build and test that kernel.
  19.830 +
  19.831 +Managing patches in a repository makes it possible for multiple
  19.832 +developers to work on the same patch series without colliding with
  19.833 +each other, all on top of an underlying source base that they may or
  19.834 +may not control.
  19.835 +
  19.836 +\subsection{MQ support for patch repositories}
  19.837 +
  19.838 +MQ helps you to work with the \sdirname{.hg/patches} directory as a
  19.839 +repository; when you prepare a repository for working with patches
  19.840 +using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to
  19.841 +create the \sdirname{.hg/patches} directory as a Mercurial repository.
  19.842 +
  19.843 +\begin{note}
  19.844 +  If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go
  19.845 +  into the \sdirname{.hg/patches} directory at any time and run
  19.846 +  \hgcmd{init}.  Don't forget to add an entry for the
  19.847 +  \sfilename{status} file to the \sfilename{.hgignore} file, though
  19.848 +
  19.849 +  (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you
  19.850 +  automatically); you \emph{really} don't want to manage the
  19.851 +  \sfilename{status} file.
  19.852 +\end{note}
  19.853 +
  19.854 +As a convenience, if MQ notices that the \dirname{.hg/patches}
  19.855 +directory is a repository, it will automatically \hgcmd{add} every
  19.856 +patch that you create and import.
  19.857 +
  19.858 +MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs
  19.859 +\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
  19.860 +some bothersome typing.
  19.861 +
  19.862 +Finally, as a convenience to manage the patch directory, you can
  19.863 +define the alias \command{mq} on Unix systems. For example, on Linux
  19.864 +systems using the \command{bash} shell, you can include the following
  19.865 +snippet in your \tildefile{.bashrc}.
  19.866 +
  19.867 +\begin{codesample2}
  19.868 +  alias mq=`hg -R \$(hg root)/.hg/patches'
  19.869 +\end{codesample2}
  19.870 +
  19.871 +You can then issue commands of the form \cmdargs{mq}{pull} from
  19.872 +the main repository.
  19.873 +
  19.874 +\subsection{A few things to watch out for}
  19.875 +
  19.876 +MQ's support for working with a repository full of patches is limited
  19.877 +in a few small respects.
  19.878 +
  19.879 +MQ cannot automatically detect changes that you make to the patch
  19.880 +directory.  If you \hgcmd{pull}, manually edit, or \hgcmd{update}
  19.881 +changes to patches or the \sfilename{series} file, you will have to
  19.882 +\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then
  19.883 +\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to
  19.884 +see those changes show up there.  If you forget to do this, you can
  19.885 +confuse MQ's idea of which patches are applied.
  19.886 +
  19.887 +\section{Third party tools for working with patches}
  19.888 +\label{sec:mq:tools}
  19.889 +
  19.890 +Once you've been working with patches for a while, you'll find
  19.891 +yourself hungry for tools that will help you to understand and
  19.892 +manipulate the patches you're dealing with.
  19.893 +
  19.894 +The \command{diffstat} command~\cite{web:diffstat} generates a
  19.895 +histogram of the modifications made to each file in a patch.  It
  19.896 +provides a good way to ``get a sense of'' a patch---which files it
  19.897 +affects, and how much change it introduces to each file and as a
  19.898 +whole.  (I find that it's a good idea to use \command{diffstat}'s
  19.899 +\cmdopt{diffstat}{-p} option as a matter of course, as otherwise it
  19.900 +will try to do clever things with prefixes of file names that
  19.901 +inevitably confuse at least me.)
  19.902 +
  19.903 +\begin{figure}[ht]
  19.904 +  \interaction{mq.tools.tools}
  19.905 +  \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands}
  19.906 +  \label{ex:mq:tools}
  19.907 +\end{figure}
  19.908 +
  19.909 +The \package{patchutils} package~\cite{web:patchutils} is invaluable.
  19.910 +It provides a set of small utilities that follow the ``Unix
  19.911 +philosophy;'' each does one useful thing with a patch.  The
  19.912 +\package{patchutils} command I use most is \command{filterdiff}, which
  19.913 +extracts subsets from a patch file.  For example, given a patch that
  19.914 +modifies hundreds of files across dozens of directories, a single
  19.915 +invocation of \command{filterdiff} can generate a smaller patch that
  19.916 +only touches files whose names match a particular glob pattern.  See
  19.917 +section~\ref{mq-collab:tips:interdiff} for another example.
  19.918 +
  19.919 +\section{Good ways to work with patches}
  19.920 +
  19.921 +Whether you are working on a patch series to submit to a free software
  19.922 +or open source project, or a series that you intend to treat as a
  19.923 +sequence of regular changesets when you're done, you can use some
  19.924 +simple techniques to keep your work well organised.
  19.925 +
  19.926 +Give your patches descriptive names.  A good name for a patch might be
  19.927 +\filename{rework-device-alloc.patch}, because it will immediately give
  19.928 +you a hint what the purpose of the patch is.  Long names shouldn't be
  19.929 +a problem; you won't be typing the names often, but you \emph{will} be
  19.930 +running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over.
  19.931 +Good naming becomes especially important when you have a number of
  19.932 +patches to work with, or if you are juggling a number of different
  19.933 +tasks and your patches only get a fraction of your attention.
  19.934 +
  19.935 +Be aware of what patch you're working on.  Use the \hgxcmd{mq}{qtop}
  19.936 +command and skim over the text of your patches frequently---for
  19.937 +example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where
  19.938 +you stand.  I have several times worked on and \hgxcmd{mq}{qrefresh}ed a
  19.939 +patch other than the one I intended, and it's often tricky to migrate
  19.940 +changes into the right patch after making them in the wrong one.
  19.941 +
  19.942 +For this reason, it is very much worth investing a little time to
  19.943 +learn how to use some of the third-party tools I described in
  19.944 +section~\ref{sec:mq:tools}, particularly \command{diffstat} and
  19.945 +\command{filterdiff}.  The former will give you a quick idea of what
  19.946 +changes your patch is making, while the latter makes it easy to splice
  19.947 +hunks selectively out of one patch and into another.
  19.948 +
  19.949 +\section{MQ cookbook}
  19.950 +
  19.951 +\subsection{Manage ``trivial'' patches}
  19.952 +
  19.953 +Because the overhead of dropping files into a new Mercurial repository
  19.954 +is so low, it makes a lot of sense to manage patches this way even if
  19.955 +you simply want to make a few changes to a source tarball that you
  19.956 +downloaded.
  19.957 +
  19.958 +Begin by downloading and unpacking the source tarball,
  19.959 +and turning it into a Mercurial repository.
  19.960 +\interaction{mq.tarball.download}
  19.961 +
  19.962 +Continue by creating a patch stack and making your changes.
  19.963 +\interaction{mq.tarball.qinit}
  19.964 +
  19.965 +Let's say a few weeks or months pass, and your package author releases
  19.966 +a new version.  First, bring their changes into the repository.
  19.967 +\interaction{mq.tarball.newsource}
  19.968 +The pipeline starting with \hgcmd{locate} above deletes all files in
  19.969 +the working directory, so that \hgcmd{commit}'s
  19.970 +\hgopt{commit}{--addremove} option can actually tell which files have
  19.971 +really been removed in the newer version of the source.
  19.972 +
  19.973 +Finally, you can apply your patches on top of the new tree.
  19.974 +\interaction{mq.tarball.repush}
  19.975 +
  19.976 +\subsection{Combining entire patches}
  19.977 +\label{sec:mq:combine}
  19.978 +
  19.979 +MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire
  19.980 +patches.  This ``folds'' the patches you name, in the order you name
  19.981 +them, into the topmost applied patch, and concatenates their
  19.982 +descriptions onto the end of its description.  The patches that you
  19.983 +fold must be unapplied before you fold them.
  19.984 +
  19.985 +The order in which you fold patches matters.  If your topmost applied
  19.986 +patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and
  19.987 +\texttt{quux} into it, you will end up with a patch that has the same
  19.988 +effect as if you applied first \texttt{foo}, then \texttt{bar},
  19.989 +followed by \texttt{quux}.
  19.990 +
  19.991 +\subsection{Merging part of one patch into another}
  19.992 +
  19.993 +Merging \emph{part} of one patch into another is more difficult than
  19.994 +combining entire patches.
  19.995 +
  19.996 +If you want to move changes to entire files, you can use
  19.997 +\command{filterdiff}'s \cmdopt{filterdiff}{-i} and
  19.998 +\cmdopt{filterdiff}{-x} options to choose the modifications to snip
  19.999 +out of one patch, concatenating its output onto the end of the patch
 19.1000 +you want to merge into.  You usually won't need to modify the patch
 19.1001 +you've merged the changes from.  Instead, MQ will report some rejected
 19.1002 +hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the
 19.1003 +other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop
 19.1004 +the duplicate hunks.
 19.1005 +
 19.1006 +If you have a patch that has multiple hunks modifying a file, and you
 19.1007 +only want to move a few of those hunks, the job becomes more messy,
 19.1008 +but you can still partly automate it.  Use \cmdargs{lsdiff}{-nvv} to
 19.1009 +print some metadata about the patch.
 19.1010 +\interaction{mq.tools.lsdiff}
 19.1011 +
 19.1012 +This command prints three different kinds of number:
 19.1013 +\begin{itemize}
 19.1014 +\item (in the first column) a \emph{file number} to identify each file
 19.1015 +  modified in the patch;
 19.1016 +\item (on the next line, indented) the line number within a modified
 19.1017 +  file where a hunk starts; and
 19.1018 +\item (on the same line) a \emph{hunk number} to identify that hunk.
 19.1019 +\end{itemize}
 19.1020 +
 19.1021 +You'll have to use some visual inspection, and reading of the patch,
 19.1022 +to identify the file and hunk numbers you'll want, but you can then
 19.1023 +pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files}
 19.1024 +and \cmdopt{filterdiff}{--hunks} options, to select exactly the file
 19.1025 +and hunk you want to extract.
 19.1026 +
 19.1027 +Once you have this hunk, you can concatenate it onto the end of your
 19.1028 +destination patch and continue with the remainder of
 19.1029 +section~\ref{sec:mq:combine}.
 19.1030 +
 19.1031 +\section{Differences between quilt and MQ}
 19.1032 +
 19.1033 +If you are already familiar with quilt, MQ provides a similar command
 19.1034 +set.  There are a few differences in the way that it works.
 19.1035 +
 19.1036 +You will already have noticed that most quilt commands have MQ
 19.1037 +counterparts that simply begin with a ``\texttt{q}''.  The exceptions
 19.1038 +are quilt's \texttt{add} and \texttt{remove} commands, the
 19.1039 +counterparts for which are the normal Mercurial \hgcmd{add} and
 19.1040 +\hgcmd{remove} commands.  There is no MQ equivalent of the quilt
 19.1041 +\texttt{edit} command.
 19.1042 +
 19.1043 +%%% Local Variables: 
 19.1044 +%%% mode: latex
 19.1045 +%%% TeX-master: "00book"
 19.1046 +%%% End: 

    20.1 Binary file es/note.png has changed

    21.1 --- a/es/tour-merge.tex	Sat Oct 18 14:35:43 2008 -0500
    21.2 +++ b/es/tour-merge.tex	Sat Oct 18 15:44:41 2008 -0500
    21.3 @@ -0,0 +1,283 @@
    21.4 +\chapter{A tour of Mercurial: merging work}
    21.5 +\label{chap:tour-merge}
    21.6 +
    21.7 +We've now covered cloning a repository, making changes in a
    21.8 +repository, and pulling or pushing changes from one repository into
    21.9 +another.  Our next step is \emph{merging} changes from separate
   21.10 +repositories.
   21.11 +
   21.12 +\section{Merging streams of work}
   21.13 +
   21.14 +Merging is a fundamental part of working with a distributed revision
   21.15 +control tool.
   21.16 +\begin{itemize}
   21.17 +\item Alice and Bob each have a personal copy of a repository for a
   21.18 +  project they're collaborating on.  Alice fixes a bug in her
   21.19 +  repository; Bob adds a new feature in his.  They want the shared
   21.20 +  repository to contain both the bug fix and the new feature.
   21.21 +\item I frequently work on several different tasks for a single
   21.22 +  project at once, each safely isolated in its own repository.
   21.23 +  Working this way means that I often need to merge one piece of my
   21.24 +  own work with another.
   21.25 +\end{itemize}
   21.26 +
   21.27 +Because merging is such a common thing to need to do, Mercurial makes
   21.28 +it easy.  Let's walk through the process.  We'll begin by cloning yet
   21.29 +another repository (see how often they spring up?) and making a change
   21.30 +in it.
   21.31 +\interaction{tour.merge.clone}
   21.32 +We should now have two copies of \filename{hello.c} with different
   21.33 +contents.  The histories of the two repositories have also diverged,
   21.34 +as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
   21.35 +\interaction{tour.merge.cat}
   21.36 +
   21.37 +\begin{figure}[ht]
   21.38 +  \centering
   21.39 +  \grafix{tour-merge-sep-repos}
   21.40 +  \caption{Divergent recent histories of the \dirname{my-hello} and
   21.41 +    \dirname{my-new-hello} repositories}
   21.42 +  \label{fig:tour-merge:sep-repos}
   21.43 +\end{figure}
   21.44 +
   21.45 +We already know that pulling changes from our \dirname{my-hello}
   21.46 +repository will have no effect on the working directory.
   21.47 +\interaction{tour.merge.pull}
   21.48 +However, the \hgcmd{pull} command says something about ``heads''.  
   21.49 +
   21.50 +\subsection{Head changesets}
   21.51 +
   21.52 +A head is a change that has no descendants, or children, as they're
   21.53 +also known.  The tip revision is thus a head, because the newest
   21.54 +revision in a repository doesn't have any children, but a repository
   21.55 +can contain more than one head.
   21.56 +
   21.57 +\begin{figure}[ht]
   21.58 +  \centering
   21.59 +  \grafix{tour-merge-pull}
   21.60 +  \caption{Repository contents after pulling from \dirname{my-hello} into
   21.61 +    \dirname{my-new-hello}}
   21.62 +  \label{fig:tour-merge:pull}
   21.63 +\end{figure}
   21.64 +
   21.65 +In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
   21.66 +pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
   21.67 +that was already present in \dirname{my-new-hello} is untouched, but a
   21.68 +new revision has been added.  By referring to
   21.69 +figure~\ref{fig:tour-merge:sep-repos}, we can see that the
   21.70 +\emph{changeset ID} remains the same in the new repository, but the
   21.71 +\emph{revision number} has changed.  (This, incidentally, is a fine
   21.72 +example of why it's not safe to use revision numbers when discussing
   21.73 +changesets.)  We can view the heads in a repository using the
   21.74 +\hgcmd{heads} command.
   21.75 +\interaction{tour.merge.heads}
   21.76 +
   21.77 +\subsection{Performing the merge}
   21.78 +
   21.79 +What happens if we try to use the normal \hgcmd{update} command to
   21.80 +update to the new tip?
   21.81 +\interaction{tour.merge.update}
   21.82 +Mercurial is telling us that the \hgcmd{update} command won't do a
   21.83 +merge; it won't update the working directory when it thinks we might
   21.84 +be wanting to do a merge, unless we force it to do so.  Instead, we
   21.85 +use the \hgcmd{merge} command to merge the two heads.
   21.86 +\interaction{tour.merge.merge}
   21.87 +
   21.88 +\begin{figure}[ht]
   21.89 +  \centering
   21.90 +  \grafix{tour-merge-merge}
   21.91 +  \caption{Working directory and repository during merge, and
   21.92 +    following commit}
   21.93 +  \label{fig:tour-merge:merge}
   21.94 +\end{figure}
   21.95 +
   21.96 +This updates the working directory so that it contains changes from
   21.97 +\emph{both} heads, which is reflected in both the output of
   21.98 +\hgcmd{parents} and the contents of \filename{hello.c}.
   21.99 +\interaction{tour.merge.parents}
  21.100 +
  21.101 +\subsection{Committing the results of the merge}
  21.102 +
  21.103 +Whenever we've done a merge, \hgcmd{parents} will display two parents
  21.104 +until we \hgcmd{commit} the results of the merge.
  21.105 +\interaction{tour.merge.commit}
  21.106 +We now have a new tip revision; notice that it has \emph{both} of
  21.107 +our former heads as its parents.  These are the same revisions that
  21.108 +were previously displayed by \hgcmd{parents}.
  21.109 +\interaction{tour.merge.tip}
  21.110 +In figure~\ref{fig:tour-merge:merge}, you can see a representation of
  21.111 +what happens to the working directory during the merge, and how this
  21.112 +affects the repository when the commit happens.  During the merge, the
  21.113 +working directory has two parent changesets, and these become the
  21.114 +parents of the new changeset.
  21.115 +
  21.116 +\section{Merging conflicting changes}
  21.117 +
  21.118 +Most merges are simple affairs, but sometimes you'll find yourself
  21.119 +merging changes where each modifies the same portions of the same
  21.120 +files.  Unless both modifications are identical, this results in a
  21.121 +\emph{conflict}, where you have to decide how to reconcile the
  21.122 +different changes into something coherent.
  21.123 +
  21.124 +\begin{figure}[ht]
  21.125 +  \centering
  21.126 +  \grafix{tour-merge-conflict}
  21.127 +  \caption{Conflicting changes to a document}
  21.128 +  \label{fig:tour-merge:conflict}
  21.129 +\end{figure}
  21.130 +
  21.131 +Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
  21.132 +conflicting changes to a document.  We started with a single version
  21.133 +of the file; then we made some changes; while someone else made
  21.134 +different changes to the same text.  Our task in resolving the
  21.135 +conflicting changes is to decide what the file should look like.
  21.136 +
  21.137 +Mercurial doesn't have a built-in facility for handling conflicts.
  21.138 +Instead, it runs an external program called \command{hgmerge}.  This
  21.139 +is a shell script that is bundled with Mercurial; you can change it to
  21.140 +behave however you please.  What it does by default is try to find one
  21.141 +of several different merging tools that are likely to be installed on
  21.142 +your system.  It first tries a few fully automatic merging tools; if
  21.143 +these don't succeed (because the resolution process requires human
  21.144 +guidance) or aren't present, the script tries a few different
  21.145 +graphical merging tools.
  21.146 +
  21.147 +It's also possible to get Mercurial to run another program or script
  21.148 +instead of \command{hgmerge}, by setting the \envar{HGMERGE}
  21.149 +environment variable to the name of your preferred program.
  21.150 +
  21.151 +\subsection{Using a graphical merge tool}
  21.152 +
  21.153 +My preferred graphical merge tool is \command{kdiff3}, which I'll use
  21.154 +to describe the features that are common to graphical file merging
  21.155 +tools.  You can see a screenshot of \command{kdiff3} in action in
  21.156 +figure~\ref{fig:tour-merge:kdiff3}.  The kind of merge it is
  21.157 +performing is called a \emph{three-way merge}, because there are three
  21.158 +different versions of the file of interest to us.  The tool thus
  21.159 +splits the upper portion of the window into three panes:
  21.160 +\begin{itemize}
  21.161 +\item At the left is the \emph{base} version of the file, i.e.~the
  21.162 +  most recent version from which the two versions we're trying to
  21.163 +  merge are descended.
  21.164 +\item In the middle is ``our'' version of the file, with the contents
  21.165 +  that we modified.
  21.166 +\item On the right is ``their'' version of the file, the one that
  21.167 +  from the changeset that we're trying to merge with.
  21.168 +\end{itemize}
  21.169 +In the pane below these is the current \emph{result} of the merge.
  21.170 +Our task is to replace all of the red text, which indicates unresolved
  21.171 +conflicts, with some sensible merger of the ``ours'' and ``theirs''
  21.172 +versions of the file.
  21.173 +
  21.174 +All four of these panes are \emph{locked together}; if we scroll
  21.175 +vertically or horizontally in any of them, the others are updated to
  21.176 +display the corresponding sections of their respective files.
  21.177 +
  21.178 +\begin{figure}[ht]
  21.179 +  \centering
  21.180 +  \grafix{kdiff3}
  21.181 +  \caption{Using \command{kdiff3} to merge versions of a file}
  21.182 +  \label{fig:tour-merge:kdiff3}
  21.183 +\end{figure}
  21.184 +
  21.185 +For each conflicting portion of the file, we can choose to resolve
  21.186 +the conflict using some combination of text from the base version,
  21.187 +ours, or theirs.  We can also manually edit the merged file at any
  21.188 +time, in case we need to make further modifications.
  21.189 +
  21.190 +There are \emph{many} file merging tools available, too many to cover
  21.191 +here.  They vary in which platforms they are available for, and in
  21.192 +their particular strengths and weaknesses.  Most are tuned for merging
  21.193 +files containing plain text, while a few are aimed at specialised file
  21.194 +formats (generally XML).
  21.195 +
  21.196 +\subsection{A worked example}
  21.197 +
  21.198 +In this example, we will reproduce the file modification history of
  21.199 +figure~\ref{fig:tour-merge:conflict} above.  Let's begin by creating a
  21.200 +repository with a base version of our document.
  21.201 +\interaction{tour-merge-conflict.wife}
  21.202 +We'll clone the repository and make a change to the file.
  21.203 +\interaction{tour-merge-conflict.cousin}
  21.204 +And another clone, to simulate someone else making a change to the
  21.205 +file.  (This hints at the idea that it's not all that unusual to merge
  21.206 +with yourself when you isolate tasks in separate repositories, and
  21.207 +indeed to find and resolve conflicts while doing so.)
  21.208 +\interaction{tour-merge-conflict.son}
  21.209 +Having created two different versions of the file, we'll set up an
  21.210 +environment suitable for running our merge.
  21.211 +\interaction{tour-merge-conflict.pull}
  21.212 +
  21.213 +In this example, I won't use Mercurial's normal \command{hgmerge}
  21.214 +program to do the merge, because it would drop my nice automated
  21.215 +example-running tool into a graphical user interface.  Instead, I'll
  21.216 +set \envar{HGMERGE} to tell Mercurial to use the non-interactive
  21.217 +\command{merge} command.  This is bundled with many Unix-like systems.
  21.218 +If you're following this example on your computer, don't bother
  21.219 +setting \envar{HGMERGE}.
  21.220 +\interaction{tour-merge-conflict.merge}
  21.221 +Because \command{merge} can't resolve the conflicting changes, it
  21.222 +leaves \emph{merge markers} inside the file that has conflicts,
  21.223 +indicating which lines have conflicts, and whether they came from our
  21.224 +version of the file or theirs.
  21.225 +
  21.226 +Mercurial can tell from the way \command{merge} exits that it wasn't
  21.227 +able to merge successfully, so it tells us what commands we'll need to
  21.228 +run if we want to redo the merging operation.  This could be useful
  21.229 +if, for example, we were running a graphical merge tool and quit
  21.230 +because we were confused or realised we had made a mistake.
  21.231 +
  21.232 +If automatic or manual merges fail, there's nothing to prevent us from
  21.233 +``fixing up'' the affected files ourselves, and committing the results
  21.234 +of our merge:
  21.235 +\interaction{tour-merge-conflict.commit}
  21.236 +
  21.237 +\section{Simplifying the pull-merge-commit sequence}
  21.238 +\label{sec:tour-merge:fetch}
  21.239 +
  21.240 +The process of merging changes as outlined above is straightforward,
  21.241 +but requires running three commands in sequence.
  21.242 +\begin{codesample2}
  21.243 +  hg pull
  21.244 +  hg merge
  21.245 +  hg commit -m 'Merged remote changes'
  21.246 +\end{codesample2}
  21.247 +In the case of the final commit, you also need to enter a commit
  21.248 +message, which is almost always going to be a piece of uninteresting
  21.249 +``boilerplate'' text.
  21.250 +
  21.251 +It would be nice to reduce the number of steps needed, if this were
  21.252 +possible.  Indeed, Mercurial is distributed with an extension called
  21.253 +\hgext{fetch} that does just this.
  21.254 +
  21.255 +Mercurial provides a flexible extension mechanism that lets people
  21.256 +extend its functionality, while keeping the core of Mercurial small
  21.257 +and easy to deal with.  Some extensions add new commands that you can
  21.258 +use from the command line, while others work ``behind the scenes,''
  21.259 +for example adding capabilities to the server.
  21.260 +
  21.261 +The \hgext{fetch} extension adds a new command called, not
  21.262 +surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
  21.263 +\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
  21.264 +changes from another repository into the current repository.  If it
  21.265 +finds that the changes added a new head to the repository, it begins a
  21.266 +merge, then commits the result of the merge with an
  21.267 +automatically-generated commit message.  If no new heads were added,
  21.268 +it updates the working directory to the new tip changeset.
  21.269 +
  21.270 +Enabling the \hgext{fetch} extension is easy.  Edit your
  21.271 +\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
  21.272 +or create an \rcsection{extensions} section.  Then add a line that
  21.273 +simply reads ``\Verb+fetch +''.
  21.274 +\begin{codesample2}
  21.275 +  [extensions]
  21.276 +  fetch =
  21.277 +\end{codesample2}
  21.278 +(Normally, on the right-hand side of the ``\texttt{=}'' would appear
  21.279 +the location of the extension, but since the \hgext{fetch} extension
  21.280 +is in the standard distribution, Mercurial knows where to search for
  21.281 +it.)
  21.282 +
  21.283 +%%% Local Variables: 
  21.284 +%%% mode: latex
  21.285 +%%% TeX-master: "00book"
  21.286 +%%% End: