Mercurial > hgbook
annotate ja/mq.tex @ 323:2d1054e1de5b
more mq.tex
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Thu, 27 Mar 2008 22:11:00 +0900 |
parents | 4301500fca37 |
children | 7dc8a24c70f4 |
rev | line source |
---|---|
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1 %\chapter{Managing change with Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
2 \chapter{Mercurial Queues$B$GJQ99$r4IM}$9$k(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{chap:mq} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
5 %\section{The patch management problem} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
6 \section{$B%Q%C%A4IM}$NLdBj(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
7 \label{sec:mq:patch-mgmt} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
8 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
9 Here is a common scenario: you need to install a software package from |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
10 source, but you find a bug that you must fix in the source before you |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
11 can start using the package. You make your changes, forget about the |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
12 package for a while, and a few months later you need to upgrade to a |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
13 newer version of the package. If the newer version of the package |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
14 still has the bug, you must extract your fix from the older source |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
15 tree and apply it against the newer version. This is a tedious task, |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
16 and it's easy to make mistakes. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
17 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
18 This is a simple case of the ``patch management'' problem. You have |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
19 an ``upstream'' source tree that you can't change; you need to make |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
20 some local changes on top of the upstream tree; and you'd like to be |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
21 able to keep those changes separate, so that you can apply them to |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
22 newer versions of the upstream source. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
23 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
24 The patch management problem arises in many situations. Probably the |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
25 most visible is that a user of an open source software project will |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
26 contribute a bug fix or new feature to the project's maintainers in the |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
27 form of a patch. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
28 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
29 Distributors of operating systems that include open source software |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
30 often need to make changes to the packages they distribute so that |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
31 they will build properly in their environments. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
32 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
33 When you have few changes to maintain, it is easy to manage a single |
235
80f387d13bfe
Fix a few command references.
Bryan O'Sullivan <bos@serpentine.com>
parents:
234
diff
changeset
|
34 patch using the standard \command{diff} and \command{patch} programs |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
35 (see section~\ref{sec:mq:patch} for a discussion of these tools). |
285
814698eebbaf
fixed a typo and formatted the notify hook configuration example nicer.
Timo Paulssen <timonator@perpetuum-immobile.de>
parents:
283
diff
changeset
|
36 Once the number of changes grows, it starts to make sense to maintain |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
37 patches as discrete ``chunks of work,'' so that for example a single |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
38 patch will contain only one bug fix (the patch might modify several |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
39 files, but it's doing ``only one thing''), and you may have a number |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
40 of such patches for different bugs you need fixed and local changes |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
41 you require. In this situation, if you submit a bug fix patch to the |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
42 upstream maintainers of a package and they include your fix in a |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
43 subsequent release, you can simply drop that single patch when you're |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 updating to the newer release. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
45 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
46 Maintaining a single patch against an upstream tree is a little |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
47 tedious and error-prone, but not difficult. However, the complexity |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
48 of the problem grows rapidly as the number of patches you have to |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
49 maintain increases. With more than a tiny number of patches in hand, |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
50 understanding which ones you have applied and maintaining them moves |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
51 from messy to overwhelming. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
52 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
53 Fortunately, Mercurial includes a powerful extension, Mercurial Queues |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
54 (or simply ``MQ''), that massively simplifies the patch management |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
55 problem. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
56 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
57 %\section{The prehistory of Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
58 \section{Mercurial Queues$BA0;K(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
59 \label{sec:mq:history} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
60 |
323 | 61 %During the late 1990s, several Linux kernel developers started to |
62 %maintain ``patch series'' that modified the behaviour of the Linux | |
63 %kernel. Some of these series were focused on stability, some on | |
64 %feature coverage, and others were more speculative. | |
65 | |
66 1990$BG/Be$N=*$o$j:"!$(BLinux$B%+!<%M%k$N3+H/<TC#$O!$(BLinux$B%+!<%M%k$r2~A1$9$k0l(B | |
67 $BO"$N%Q%C%A$N4IM}$r;O$a$?!%$=$l$i$N$&$A!$$"$k$b$N$O0BDj@-$K!$JL$N$b$N$OFC(B | |
68 $BDj$N5!G=$K!$$^$?JL$N$b$N$OLn?4E*$JFbMF$KFC2=$7$F$$$?!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
69 |
323 | 70 %The sizes of these patch series grew rapidly. In 2002, Andrew Morton |
71 %published some shell scripts he had been using to automate the task of | |
72 %managing his patch queues. Andrew was successfully using these | |
73 %scripts to manage hundreds (sometimes thousands) of patches on top of | |
74 %the Linux kernel. | |
75 | |
76 $B$3$l$i$N%Q%C%A%7%j!<%:$N%5%$%:$O$O$9$0$KKD$l>e$,$C$?!%(B2002$BG/$K(BAndrew | |
77 Morton$B$OH`$N%Q%C%A%-%e!<$N4IM}$r<+F02=$9$k$$$/$D$+$N%7%'%k%9%/%j%W%H$r8x(B | |
78 $BI=$7$?!%(BAndrew$B$O?tI4$+$i?t@i$N(BLinux$B%+!<%M%k%Q%C%A$r$3$l$i$N%9%/%j%W%H$G(B | |
79 $B4IM}$9$k$3$H$,$G$-$F$$$?!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
80 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
81 %\subsection{A patchwork quilt} |
323 | 82 \subsection{patchwork quilt} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
83 \label{sec:mq:quilt} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
84 |
323 | 85 %In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the |
86 %approach of Andrew's scripts and published a tool called ``patchwork | |
87 %quilt''~\cite{web:quilt}, or simply ``quilt'' | |
88 %(see~\cite{gruenbacher:2005} for a paper describing it). Because | |
89 %quilt substantially automated patch management, it rapidly gained a | |
90 %large following among open source software developers. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
91 |
323 | 92 2003$BG/$N;O$a!$(BAndreas Gruenbacher$B$H(BMartin Quinson$B$O(BAndrew$B$N%9%/%j%W%H$N$d(B |
93 $B$jJ}$r??;w$F!$(B``patchwork quilt''~\cite{web:quilt}$B$"$k$$$OC1$K(B``quilt''$B$H(B | |
94 $B8F$P$l$k%D!<%k$r%j%j!<%9$7$?!%!J>\$7$/$OO@J8(B~\cite{gruenbacher:2005}$B$r;2(B | |
95 $B>H$N$3$H!%!K(Bquilt$B$O==J,$K<+F02=$5$l$?%Q%C%A4IM}$rDs6!$7$F$$$?$N$G!$%=%U%H(B | |
96 $B%&%'%"3+H/<T$NBg$-$J;Y;}$r5^B.$K3MF@$7$F$$$C$?!%(B | |
97 | |
98 %Quilt manages a \emph{stack of patches} on top of a directory tree. | |
99 %To begin, you tell quilt to manage a directory tree, and tell it which | |
100 %files you want to manage; it stores away the names and contents of | |
101 %those files. To fix a bug, you create a new patch (using a single | |
102 %command), edit the files you need to fix, then ``refresh'' the patch. | |
103 | |
104 quilt$B$O%G%#%l%/%H%j%D%j!<>e$G(B\emph{$B%Q%C%A$N%9%?%C%/(B}$B$r4IM}$9$k!%%Q%C%A$N(B | |
105 $B4IM}$r;O$a$k$K$O!$(Bquilt$B$K4IM}$9$Y$-%G%#%l%/%H%j%D%j!<$H!$4IM}BP>]$N%U%!%$(B | |
106 $B%k$r;XDj$9$k!%(Bquilt$B$O$3$l$i$N%U%!%$%k$NL>A0$HCf?H$rJ]B8$9$k!%%P%0$r=$@5(B | |
107 $B$9$k>l9g$O!$$^$:?7$7$$%Q%C%A$r!J%3%^%s%I(B1$B$D$G!K:n@.$7!$I,MW$J%U%!%$%k$K(B | |
108 $B=$@5$r2C$($?8e!$%Q%C%A$r(B``$B%j%U%l%C%7%e(B''$B$9$l$P$h$$!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
109 |
323 | 110 %The refresh step causes quilt to scan the directory tree; it updates |
111 %the patch with all of the changes you have made. You can create | |
112 %another patch on top of the first, which will track the changes | |
113 %required to modify the tree from ``tree with one patch applied'' to | |
114 %``tree with two patches applied''. | |
115 | |
116 $B%j%U%l%C%7%e$G$O!$(Bquilt$B$O%G%#%l%/%H%j%D%j!<$r%9%-%c%s$7!$JQ99A4$F$rH?1G$5(B | |
117 $B$;$F%Q%C%A$r99?7$9$k!%(B``$B$"$k%Q%C%A$,E,MQ$5$l$?>uBV$N%D%j!<(B''$B$+$i(B``2$B$D$N%Q%C(B | |
118 $B%A$,E,MQ$5$l$?%D%j!<(B''$B$X99?7$9$k$N$KI,MW$JJQ99$rDI@W$7!$JL$N%Q%C%A$r:n$k(B | |
119 $B$3$H$b$G$-$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
120 |
323 | 121 %You can \emph{change} which patches are applied to the tree. If you |
122 %``pop'' a patch, the changes made by that patch will vanish from the | |
123 %directory tree. Quilt remembers which patches you have popped, | |
124 %though, so you can ``push'' a popped patch again, and the directory | |
125 %tree will be restored to contain the modifications in the patch.Most | |
126 %importantly, you can run the ``refresh'' command at any time, and the | |
127 %topmost applied patch will be updated. This means that you can, at | |
128 %any time, change both which patches are applied and what | |
129 %modifications those patches make. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
130 |
323 | 131 $B%f!<%6$O$I$N%Q%C%A$,%D%j!<$KE,MQ$5$l$k$+$r(B\emph{$BJQ99(B}$B$G$-$k!%$"$k%Q%C%A$r(B |
132 $B%]%C%W$9$k$H!$$3$N%Q%C%A$K$h$kJQ99$O%D%j!<$+$i>CLG$9$k!%(Bquilt$B$O$I$N%Q%C%A(B | |
133 $B$r%]%C%W$7$?$+5-21$7$F$*$j!$0lEY%]%C%W$7$?%U%!%$%k$r:F$S%W%C%7%e$7!$%G%#(B | |
134 $B%l%/%H%j%D%j!<$r%Q%C%A$K$h$kJQ99$,$J$5$l$?>uBV$KLa$9$3$H$,$G$-$k!%:G$b=E(B | |
135 $BMW$J$3$H$O!$$$$D$G$b(B``refresh''$B%3%^%s%I$r<B9T$7$F0lHV?7$7$/E,MQ$5$l$?%Q%C(B | |
136 $B%A$r99?7$G$-$k$3$H$G$"$k!%$3$l$O$9$J$o$A!$%Q%C%A$NE,MQ$5$l$?>uBV$H!$%Q%C(B | |
137 $B%A$=$l<+BN$r$$$D$G$b99?7$G$-$k$H$$$&$3$H$G$"$k!%(B | |
138 | |
139 %Quilt knows nothing about revision control tools, so it works equally | |
140 %well on top of an unpacked tarball or a Subversion working copy. | |
141 | |
142 quilt$B$O%j%S%8%g%s4IM}%D!<%k$K$D$$$F$OA4$/4XCN$7$J$$$?$a!$E83+$5$l$?(Btar$B%\!<(B | |
143 $B%k>e$G$b!$(BSubversion$B$N%o!<%-%s%0%3%T!<>e$G$bF1MM$KF0:n$9$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
144 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
145 %\subsection{From patchwork quilt to Mercurial Queues} |
323 | 146 \subsection{patchwork quilt$B$+$i(BMercurial Queues$B$X(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
147 \label{sec:mq:quilt-mq} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
148 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
149 In mid-2005, Chris Mason took the features of quilt and wrote an |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
150 extension that he called Mercurial Queues, which added quilt-like |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
151 behaviour to Mercurial. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
152 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 The key difference between quilt and MQ is that quilt knows nothing |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
154 about revision control systems, while MQ is \emph{integrated} into |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
155 Mercurial. Each patch that you push is represented as a Mercurial |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
156 changeset. Pop a patch, and the changeset goes away. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
157 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
158 Because quilt does not care about revision control tools, it is still |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
159 a tremendously useful piece of software to know about for situations |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
160 where you cannot use Mercurial and MQ. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
161 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
162 %\section{The huge advantage of MQ} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
163 \section{MQ$B$NBg$-$JMxE@(B} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
164 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
165 I cannot overstate the value that MQ offers through the unification of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
166 patches and revision control. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
167 |
66 | 168 A major reason that patches have persisted in the free software and |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
169 open source world---in spite of the availability of increasingly |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
170 capable revision control tools over the years---is the \emph{agility} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
171 they offer. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
172 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
173 Traditional revision control tools make a permanent, irreversible |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
174 record of everything that you do. While this has great value, it's |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
175 also somewhat stifling. If you want to perform a wild-eyed |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
176 experiment, you have to be careful in how you go about it, or you risk |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
177 leaving unneeded---or worse, misleading or destabilising---traces of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
178 your missteps and errors in the permanent revision record. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
179 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
180 By contrast, MQ's marriage of distributed revision control with |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
181 patches makes it much easier to isolate your work. Your patches live |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
182 on top of normal revision history, and you can make them disappear or |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
183 reappear at will. If you don't like a patch, you can drop it. If a |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
184 patch isn't quite as you want it to be, simply fix it---as many times |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
185 as you need to, until you have refined it into the form you desire. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
186 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
187 As an example, the integration of patches with revision control makes |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
188 understanding patches and debugging their effects---and their |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
189 interplay with the code they're based on---\emph{enormously} easier. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
190 Since every applied patch has an associated changeset, you can use |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
191 \hgcmdargs{log}{\emph{filename}} to see which changesets and patches |
282 | 192 affected a file. You can use the \hgext{bisect} command to |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
193 binary-search through all changesets and applied patches to see where |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
194 a bug got introduced or fixed. You can use the \hgcmd{annotate} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
195 command to see which changeset or patch modified a particular line of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
196 a source file. And so on. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
197 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
198 %\section{Understanding patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
199 \section{$B%Q%C%A$H$O2?$+(B} |
26 | 200 \label{sec:mq:patch} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
201 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
202 Because MQ doesn't hide its patch-oriented nature, it is helpful to |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
203 understand what patches are, and a little about the tools that work |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
204 with them. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
205 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
206 The traditional Unix \command{diff} command compares two files, and |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
207 prints a list of differences between them. The \command{patch} command |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
208 understands these differences as \emph{modifications} to make to a |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
209 file. Take a look at figure~\ref{ex:mq:diff} for a simple example of |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
210 these commands in action. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
211 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
212 \begin{figure}[ht] |
46
dd657c4d3a47
Rename mq.diff to mq.dodiff Emacs won't screw up the syntax highlighting.
Bryan O'Sullivan <bos@serpentine.com>
parents:
35
diff
changeset
|
213 \interaction{mq.dodiff.diff} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
214 \caption{Simple uses of the \command{diff} and \command{patch} commands} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
215 \label{ex:mq:diff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
216 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
217 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
218 The type of file that \command{diff} generates (and \command{patch} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
219 takes as input) is called a ``patch'' or a ``diff''; there is no |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
220 difference between a patch and a diff. (We'll use the term ``patch'', |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
221 since it's more commonly used.) |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
222 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
223 A patch file can start with arbitrary text; the \command{patch} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
224 command ignores this text, but MQ uses it as the commit message when |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
225 creating changesets. To find the beginning of the patch content, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
226 \command{patch} searches for the first line that starts with the |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
227 string ``\texttt{diff~-}''. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
228 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
229 MQ works with \emph{unified} diffs (\command{patch} can accept several |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
230 other diff formats, but MQ doesn't). A unified diff contains two |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
231 kinds of header. The \emph{file header} describes the file being |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
232 modified; it contains the name of the file to modify. When |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
233 \command{patch} sees a new file header, it looks for a file with that |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
234 name to start modifying. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
235 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
236 After the file header comes a series of \emph{hunks}. Each hunk |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
237 starts with a header; this identifies the range of line numbers within |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
238 the file that the hunk should modify. Following the header, a hunk |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
239 starts and ends with a few (usually three) lines of text from the |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
240 unmodified file; these are called the \emph{context} for the hunk. If |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
241 there's only a small amount of context between successive hunks, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
242 \command{diff} doesn't print a new hunk header; it just runs the hunks |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
243 together, with a few lines of context between modifications. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
244 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
245 Each line of context begins with a space character. Within the hunk, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
246 a line that begins with ``\texttt{-}'' means ``remove this line,'' |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
247 while a line that begins with ``\texttt{+}'' means ``insert this |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
248 line.'' For example, a line that is modified is represented by one |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
249 deletion and one insertion. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
250 |
66 | 251 We will return to some of the more subtle aspects of patches later (in |
26 | 252 section~\ref{sec:mq:adv-patch}), but you should have enough information |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
253 now to use MQ. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
254 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
255 %\section{Getting started with Mercurial Queues} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
256 \section{Mercurial Queues$B$r;H$C$F$_$k(B} |
2 | 257 \label{sec:mq:start} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
258 |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
259 Because MQ is implemented as an extension, you must explicitly enable |
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
260 before you can use it. (You don't need to download anything; MQ ships |
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
261 with the standard Mercurial distribution.) To enable MQ, edit your |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
262 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. |
2 | 263 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
264 \begin{figure}[ht] |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
265 \begin{codesample4} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
266 [extensions] |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
267 hgext.mq = |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
268 \end{codesample4} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
269 \label{ex:mq:config} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
270 \caption{Contents to add to \tildefile{.hgrc} to enable the MQ extension} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
271 \end{figure} |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
272 |
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
273 Once the extension is enabled, it will make a number of new commands |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
274 available. To verify that the extension is working, you can use |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
275 \hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
276 the example in figure~\ref{ex:mq:enabled}. |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
277 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
278 \begin{figure}[ht] |
4
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
279 \interaction{mq.qinit-help.help} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
280 \caption{How to verify that MQ is enabled} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
281 \label{ex:mq:enabled} |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
282 \end{figure} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
283 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
284 You can use MQ with \emph{any} Mercurial repository, and its commands |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
285 only operate within that repository. To get started, simply prepare |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
286 the repository using the \hgxcmd{mq}{qinit} command (see |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
287 figure~\ref{ex:mq:qinit}). This command creates an empty directory |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
288 called \sdirname{.hg/patches}, where MQ will keep its metadata. As |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
289 with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
290 if it succeeds. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
291 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
292 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
293 \interaction{mq.tutorial.qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
294 \caption{Preparing a repository for use with MQ} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
295 \label{ex:mq:qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
296 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
297 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
298 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
299 \interaction{mq.tutorial.qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
300 \caption{Creating a new patch} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
301 \label{ex:mq:qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
302 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
303 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
304 %\subsection{Creating a new patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
305 \subsection{$B?7$7$$%Q%C%A$N:n@.(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
306 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
307 To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
308 command takes one argument, the name of the patch to create. MQ will |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
309 use this as the name of an actual file in the \sdirname{.hg/patches} |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
310 directory, as you can see in figure~\ref{ex:mq:qnew}. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
311 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
312 Also newly present in the \sdirname{.hg/patches} directory are two |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
313 other files, \sfilename{series} and \sfilename{status}. The |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
314 \sfilename{series} file lists all of the patches that MQ knows about |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
315 for this repository, with one patch per line. Mercurial uses the |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
316 \sfilename{status} file for internal book-keeping; it tracks all of the |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
317 patches that MQ has \emph{applied} in this repository. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
318 |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
319 \begin{note} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
320 You may sometimes want to edit the \sfilename{series} file by hand; |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
321 for example, to change the sequence in which some patches are |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
322 applied. However, manually editing the \sfilename{status} file is |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
323 almost always a bad idea, as it's easy to corrupt MQ's idea of what |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
324 is happening. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
325 \end{note} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
326 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
327 Once you have created your new patch, you can edit files in the |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
328 working directory as you usually would. All of the normal Mercurial |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
329 commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
330 they did before. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
331 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
332 %\subsection{Refreshing a patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
333 \subsection{$B%Q%C%A$N:F@8(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
334 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
335 When you reach a point where you want to save your work, use the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
336 \hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
337 you are working on. This command folds the changes you have made in |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
338 the working directory into your patch, and updates its corresponding |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
339 changeset to contain those changes. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
340 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
341 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
342 \interaction{mq.tutorial.qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
343 \caption{Refreshing a patch} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
344 \label{ex:mq:qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
345 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
346 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
347 You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way |
13 | 348 to ``checkpoint'' your work. Refresh your patch at an opportune |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
349 time; try an experiment; and if the experiment doesn't work out, |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
350 \hgcmd{revert} your modifications back to the last time you refreshed. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
351 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
352 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
353 \interaction{mq.tutorial.qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
354 \caption{Refresh a patch many times to accumulate changes} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
355 \label{ex:mq:qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
356 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
357 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
358 %\subsection{Stacking and tracking patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
359 \subsection{$B%Q%C%A$N=8@Q$HDI@W(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
360 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
361 Once you have finished working on a patch, or need to work on another, |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
362 you can use the \hgxcmd{mq}{qnew} command again to create a new patch. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
363 Mercurial will apply this patch on top of your existing patch. See |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
364 figure~\ref{ex:mq:qnew2} for an example. Notice that the patch |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
365 contains the changes in our prior patch as part of its context (you |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
366 can see this more clearly in the output of \hgcmd{annotate}). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
367 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
368 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
369 \interaction{mq.tutorial.qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
370 \caption{Stacking a second patch on top of the first} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
371 \label{ex:mq:qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
372 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
373 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
374 So far, with the exception of \hgxcmd{mq}{qnew} and \hgxcmd{mq}{qrefresh}, we've |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
375 been careful to only use regular Mercurial commands. However, MQ |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
376 provides many commands that are easier to use when you are thinking |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
377 about patches, as illustrated in figure~\ref{ex:mq:qseries}: |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
378 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
379 \begin{itemize} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
380 \item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
381 about in this repository, from oldest to newest (most recently |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
382 \emph{created}). |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
383 \item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
384 \emph{applied} in this repository, again from oldest to newest (most |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
385 recently applied). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
386 \end{itemize} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
387 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
388 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
389 \interaction{mq.tutorial.qseries} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
390 \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
391 \hgxcmd{mq}{qapplied}} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
392 \label{ex:mq:qseries} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
393 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
394 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
395 %\subsection{Manipulating the patch stack} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
396 \subsection{$B%Q%C%A%9%?%C%/$NA`:n(B} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
397 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
398 The previous discussion implied that there must be a difference |
11 | 399 between ``known'' and ``applied'' patches, and there is. MQ can |
400 manage a patch without it being applied in the repository. | |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
401 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
402 An \emph{applied} patch has a corresponding changeset in the |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
403 repository, and the effects of the patch and changeset are visible in |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
404 the working directory. You can undo the application of a patch using |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
405 the \hgxcmd{mq}{qpop} command. MQ still \emph{knows about}, or manages, a |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
406 popped patch, but the patch no longer has a corresponding changeset in |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
407 the repository, and the working directory does not contain the changes |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
408 made by the patch. Figure~\ref{fig:mq:stack} illustrates the |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
409 difference between applied and tracked patches. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
410 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
411 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
412 \centering |
35
e68f4a96c16e
Fixed the \grafix macro to work for PDFs again.
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
30
diff
changeset
|
413 \grafix{mq-stack} |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
414 \caption{Applied and unapplied patches in the MQ patch stack} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
415 \label{fig:mq:stack} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
416 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
417 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
418 You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
419 command. This creates a new changeset to correspond to the patch, and |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
420 the patch's changes once again become present in the working |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
421 directory. See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop} |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
422 and \hgxcmd{mq}{qpush} in action. Notice that once we have popped a patch |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
423 or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
424 that of \hgxcmd{mq}{qapplied} has changed. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
425 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
426 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
427 \interaction{mq.tutorial.qpop} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
428 \caption{Modifying the stack of applied patches} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
429 \label{ex:mq:qpop} |
11 | 430 \end{figure} |
431 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
432 %\subsection{Pushing and popping many patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
433 \subsection{$B%Q%C%A$N%W%C%7%e$H%]%C%W(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
434 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
435 While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
436 a time by default, you can push and pop many patches in one go. The |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
437 \hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
438 unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
439 causes it to pop all applied patches. (For some more ways to push and |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
440 pop many patches, see section~\ref{sec:mq:perf} below.) |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
441 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
442 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
443 \interaction{mq.tutorial.qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
444 \caption{Pushing all unapplied patches} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
445 \label{ex:mq:qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
446 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
447 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
448 %\subsection{Safety checks, and overriding them} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
449 \subsection{$B0BA4@-%A%'%C%/$H%*!<%P%i%$%I(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
450 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
451 Several MQ commands check the working directory before they do |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
452 anything, and fail if they find any modifications. They do this to |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
453 ensure that you won't lose any changes that you have made, but not yet |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
454 incorporated into a patch. Figure~\ref{ex:mq:add} illustrates this; |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
455 the \hgxcmd{mq}{qnew} command will not create a new patch if there are |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
456 outstanding changes, caused in this case by the \hgcmd{add} of |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
457 \filename{file3}. |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
458 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
459 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
460 \interaction{mq.tutorial.add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
461 \caption{Forcibly creating a patch} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
462 \label{ex:mq:add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
463 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
464 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
465 Commands that check the working directory all take an ``I know what |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
466 I'm doing'' option, which is always named \option{-f}. The exact |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
467 meaning of \option{-f} depends on the command. For example, |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
468 \hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
469 changes into the new patch it creates, but |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
470 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
471 files affected by the patch that it is popping. Be sure to read the |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
472 documentation for a command's \option{-f} option before you use it! |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
473 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
474 %\subsection{Working on several patches at once} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
475 \subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} |
13 | 476 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
477 The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} |
13 | 478 applied patch. This means that you can suspend work on one patch (by |
479 refreshing it), pop or push to make a different patch the top, and | |
480 work on \emph{that} patch for a while. | |
481 | |
482 Here's an example that illustrates how you can use this ability. | |
483 Let's say you're developing a new feature as two patches. The first | |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
484 is a change to the core of your software, and the second---layered on |
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
485 top of the first---changes the user interface to use the code you just |
13 | 486 added to the core. If you notice a bug in the core while you're |
487 working on the UI patch, it's easy to fix the core. Simply | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
488 \hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
489 \hgxcmd{mq}{qpop} down to the core patch. Fix the core bug, |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
490 \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI |
13 | 491 patch to continue where you left off. |
492 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
493 %\section{More about patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
494 \section{$B$5$i$K%Q%C%A$K$D$$$F(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
495 \label{sec:mq:adv-patch} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
496 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
497 MQ uses the GNU \command{patch} command to apply patches, so it's |
26 | 498 helpful to know a few more detailed aspects of how \command{patch} |
499 works, and about patches themselves. | |
500 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
501 %\subsection{The strip count} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
502 \subsection{$B%9%H%j%C%W%+%&%s%H(B} |
26 | 503 |
504 If you look at the file headers in a patch, you will notice that the | |
505 pathnames usually have an extra component on the front that isn't | |
506 present in the actual path name. This is a holdover from the way that | |
507 people used to generate patches (people still do this, but it's | |
508 somewhat rare with modern revision control tools). | |
509 | |
510 Alice would unpack a tarball, edit her files, then decide that she | |
511 wanted to create a patch. So she'd rename her working directory, | |
512 unpack the tarball again (hence the need for the rename), and use the | |
513 \cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to | |
514 recursively generate a patch between the unmodified directory and the | |
515 modified one. The result would be that the name of the unmodified | |
516 directory would be at the front of the left-hand path in every file | |
517 header, and the name of the modified directory would be at the front | |
518 of the right-hand path. | |
519 | |
520 Since someone receiving a patch from the Alices of the net would be | |
521 unlikely to have unmodified and modified directories with exactly the | |
522 same names, the \command{patch} command has a \cmdopt{patch}{-p} | |
523 option that indicates the number of leading path name components to | |
524 strip when trying to apply a patch. This number is called the | |
525 \emph{strip count}. | |
526 | |
527 An option of ``\texttt{-p1}'' means ``use a strip count of one''. If | |
528 \command{patch} sees a file name \filename{foo/bar/baz} in a file | |
529 header, it will strip \filename{foo} and try to patch a file named | |
530 \filename{bar/baz}. (Strictly speaking, the strip count refers to the | |
531 number of \emph{path separators} (and the components that go with them | |
532 ) to strip. A strip count of one will turn \filename{foo/bar} into | |
533 \filename{bar}, but \filename{/foo/bar} (notice the extra leading | |
534 slash) into \filename{foo/bar}.) | |
535 | |
536 The ``standard'' strip count for patches is one; almost all patches | |
537 contain one leading path name component that needs to be stripped. | |
538 Mercurial's \hgcmd{diff} command generates path names in this form, | |
539 and the \hgcmd{import} command and MQ expect patches to have a strip | |
540 count of one. | |
541 | |
542 If you receive a patch from someone that you want to add to your patch | |
543 queue, and the patch needs a strip count other than one, you cannot | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
544 just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet |
26 | 545 have a \texttt{-p} option (see~\bug{311}). Your best bet is to |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
546 \hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} |
26 | 547 to apply their patch, followed by \hgcmd{addremove} to pick up any |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
548 files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. |
26 | 549 This complexity may become unnecessary; see~\bug{311} for details. |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
550 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
551 %\subsection{Strategies for applying a patch} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
552 \subsection{$B%Q%C%AE,MQ$N$?$a$N@oN,(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
553 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
554 When \command{patch} applies a hunk, it tries a handful of |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
555 successively less accurate strategies to try to make the hunk apply. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
556 This falling-back technique often makes it possible to take a patch |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
557 that was generated against an old version of a file, and apply it |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
558 against a newer version of that file. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
559 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
560 First, \command{patch} tries an exact match, where the line numbers, |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
561 the context, and the text to be modified must apply exactly. If it |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
562 cannot make an exact match, it tries to find an exact match for the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
563 context, without honouring the line numbering information. If this |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
564 succeeds, it prints a line of output saying that the hunk was applied, |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
565 but at some \emph{offset} from the original line number. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
566 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
567 If a context-only match fails, \command{patch} removes the first and |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
568 last lines of the context, and tries a \emph{reduced} context-only |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
569 match. If the hunk with reduced context succeeds, it prints a message |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
570 saying that it applied the hunk with a \emph{fuzz factor} (the number |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
571 after the fuzz factor indicates how many lines of context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
572 \command{patch} had to trim before the patch applied). |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
573 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
574 When neither of these techniques works, \command{patch} prints a |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
575 message saying that the hunk in question was rejected. It saves |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
576 rejected hunks (also simply called ``rejects'') to a file with the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
577 same name, and an added \sfilename{.rej} extension. It also saves an |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
578 unmodified copy of the file with a \sfilename{.orig} extension; the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
579 copy of the file without any extensions will contain any changes made |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
580 by hunks that \emph{did} apply cleanly. If you have a patch that |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
581 modifies \filename{foo} with six hunks, and one of them fails to |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
582 apply, you will have: an unmodified \filename{foo.orig}, a |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
583 \filename{foo.rej} containing one hunk, and \filename{foo}, containing |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
584 the changes made by the five successful five hunks. |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
585 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
586 %\subsection{Some quirks of patch representation} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
587 \subsection{$B%Q%C%AI=8=$N4qL/$JE@(B} |
25
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
588 |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
589 There are a few useful things to know about how \command{patch} works |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
590 with files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
591 \begin{itemize} |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
592 \item This should already be obvious, but \command{patch} cannot |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
593 handle binary files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
594 \item Neither does it care about the executable bit; it creates new |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
595 files as readable, but not executable. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
596 \item \command{patch} treats the removal of a file as a diff between |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
597 the file to be removed and the empty file. So your idea of ``I |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
598 deleted this file'' looks like ``every line of this file was |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
599 deleted'' in a patch. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
600 \item It treats the addition of a file as a diff between the empty |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
601 file and the file to be added. So in a patch, your idea of ``I |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
602 added this file'' looks like ``every line of this file was added''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
603 \item It treats a renamed file as the removal of the old name, and the |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
604 addition of the new name. This means that renamed files have a big |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
605 footprint in patches. (Note also that Mercurial does not currently |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
606 try to infer when files have been renamed or copied in a patch.) |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
607 \item \command{patch} cannot represent empty files, so you cannot use |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
608 a patch to represent the notion ``I added this empty file to the |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
609 tree''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
610 \end{itemize} |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
611 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
612 %\subsection{Beware the fuzz} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
613 \subsection{$B[#Kf$JE@$K$D$$$F(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
614 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
615 While applying a hunk at an offset, or with a fuzz factor, will often |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
616 be completely successful, these inexact techniques naturally leave |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
617 open the possibility of corrupting the patched file. The most common |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
618 cases typically involve applying a patch twice, or at an incorrect |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
619 location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
620 mentions an offset or fuzz factor, you should make sure that the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
621 modified files are correct afterwards. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
622 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
623 It's often a good idea to refresh a patch that has applied with an |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
624 offset or fuzz factor; refreshing the patch generates new context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
625 information that will make it apply cleanly. I say ``often,'' not |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
626 ``always,'' because sometimes refreshing a patch will make it fail to |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
627 apply against a different revision of the underlying files. In some |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
628 cases, such as when you're maintaining a patch that must sit on top of |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
629 multiple versions of a source tree, it's acceptable to have a patch |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
630 apply with some fuzz, provided you've verified the results of the |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
631 patching process in such cases. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
632 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
633 %\subsection{Handling rejection} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
634 \subsection{$B%j%8%'%/%H$N<h$j07$$(B} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
635 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
636 If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
637 message and exit. If it has left \sfilename{.rej} files behind, it is |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
638 usually best to fix up the rejected hunks before you push more patches |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
639 or do any further work. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
640 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
641 If your patch \emph{used to} apply cleanly, and no longer does because |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
642 you've changed the underlying code that your patches are based on, |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
643 Mercurial Queues can help; see section~\ref{sec:mq:merge} for details. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
644 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
645 Unfortunately, there aren't any great techniques for dealing with |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
646 rejected hunks. Most often, you'll need to view the \sfilename{.rej} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
647 file and edit the target file, applying the rejected hunks by hand. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
648 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
649 If you're feeling adventurous, Neil Brown, a Linux kernel hacker, |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
650 wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
651 vigorous than \command{patch} in its attempts to make a patch apply. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
652 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
653 Another Linux kernel hacker, Chris Mason (the author of Mercurial |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
654 Queues), wrote a similar tool called |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
655 \command{mpatch}~\cite{web:mpatch}, which takes a simple approach to |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
656 automating the application of hunks rejected by \command{patch}. The |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
657 \command{mpatch} command can help with four common reasons that a hunk |
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
658 may be rejected: |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
659 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
660 \begin{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
661 \item The context in the middle of a hunk has changed. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
662 \item A hunk is missing some context at the beginning or end. |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
663 \item A large hunk might apply better---either entirely or in |
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
664 part---if it was broken up into smaller hunks. |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
665 \item A hunk removes lines with slightly different content than those |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
666 currently present in the file. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
667 \end{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
668 |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
669 If you use \command{wiggle} or \command{mpatch}, you should be doubly |
55 | 670 careful to check your results when you're done. In fact, |
254
7301e64c362e
Chris Mason's "rej" tool has been superseded by "mpatch", per David Rushby.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
671 \command{mpatch} enforces this method of double-checking the tool's |
55 | 672 output, by automatically dropping you into a merge program when it has |
673 done its job, so that you can verify its work and finish off any | |
674 remaining merges. | |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
675 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
676 %\section{Getting the best performance out of MQ} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
677 \section{MQ$B$r:GBg8B$K3hMQ$9$k(B} |
27
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
678 \label{sec:mq:perf} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
679 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
680 MQ is very efficient at handling a large number of patches. I ran |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
681 some performance experiments in mid-2006 for a talk that I gave at the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
682 2006 EuroPython conference~\cite{web:europython}. I used as my data |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
683 set the Linux 2.6.17-mm1 patch series, which consists of 1,738 |
66 | 684 patches. I applied these on top of a Linux kernel repository |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
685 containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
686 2.6.17. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
687 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
688 On my old, slow laptop, I was able to |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
689 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes, |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
690 and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds. (On a |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
691 newer laptop, the time to push all patches dropped to two minutes.) I |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
692 could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
693 lines of changes to 287 files) in 6.6 seconds. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
694 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
695 Clearly, MQ is well suited to working in large trees, but there are a |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
696 few tricks you can use to get the best performance of it. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
697 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
698 First of all, try to ``batch'' operations together. Every time you |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
699 run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
700 directory once to make sure you haven't made some changes and then |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
701 forgotten to run \hgxcmd{mq}{qrefresh}. On a small tree, the time that |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
702 this scan takes is unnoticeable. However, on a medium-sized tree |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
703 (containing tens of thousands of files), it can take a second or more. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
704 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
705 The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
706 multiple patches at a time. You can identify the ``destination |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
707 patch'' that you want to end up at. When you \hgxcmd{mq}{qpush} with a |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
708 destination specified, it will push patches until that patch is at the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
709 top of the applied stack. When you \hgxcmd{mq}{qpop} to a destination, MQ |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
710 will pop patches until the destination patch is at the top. |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
711 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
712 You can identify a destination patch using either the name of the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
713 patch, or by number. If you use numeric addressing, patches are |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
714 counted from zero; this means that the first patch is zero, the second |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
715 is one, and so on. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
716 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
717 %\section{Updating your patches when the underlying code changes} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
718 \section{$B2<0L%3!<%I$NJQ2=$K9g$o$;$F%Q%C%A$r99?7$9$k(B} |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
719 \label{sec:mq:merge} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
720 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
721 It's common to have a stack of patches on top of an underlying |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
722 repository that you don't modify directly. If you're working on |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
723 changes to third-party code, or on a feature that is taking longer to |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
724 develop than the rate of change of the code beneath, you will often |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
725 need to sync up with the underlying code, and fix up any hunks in your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
726 patches that no longer apply. This is called \emph{rebasing} your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
727 patch series. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
728 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
729 The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
730 your patches, then \hgcmd{pull} changes into the underlying |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
731 repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
732 patches again. MQ will stop pushing any time it runs across a patch |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
733 that fails to apply during conflicts, allowing you to fix your |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
734 conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
735 until you have fixed your entire stack. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
736 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
737 This approach is easy to use and works well if you don't expect |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
738 changes to the underlying code to affect how well your patches apply. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
739 If your patch stack touches code that is modified frequently or |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
740 invasively in the underlying repository, however, fixing up rejected |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
741 hunks by hand quickly becomes tiresome. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
742 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
743 It's possible to partially automate the rebasing process. If your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
744 patches apply cleanly against some revision of the underlying repo, MQ |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
745 can use this information to help you to resolve conflicts between your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
746 patches and a different revision. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
747 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
748 The process is a little involved. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
749 \begin{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
750 \item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
751 the revision where you know that they apply cleanly. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
752 \item Save a backup copy of your patch directory using |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
753 \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}. This prints |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
754 the name of the directory that it has saved the patches in. It will |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
755 save the patches to a directory called |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
756 \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
757 integer. It also commits a ``save changeset'' on top of your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
758 applied patches; this is for internal book-keeping, and records the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
759 states of the \sfilename{series} and \sfilename{status} files. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
760 \item Use \hgcmd{pull} to bring new changes into the underlying |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
761 repository. (Don't run \hgcmdargs{pull}{-u}; see below for why.) |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
762 \item Update to the new tip revision, using |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
763 \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
764 have pushed. |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
765 \item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
766 \hgxopt{mq}{qpush}{-a}}. The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
767 tells MQ to perform a three-way merge if the patch fails to apply. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
768 \end{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
769 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
770 During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
771 \sfilename{series} file is applied normally. If a patch applies with |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
772 fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
773 performs a three-way merge with the corresponding changeset. This |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
774 merge uses Mercurial's normal merge machinery, so it may pop up a GUI |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
775 merge tool to help you to resolve problems. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
776 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
777 When you finish resolving the effects of a patch, MQ refreshes your |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
778 patch based on the result of the merge. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
779 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
780 At the end of this process, your repository will have one extra head |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
781 from the old patch queue, and a copy of the old patch queue will be in |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
782 \sdirname{.hg/patches.\emph{N}}. You can remove the extra head using |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
783 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
784 or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
785 you are sure that you no longer need it as a backup. |
13 | 786 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
787 %\section{Identifying patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
788 \section{$B%Q%C%A$N<1JL(B} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
789 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
790 MQ commands that work with patches let you refer to a patch either by |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
791 using its name or by a number. By name is obvious enough; pass the |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
792 name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will |
55 | 793 push patches until \filename{foo.patch} is applied. |
794 | |
795 As a shortcut, you can refer to a patch using both a name and a | |
796 numeric offset; \texttt{foo.patch-2} means ``two patches before | |
797 \texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches | |
798 after \texttt{bar.patch}''. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
799 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
800 Referring to a patch by index isn't much different. The first patch |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
801 printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
802 of those start-at-zero counting systems); the second is patch one; and |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
803 so on |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
804 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
805 MQ also makes it easy to work with patches when you are using normal |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
806 Mercurial commands. Every command that accepts a changeset ID will |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
807 also accept the name of an applied patch. MQ augments the tags |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
808 normally in the repository with an eponymous one for each applied |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
809 patch. In addition, the special tags \index{tags!special tag |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
810 names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
811 names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
812 topmost applied patches, respectively. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
813 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
814 These additions to Mercurial's normal tagging capabilities make |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
815 dealing with patches even more of a breeze. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
816 \begin{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
817 \item Want to patchbomb a mailing list with your latest series of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
818 changes? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
819 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
820 hg email qbase:qtip |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
821 \end{codesample4} |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
822 (Don't know what ``patchbombing'' is? See |
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
823 section~\ref{sec:hgext:patchbomb}.) |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
824 \item Need to see all of the patches since \texttt{foo.patch} that |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
825 have touched files in a subdirectory of your tree? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
826 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
827 hg log -r foo.patch:qtip \emph{subdir} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
828 \end{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
829 \end{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
830 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
831 Because MQ makes the names of patches available to the rest of |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
832 Mercurial through its normal internal tag machinery, you don't need to |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
833 type in the entire name of a patch when you want to identify it by |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
834 name. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
835 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
836 \begin{figure}[ht] |
155
914babdc99c8
run-example: better error if bogus section name found.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
837 \interaction{mq.id.output} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
838 \caption{Using MQ's tag features to work with patches} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
839 \label{ex:mq:id} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
840 \end{figure} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
841 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
842 Another nice consequence of representing patch names as tags is that |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
843 when you run the \hgcmd{log} command, it will display a patch's name |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
844 as a tag, simply as part of its normal output. This makes it easy to |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
845 visually distinguish applied patches from underlying ``normal'' |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
846 revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
847 commands in use with applied patches. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
848 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
849 %\section{Useful things to know about} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
850 \section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} |
26 | 851 |
852 There are a number of aspects of MQ usage that don't fit tidily into | |
853 sections of their own, but that are good to know. Here they are, in | |
854 one place. | |
855 | |
856 \begin{itemize} | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
857 \item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it |
26 | 858 again, the changeset that represents the patch after the pop/push |
859 will have a \emph{different identity} than the changeset that | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
860 represented the hash beforehand. See |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
861 section~\ref{sec:mqref:cmd:qpush} for information as to why this is. |
26 | 862 \item It's not a good idea to \hgcmd{merge} changes from another |
863 branch with a patch changeset, at least if you want to maintain the | |
864 ``patchiness'' of that changeset and changesets below it on the | |
865 patch stack. If you try to do this, it will appear to succeed, but | |
866 MQ will become confused. | |
867 \end{itemize} | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
868 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
869 %\section{Managing patches in a repository} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
870 \section{$B%j%]%8%H%jFb$G$N%Q%C%A$N4IM}(B} |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
871 \label{sec:mq:repo} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
872 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
873 Because MQ's \sdirname{.hg/patches} directory resides outside a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
874 Mercurial repository's working directory, the ``underlying'' Mercurial |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
875 repository knows nothing about the management or presence of patches. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
876 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
877 This presents the interesting possibility of managing the contents of |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
878 the patch directory as a Mercurial repository in its own right. This |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
879 can be a useful way to work. For example, you can work on a patch for |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
880 a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
881 the patch. This lets you ``roll back'' to that version of the patch |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
882 later on. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
883 |
26 | 884 You can then share different versions of the same patch stack among |
885 multiple underlying repositories. I use this when I am developing a | |
886 Linux kernel feature. I have a pristine copy of my kernel sources for | |
887 each of several CPU architectures, and a cloned repository under each | |
888 that contains the patches I am working on. When I want to test a | |
889 change on a different architecture, I push my current patches to the | |
890 patch repository associated with that kernel tree, pop and push all of | |
891 my patches, and build and test that kernel. | |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
892 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
893 Managing patches in a repository makes it possible for multiple |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
894 developers to work on the same patch series without colliding with |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
895 each other, all on top of an underlying source base that they may or |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
896 may not control. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
897 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
898 %\subsection{MQ support for patch repositories} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
899 \subsection{MQ$B$K$h$k%Q%C%A%j%]%8%H%j%5%]!<%H(B} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
900 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
901 MQ helps you to work with the \sdirname{.hg/patches} directory as a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
902 repository; when you prepare a repository for working with patches |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
903 using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
904 create the \sdirname{.hg/patches} directory as a Mercurial repository. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
905 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
906 \begin{note} |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
907 If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
908 into the \sdirname{.hg/patches} directory at any time and run |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
909 \hgcmd{init}. Don't forget to add an entry for the |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
910 \sfilename{status} file to the \sfilename{.hgignore} file, though |
104
32bf9a5f22c0
Refactor MQ chapter into three.
Bryan O'Sullivan <bos@serpentine.com>
parents:
66
diff
changeset
|
911 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
912 (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
913 automatically); you \emph{really} don't want to manage the |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
914 \sfilename{status} file. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
915 \end{note} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
916 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
917 As a convenience, if MQ notices that the \dirname{.hg/patches} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
918 directory is a repository, it will automatically \hgcmd{add} every |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
919 patch that you create and import. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
920 |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
921 MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
922 \hgcmd{commit} in the \sdirname{.hg/patches} directory. This saves |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
923 some bothersome typing. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
924 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
925 Finally, as a convenience to manage the patch directory, you can |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
926 define the alias \command{mq} on Unix systems. For example, on Linux |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
927 systems using the \command{bash} shell, you can include the following |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
928 snippet in your \tildefile{.bashrc}. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
929 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
930 \begin{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
931 alias mq=`hg -R \$(hg root)/.hg/patches' |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
932 \end{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
933 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
934 You can then issue commands of the form \cmdargs{mq}{pull} from |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
935 the main repository. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
936 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
937 %\subsection{A few things to watch out for} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
938 \subsection{$B4F;k$7$F$*$/$Y$-$$$/$D$+$NE@(B} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
939 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
940 MQ's support for working with a repository full of patches is limited |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
941 in a few small respects. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
942 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
943 MQ cannot automatically detect changes that you make to the patch |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
944 directory. If you \hgcmd{pull}, manually edit, or \hgcmd{update} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
945 changes to patches or the \sfilename{series} file, you will have to |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
946 \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then |
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
947 \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
948 see those changes show up there. If you forget to do this, you can |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
949 confuse MQ's idea of which patches are applied. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
950 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
951 %\section{Third party tools for working with patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
952 \section{$B%Q%C%A8~$1%5!<%I%Q!<%F%#%D!<%k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
953 \label{sec:mq:tools} |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
954 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
955 Once you've been working with patches for a while, you'll find |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
956 yourself hungry for tools that will help you to understand and |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
957 manipulate the patches you're dealing with. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
958 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
959 The \command{diffstat} command~\cite{web:diffstat} generates a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
960 histogram of the modifications made to each file in a patch. It |
18
e6f4088ebe52
Generate a PDF file with a feedback link on each paragraph.
Bryan O'Sullivan <bos@serpentine.com>
parents:
17
diff
changeset
|
961 provides a good way to ``get a sense of'' a patch---which files it |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
962 affects, and how much change it introduces to each file and as a |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
963 whole. (I find that it's a good idea to use \command{diffstat}'s |
241
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
964 \cmdopt{diffstat}{-p} option as a matter of course, as otherwise it |
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
965 will try to do clever things with prefixes of file names that |
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
235
diff
changeset
|
966 inevitably confuse at least me.) |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
967 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
968 \begin{figure}[ht] |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
969 \interaction{mq.tools.tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
970 \caption{The \command{diffstat}, \command{filterdiff}, and \command{lsdiff} commands} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
971 \label{ex:mq:tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
972 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
973 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
974 The \package{patchutils} package~\cite{web:patchutils} is invaluable. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
975 It provides a set of small utilities that follow the ``Unix |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
976 philosophy;'' each does one useful thing with a patch. The |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
977 \package{patchutils} command I use most is \command{filterdiff}, which |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
978 extracts subsets from a patch file. For example, given a patch that |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
979 modifies hundreds of files across dozens of directories, a single |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
980 invocation of \command{filterdiff} can generate a smaller patch that |
106
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
981 only touches files whose names match a particular glob pattern. See |
9cbc5d0db542
Finish off advanced MQ chapter (maybe).
Bryan O'Sullivan <bos@serpentine.com>
parents:
104
diff
changeset
|
982 section~\ref{mq-collab:tips:interdiff} for another example. |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
983 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
984 %\section{Good ways to work with patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
985 \section{$B9%$^$7$$%Q%C%A<h$j07$$J}K!(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
986 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
987 Whether you are working on a patch series to submit to a free software |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
988 or open source project, or a series that you intend to treat as a |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
989 sequence of regular changesets when you're done, you can use some |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
990 simple techniques to keep your work well organised. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
991 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
992 Give your patches descriptive names. A good name for a patch might be |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
993 \filename{rework-device-alloc.patch}, because it will immediately give |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
994 you a hint what the purpose of the patch is. Long names shouldn't be |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
995 a problem; you won't be typing the names often, but you \emph{will} be |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
996 running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over and over. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
997 Good naming becomes especially important when you have a number of |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
998 patches to work with, or if you are juggling a number of different |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
999 tasks and your patches only get a fraction of your attention. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1000 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1001 Be aware of what patch you're working on. Use the \hgxcmd{mq}{qtop} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1002 command and skim over the text of your patches frequently---for |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1003 example, using \hgcmdargs{tip}{\hgopt{tip}{-p}})---to be sure of where |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1004 you stand. I have several times worked on and \hgxcmd{mq}{qrefresh}ed a |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1005 patch other than the one I intended, and it's often tricky to migrate |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1006 changes into the right patch after making them in the wrong one. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1007 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1008 For this reason, it is very much worth investing a little time to |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1009 learn how to use some of the third-party tools I described in |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1010 section~\ref{sec:mq:tools}, particularly \command{diffstat} and |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1011 \command{filterdiff}. The former will give you a quick idea of what |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1012 changes your patch is making, while the latter makes it easy to splice |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1013 hunks selectively out of one patch and into another. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1014 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1015 %\section{MQ cookbook} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1016 \section{MQ$B%/%C%/%V%C%/(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1017 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1018 %\subsection{Manage ``trivial'' patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1019 \subsection{``$B%H%j%S%"%k(B''$B$J%Q%C%A$N4IM}(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1020 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1021 Because the overhead of dropping files into a new Mercurial repository |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1022 is so low, it makes a lot of sense to manage patches this way even if |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1023 you simply want to make a few changes to a source tarball that you |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1024 downloaded. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1025 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1026 Begin by downloading and unpacking the source tarball, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1027 and turning it into a Mercurial repository. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1028 \interaction{mq.tarball.download} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1029 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1030 Continue by creating a patch stack and making your changes. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1031 \interaction{mq.tarball.qinit} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1032 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1033 Let's say a few weeks or months pass, and your package author releases |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1034 a new version. First, bring their changes into the repository. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1035 \interaction{mq.tarball.newsource} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1036 The pipeline starting with \hgcmd{locate} above deletes all files in |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1037 the working directory, so that \hgcmd{commit}'s |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1038 \hgopt{commit}{--addremove} option can actually tell which files have |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1039 really been removed in the newer version of the source. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1040 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1041 Finally, you can apply your patches on top of the new tree. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1042 \interaction{mq.tarball.repush} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1043 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1044 %\subsection{Combining entire patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1045 \subsection{$B%Q%C%AF1;N$r7k9g$9$k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1046 \label{sec:mq:combine} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1047 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1048 MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire |
55 | 1049 patches. This ``folds'' the patches you name, in the order you name |
1050 them, into the topmost applied patch, and concatenates their | |
1051 descriptions onto the end of its description. The patches that you | |
1052 fold must be unapplied before you fold them. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1053 |
55 | 1054 The order in which you fold patches matters. If your topmost applied |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1055 patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and |
55 | 1056 \texttt{quux} into it, you will end up with a patch that has the same |
1057 effect as if you applied first \texttt{foo}, then \texttt{bar}, | |
1058 followed by \texttt{quux}. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1059 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1060 %\subsection{Merging part of one patch into another} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1061 \subsection{$B%Q%C%A$N0lItJ,$rJL$N%Q%C%A$X%^!<%8$9$k(B} |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1062 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1063 Merging \emph{part} of one patch into another is more difficult than |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1064 combining entire patches. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1065 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1066 If you want to move changes to entire files, you can use |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1067 \command{filterdiff}'s \cmdopt{filterdiff}{-i} and |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1068 \cmdopt{filterdiff}{-x} options to choose the modifications to snip |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1069 out of one patch, concatenating its output onto the end of the patch |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1070 you want to merge into. You usually won't need to modify the patch |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1071 you've merged the changes from. Instead, MQ will report some rejected |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1072 hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the |
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1073 other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1074 the duplicate hunks. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1075 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1076 If you have a patch that has multiple hunks modifying a file, and you |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1077 only want to move a few of those hunks, the job becomes more messy, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1078 but you can still partly automate it. Use \cmdargs{lsdiff}{-nvv} to |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1079 print some metadata about the patch. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1080 \interaction{mq.tools.lsdiff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1081 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1082 This command prints three different kinds of number: |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1083 \begin{itemize} |
26 | 1084 \item (in the first column) a \emph{file number} to identify each file |
1085 modified in the patch; | |
1086 \item (on the next line, indented) the line number within a modified | |
1087 file where a hunk starts; and | |
1088 \item (on the same line) a \emph{hunk number} to identify that hunk. | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1089 \end{itemize} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1090 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1091 You'll have to use some visual inspection, and reading of the patch, |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1092 to identify the file and hunk numbers you'll want, but you can then |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1093 pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1094 and \cmdopt{filterdiff}{--hunks} options, to select exactly the file |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1095 and hunk you want to extract. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1096 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1097 Once you have this hunk, you can concatenate it onto the end of your |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1098 destination patch and continue with the remainder of |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1099 section~\ref{sec:mq:combine}. |
26 | 1100 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1101 %\section{Differences between quilt and MQ} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1102 \section{$B%-%k%H$H(BMQ$B$N0c$$(B} |
26 | 1103 |
1104 If you are already familiar with quilt, MQ provides a similar command | |
1105 set. There are a few differences in the way that it works. | |
1106 | |
1107 You will already have noticed that most quilt commands have MQ | |
1108 counterparts that simply begin with a ``\texttt{q}''. The exceptions | |
1109 are quilt's \texttt{add} and \texttt{remove} commands, the | |
1110 counterparts for which are the normal Mercurial \hgcmd{add} and | |
1111 \hgcmd{remove} commands. There is no MQ equivalent of the quilt | |
1112 \texttt{edit} command. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1113 |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1114 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
1115 %%% mode: yatex |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1116 %%% TeX-master: "00book" |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1117 %%% End: |