hgbook
diff en/mq.tex @ 14:e2aa527bafa0
Describe unified diffs
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Jul 03 17:12:11 2006 -0700 (2006-07-03) |
parents | 5c3966f6991b |
children | b8ac9f312a47 |
line diff
1.1 --- a/en/mq.tex Mon Jul 03 12:35:44 2006 -0700 1.2 +++ b/en/mq.tex Mon Jul 03 17:12:11 2006 -0700 1.3 @@ -318,6 +318,80 @@ 1.4 \hgcmd{qrefresh} the core patch, and \hgcmd{qpush} back to the UI 1.5 patch to continue where you left off. 1.6 1.7 +\section{Mercurial Queues and GNU patch} 1.8 + 1.9 +MQ uses the GNU \command{patch} command to apply patches. It will 1.10 +help you to understand the data that MQ and \command{patch} work with, 1.11 +and a few aspects of how \command{patch} operates. 1.12 + 1.13 +A patch file can start with arbitrary text; MQ uses this text as the 1.14 +commit message when creating changesets. It treats the first line 1.15 +that starts with the string ``\texttt{diff~-}'' as the separator 1.16 +between header and content. 1.17 + 1.18 +MQ works with \emph{unified diffs} (\command{patch} can accept several 1.19 +other kinds of diff, but MQ doesn't). A unified diff contains two 1.20 +kinds of header. The \emph{file header} describes the file being 1.21 +modified; it contains the name of the file to modify. When 1.22 +\command{patch} sees a new file header, it looks for a file of that 1.23 +name to start modifying. 1.24 + 1.25 +After the file header come a series of \emph{hunks}. Each hunk starts 1.26 +with a header; this identifies the range of line numbers within the 1.27 +file that the hunk should modify. Following the header, a hunk starts 1.28 +and ends with a few lines of text from the unmodified file; these are 1.29 +called the \emph{context} for the hunk. Each unmodified line begins 1.30 +with a space characters. Within the hunk, a line that begins with 1.31 +``\texttt{-}'' means ``remove this line,'' while a line that begins 1.32 +with ``\texttt{+}'' means ``insert this line.'' For example, a line 1.33 +that is modified is represented by one deletion and one insertion. 1.34 + 1.35 +When \command{patch} applies a hunk, it tries a handful of 1.36 +successively less accurate strategies to try to make the hunk apply. 1.37 +This falling-back technique often makes it possible to take a patch 1.38 +that was generated against an old version of a file, and apply it 1.39 +against a newer version of that file. 1.40 + 1.41 +First, \command{patch} tries an exact match, where the line numbers, 1.42 +the context, and the text to be modified must apply exactly. If it 1.43 +cannot make an exact match, it tries to find an exact match for the 1.44 +context, without honouring the line numbering information. If this 1.45 +succeeds, it prints a line of output saying that the hunk was applied, 1.46 +but at some \emph{offset} from the original line number. 1.47 + 1.48 +If a context-only match fails, \command{patch} removes the first and 1.49 +last lines of the context, and tries a \emph{reduced} context-only 1.50 +match. If the hunk with reduced context succeeds, it prints a message 1.51 +saying that it applied the hunk with a \emph{fuzz factor} (the number 1.52 +after the fuzz factor indicates how many lines of context 1.53 +\command{patch} had to trim before the patch applied). 1.54 + 1.55 +When neither of these techniques works, \command{patch} prints a 1.56 +message saying that the hunk in question was rejected. It saves 1.57 +rejected hunks to a file with the same name, and an added 1.58 +\filename{.rej} extension. If \hgcmd{qpush} fails to apply a patch, 1.59 +it will print an error message and exit. 1.60 + 1.61 +\subsection{Beware the fuzz} 1.62 + 1.63 +While applying a hunk at an offset, or with a fuzz factor, will often 1.64 +be completely successful, these inexact techniques naturally leave 1.65 +open the possibility of corrupting the patched file. The most common 1.66 +cases typically involve applying a patch twice, or at an incorrect 1.67 +location in the file. If \command{patch} or \hgcmd{qpush} ever 1.68 +mentions an offset or fuzz factor, you should make sure that the 1.69 +modified files are correct afterwards. 1.70 + 1.71 +It's often a good idea to refresh a patch that has applied with an 1.72 +offset or fuzz factor; refreshing the patch generates new context 1.73 +information that will make it apply cleanly. I say ``often,'' not 1.74 +``always,'' because sometimes refreshing a patch will make it fail to 1.75 +apply against a different revision of the underlying files. In some 1.76 +cases, such as when you're maintaining a patch that must sit on top of 1.77 +multiple versions of a source tree, it's acceptable to have a patch 1.78 +apply with some fuzz, provided you've verified the results of the 1.79 +patching process in such cases. 1.80 + 1.81 1.82 %%% Local Variables: 1.83 %%% mode: latex