hgbook
changeset 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 |
files | en/99defs.tex en/mq.tex |
line diff
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