hgbook
changeset 15:b8ac9f312a47
Document wiggle and rej
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Jul 03 17:58:29 2006 -0700 (2006-07-03) |
parents | e2aa527bafa0 |
children | 81454425eee9 |
files | en/99book.bib en/mq.tex |
line diff
1.1 --- a/en/99book.bib Mon Jul 03 17:12:11 2006 -0700 1.2 +++ b/en/99book.bib Mon Jul 03 17:58:29 2006 -0700 1.3 @@ -1,6 +1,6 @@ 1.4 @Unpublished{gruenbacher:2005, 1.5 author = {Andreas Gruenbacher}, 1.6 - title = {How To Survive With Many Patches (Introduction to Quilt)}, 1.7 + title = {How To Survive With Many Patches (Introduction to \texttt{quilt})}, 1.8 year = {2005}, 1.9 month = {June}, 1.10 note = {\url{http://www.suse.de/~agruen/quilt.pdf}}, 1.11 @@ -12,3 +12,15 @@ 1.12 note = {\url{http://savannah.nongnu.org/projects/quilt}}, 1.13 } 1.14 1.15 +@Misc{web:rej, 1.16 + author = {Chris Mason}, 1.17 + title = {\texttt{rej}--help solve patch rejects}, 1.18 + note = {\url{ftp://ftp.suse.com/pub/people/mason/rej/}}, 1.19 +} 1.20 + 1.21 +@Misc{web:wiggle, 1.22 + author = {Neil Brown}, 1.23 + title = {\texttt{wiggle}--apply conflicting patches}, 1.24 + note = {\url{http://cgi.cse.unsw.edu.au/~neilb/source/wiggle/}}, 1.25 +} 1.26 +
2.1 --- a/en/mq.tex Mon Jul 03 17:12:11 2006 -0700 2.2 +++ b/en/mq.tex Mon Jul 03 17:58:29 2006 -0700 2.3 @@ -29,7 +29,8 @@ 2.4 they will build properly in their environments. 2.5 2.6 When you have few changes to maintain, it is easy to manage a single 2.7 -patch using the standard \texttt{diff} and \texttt{patch} programs. 2.8 +patch using the standard \texttt{diff} and \texttt{patch} programs 2.9 +(see section~\ref{sec:mq:patch} for a discussion of these tools). 2.10 Once the number of changes grows, it starts to makes sense to maintain 2.11 patches as discrete ``chunks of work,'' so that for example a single 2.12 patch will contain only one bug fix (the patch might modify several 2.13 @@ -319,32 +320,43 @@ 2.14 patch to continue where you left off. 2.15 2.16 \section{Mercurial Queues and GNU patch} 2.17 +\label{sec:mq:patch} 2.18 2.19 MQ uses the GNU \command{patch} command to apply patches. It will 2.20 help you to understand the data that MQ and \command{patch} work with, 2.21 and a few aspects of how \command{patch} operates. 2.22 2.23 +The \command{diff} command generates a list of modifications by 2.24 +comparing two files. The \command{patch} command applies a list of 2.25 +modifications to a file. The kinds of files that \command{diff} and 2.26 +\command{patch} work with are referred to as both ``diffs'' and 2.27 +``patches;'' there is no difference between a diff and a patch. 2.28 + 2.29 A patch file can start with arbitrary text; MQ uses this text as the 2.30 commit message when creating changesets. It treats the first line 2.31 that starts with the string ``\texttt{diff~-}'' as the separator 2.32 between header and content. 2.33 2.34 -MQ works with \emph{unified diffs} (\command{patch} can accept several 2.35 -other kinds of diff, but MQ doesn't). A unified diff contains two 2.36 +MQ works with \emph{unified} diffs (\command{patch} can accept several 2.37 +other diff formats, but MQ doesn't). A unified diff contains two 2.38 kinds of header. The \emph{file header} describes the file being 2.39 modified; it contains the name of the file to modify. When 2.40 -\command{patch} sees a new file header, it looks for a file of that 2.41 +\command{patch} sees a new file header, it looks for a file with that 2.42 name to start modifying. 2.43 2.44 -After the file header come a series of \emph{hunks}. Each hunk starts 2.45 -with a header; this identifies the range of line numbers within the 2.46 -file that the hunk should modify. Following the header, a hunk starts 2.47 -and ends with a few lines of text from the unmodified file; these are 2.48 -called the \emph{context} for the hunk. Each unmodified line begins 2.49 -with a space characters. Within the hunk, a line that begins with 2.50 -``\texttt{-}'' means ``remove this line,'' while a line that begins 2.51 -with ``\texttt{+}'' means ``insert this line.'' For example, a line 2.52 -that is modified is represented by one deletion and one insertion. 2.53 +After the file header comes a series of \emph{hunks}. Each hunk 2.54 +starts with a header; this identifies the range of line numbers within 2.55 +the file that the hunk should modify. Following the header, a hunk 2.56 +starts and ends with a few (usually three) lines of text from the 2.57 +unmodified file; these are called the \emph{context} for the hunk. 2.58 +Each unmodified line begins with a space characters. Within the hunk, 2.59 +a line that begins with ``\texttt{-}'' means ``remove this line,'' 2.60 +while a line that begins with ``\texttt{+}'' means ``insert this 2.61 +line.'' For example, a line that is modified is represented by one 2.62 +deletion and one insertion. 2.63 + 2.64 +The \command{diff} command runs hunks together when there's not enough 2.65 +context between modifications to justify 2.66 2.67 When \command{patch} applies a hunk, it tries a handful of 2.68 successively less accurate strategies to try to make the hunk apply. 2.69 @@ -369,8 +381,14 @@ 2.70 When neither of these techniques works, \command{patch} prints a 2.71 message saying that the hunk in question was rejected. It saves 2.72 rejected hunks to a file with the same name, and an added 2.73 -\filename{.rej} extension. If \hgcmd{qpush} fails to apply a patch, 2.74 -it will print an error message and exit. 2.75 +\filename{.rej} extension. It also saves an unmodified copy of the 2.76 +file with a \filename{.orig} extension; the copy of the file without 2.77 +any extensions will contain any changes made by hunks that \emph{did} 2.78 +apply cleanly. If you have a patch that modifies \filename{foo} with 2.79 +six hunks, and one of them fails to apply, you will have: an 2.80 +unmodified \filename{foo.orig}, a \filename{foo.rej} containing one 2.81 +hunk, and \filename{foo}, containing the changes made by the five 2.82 +successful five hunks. 2.83 2.84 \subsection{Beware the fuzz} 2.85 2.86 @@ -392,6 +410,48 @@ 2.87 apply with some fuzz, provided you've verified the results of the 2.88 patching process in such cases. 2.89 2.90 +\subsection{Handling rejection} 2.91 + 2.92 +If \hgcmd{qpush} fails to apply a patch, it will print an error 2.93 +message and exit. If it has left \filename{.rej} files behind, it is 2.94 +usually best to fix up the rejected hunks before you push more patches 2.95 +or do any further work. 2.96 + 2.97 +If your patch \emph{used to} apply cleanly, and no longer does because 2.98 +you've changed the underlying code that your patches are based on, 2.99 +Mercurial Queues can help; see section~\ref{seq:mq:merge} for details. 2.100 + 2.101 +Unfortunately, there aren't any great techniques for dealing with 2.102 +rejected hunks. Most often, you'll need to view the \filename{.rej} 2.103 +file and edit the target file, applying the rejected hunks by hand. 2.104 + 2.105 +If you're feeling adventurous, Neil Brown, an Australian Linux kernel 2.106 +hacker, has written a tool called \command{wiggle}~\cite{web:wiggle}, 2.107 +which is more vigorous than \command{patch} in its attempts to make a 2.108 +patch apply. 2.109 + 2.110 +Another Linux kernel hacker, Chris Mason (the author of Mercurial 2.111 +Queues), wrote a similar tool called \command{rej}~\cite{web:rej}, 2.112 +which takes a simple approach to automating the application of hunks 2.113 +rejected by \command{patch}. \command{rej} can help with four common 2.114 +reasons that a hunk may be rejected: 2.115 + 2.116 +\begin{itemize} 2.117 +\item The context in the middle of a hunk has changed. 2.118 +\item A hunk is missing some context at the beginning or end. 2.119 +\item A large hunk might apply better--either entirely or in part--if 2.120 + it was broken up into smaller hunks. 2.121 +\item A hunk removes lines with slightly different content than those 2.122 + currently present in the file. 2.123 +\end{itemize} 2.124 + 2.125 +If you use \command{wiggle} or \command{rej}, you should be doubly 2.126 +careful to check your results when you're done. 2.127 + 2.128 +\section{Updating your patches when the underlying code changes} 2.129 +\label{sec:mq:merge} 2.130 + 2.131 +XXX. 2.132 2.133 %%% Local Variables: 2.134 %%% mode: latex