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