1.1 --- a/en/99defs.tex	Mon Jul 03 12:35:44 2006 -0700
     1.2 +++ b/en/99defs.tex	Mon Jul 03 17:12:11 2006 -0700
     1.3 @@ -2,6 +2,7 @@
     1.4  \newcommand{\filename}[1]{\texttt{#1}}
     1.5  \newcommand{\hgext}[1]{\texttt{#1}}
     1.6  \newcommand{\hgcmd}[1]{``\texttt{hg #1}''}
     1.7 +\newcommand{\command}[1]{\texttt{#1}}
     1.8  \newcommand{\hgcmdargs}[2]{``\texttt{hg #1 #2}''}
     1.9  
    1.10  \newsavebox{\notebox}

     2.1 --- a/en/mq.tex	Mon Jul 03 12:35:44 2006 -0700
     2.2 +++ b/en/mq.tex	Mon Jul 03 17:12:11 2006 -0700
     2.3 @@ -318,6 +318,80 @@
     2.4  \hgcmd{qrefresh} the core patch, and \hgcmd{qpush} back to the UI
     2.5  patch to continue where you left off.
     2.6  
     2.7 +\section{Mercurial Queues and GNU patch}
     2.8 +
     2.9 +MQ uses the GNU \command{patch} command to apply patches.  It will
    2.10 +help you to understand the data that MQ and \command{patch} work with,
    2.11 +and a few aspects of how \command{patch} operates.
    2.12 +
    2.13 +A patch file can start with arbitrary text; MQ uses this text as the
    2.14 +commit message when creating changesets.  It treats the first line
    2.15 +that starts with the string ``\texttt{diff~-}'' as the separator
    2.16 +between header and content.
    2.17 +
    2.18 +MQ works with \emph{unified diffs} (\command{patch} can accept several
    2.19 +other kinds of diff, but MQ doesn't).  A unified diff contains two
    2.20 +kinds of header.  The \emph{file header} describes the file being
    2.21 +modified; it contains the name of the file to modify.  When
    2.22 +\command{patch} sees a new file header, it looks for a file of that
    2.23 +name to start modifying.
    2.24 +
    2.25 +After the file header come a series of \emph{hunks}.  Each hunk starts
    2.26 +with a header; this identifies the range of line numbers within the
    2.27 +file that the hunk should modify.  Following the header, a hunk starts
    2.28 +and ends with a few lines of text from the unmodified file; these are
    2.29 +called the \emph{context} for the hunk.  Each unmodified line begins
    2.30 +with a space characters.  Within the hunk, a line that begins with
    2.31 +``\texttt{-}'' means ``remove this line,'' while a line that begins
    2.32 +with ``\texttt{+}'' means ``insert this line.''  For example, a line
    2.33 +that is modified is represented by one deletion and one insertion.
    2.34 +
    2.35 +When \command{patch} applies a hunk, it tries a handful of
    2.36 +successively less accurate strategies to try to make the hunk apply.
    2.37 +This falling-back technique often makes it possible to take a patch
    2.38 +that was generated against an old version of a file, and apply it
    2.39 +against a newer version of that file.
    2.40 +
    2.41 +First, \command{patch} tries an exact match, where the line numbers,
    2.42 +the context, and the text to be modified must apply exactly.  If it
    2.43 +cannot make an exact match, it tries to find an exact match for the
    2.44 +context, without honouring the line numbering information.  If this
    2.45 +succeeds, it prints a line of output saying that the hunk was applied,
    2.46 +but at some \emph{offset} from the original line number.
    2.47 +
    2.48 +If a context-only match fails, \command{patch} removes the first and
    2.49 +last lines of the context, and tries a \emph{reduced} context-only
    2.50 +match.  If the hunk with reduced context succeeds, it prints a message
    2.51 +saying that it applied the hunk with a \emph{fuzz factor} (the number
    2.52 +after the fuzz factor indicates how many lines of context
    2.53 +\command{patch} had to trim before the patch applied).
    2.54 +
    2.55 +When neither of these techniques works, \command{patch} prints a
    2.56 +message saying that the hunk in question was rejected.  It saves
    2.57 +rejected hunks to a file with the same name, and an added
    2.58 +\filename{.rej} extension.  If \hgcmd{qpush} fails to apply a patch,
    2.59 +it will print an error message and exit.
    2.60 +
    2.61 +\subsection{Beware the fuzz}
    2.62 +
    2.63 +While applying a hunk at an offset, or with a fuzz factor, will often
    2.64 +be completely successful, these inexact techniques naturally leave
    2.65 +open the possibility of corrupting the patched file.  The most common
    2.66 +cases typically involve applying a patch twice, or at an incorrect
    2.67 +location in the file.  If \command{patch} or \hgcmd{qpush} ever
    2.68 +mentions an offset or fuzz factor, you should make sure that the
    2.69 +modified files are correct afterwards.  
    2.70 +
    2.71 +It's often a good idea to refresh a patch that has applied with an
    2.72 +offset or fuzz factor; refreshing the patch generates new context
    2.73 +information that will make it apply cleanly.  I say ``often,'' not
    2.74 +``always,'' because sometimes refreshing a patch will make it fail to
    2.75 +apply against a different revision of the underlying files.  In some
    2.76 +cases, such as when you're maintaining a patch that must sit on top of
    2.77 +multiple versions of a source tree, it's acceptable to have a patch
    2.78 +apply with some fuzz, provided you've verified the results of the
    2.79 +patching process in such cases.
    2.80 +
    2.81  
    2.82  %%% Local Variables: 
    2.83  %%% mode: latex