hgbook
changeset 336:7e52f0cc4516
changed es/hgext.tex
changed es/hook.tex
changed es/kdiff3.png
changed es/license.tex
changed es/mq-collab.tex
changed es/mq-ref.tex
changed es/mq.tex
changed es/note.png
changed es/tour-merge.tex
changed es/undo-manual-merge.dot
changed es/undo-non-tip.dot
files needed to compile the pdf version of the book.
changed es/hook.tex
changed es/kdiff3.png
changed es/license.tex
changed es/mq-collab.tex
changed es/mq-ref.tex
changed es/mq.tex
changed es/note.png
changed es/tour-merge.tex
changed es/undo-manual-merge.dot
changed es/undo-non-tip.dot
files needed to compile the pdf version of the book.
line diff
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:
22.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 22.2 +++ b/es/undo-manual-merge.dot Sat Oct 18 15:44:41 2008 -0500 22.3 @@ -0,0 +1,8 @@ 22.4 +digraph undo_manual { 22.5 + "first change" -> "second change"; 22.6 + "second change" -> "third change"; 22.7 + backout [label="back out\nsecond change", shape=box]; 22.8 + "second change" -> backout; 22.9 + "third change" -> "manual\nmerge"; 22.10 + backout -> "manual\nmerge"; 22.11 +}
23.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 23.2 +++ b/es/undo-non-tip.dot Sat Oct 18 15:44:41 2008 -0500 23.3 @@ -0,0 +1,9 @@ 23.4 +digraph undo_non_tip { 23.5 + "first change" -> "second change"; 23.6 + "second change" -> "third change"; 23.7 + backout [label="back out\nsecond change", shape=box]; 23.8 + "second change" -> backout; 23.9 + merge [label="automated\nmerge", shape=box]; 23.10 + "third change" -> merge; 23.11 + backout -> merge; 23.12 +}