Mercurial > hgbook
annotate ja/mq.tex @ 324:7dc8a24c70f4
more mq.tex
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Fri, 28 Mar 2008 01:13:26 +0900 |
parents | 2d1054e1de5b |
children | a8269a1b9164 |
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 |
324 | 149 %In mid-2005, Chris Mason took the features of quilt and wrote an |
150 %extension that he called Mercurial Queues, which added quilt-like | |
151 %behaviour to Mercurial. | |
152 | |
153 2005$BG/$NCf:"(BChris Mason$B$O!$(Bquilt$B$N5!G=$r<h$jF~$l$F!$(BMercurial$B$K(Bquilt$B$N$h(B | |
154 $B$&$JF0:n$rDI2C$9$k(BMercurial Queues$B$H$$$&%(%/%9%F%s%7%g%s$r=q$$$?!%(B | |
155 | |
156 %The key difference between quilt and MQ is that quilt knows nothing | |
157 %about revision control systems, while MQ is \emph{integrated} into | |
158 %Mercurial. Each patch that you push is represented as a Mercurial | |
159 %changeset. Pop a patch, and the changeset goes away. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
160 |
324 | 161 quilt$B$H(BMQ$B$N0c$$$O!$(Bquilt$B$O%j%S%8%g%s4IM}%7%9%F%`$K$D$$$F2?$b4XCN$7$J$$$N(B |
162 $B$KBP$7$F!$(BMQ$B$O(BMercurial$B$KE}9g$5$l$F$$$k$3$H$G$"$k!%%W%C%7%e$7$?8D!9$N%Q%C(B | |
163 $B%A$O(BMercurial$B$N%A%'%s%8%;%C%H$H$7$FI=8=$5$l$k!%%Q%C%A$r%]%C%W$9$k$H!$%A%'(B | |
164 $B%s%8%;%C%H$O>C$($F$J$/$J$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
165 |
324 | 166 %Because quilt does not care about revision control tools, it is still |
167 %a tremendously useful piece of software to know about for situations | |
168 %where you cannot use Mercurial and MQ. | |
169 | |
170 quilt$B$O%j%S%8%g%s4IM}%D!<%k$HL54X78$KMxMQ2DG=$J$?$a!$(BMercurial$B$H(BMQ$B$,;H$((B | |
171 $B$J$$>u67$G$O0MA3$H$7$FHs>o$KM-1W$J%D!<%k$G$"$k$3$H$O5-21$KN1$a$F$*$/$Y$-(B | |
172 $B$G$"$k!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
173 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
174 %\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
|
175 \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
|
176 |
324 | 177 %I cannot overstate the value that MQ offers through the unification of |
178 %patches and revision control. | |
179 | |
180 MQ$B$,%Q%C%A$H%j%S%8%g%s%3%s%H%m!<%k$NE}9g$K$h$C$F$b$?$i$92ACM$r8XD%$9$k$o(B | |
181 $B$1$K$O$$$+$J$$!%(B | |
182 | |
183 %A major reason that patches have persisted in the free software and | |
184 %open source world---in spite of the availability of increasingly | |
185 %capable revision control tools over the years---is the \emph{agility} | |
186 %they offer. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
187 |
324 | 188 $B;~$rDI$&Kh$K%j%S%8%g%s%3%s%H%m!<%k%D!<%k$NMxMQ$,9-$,$C$F$$$k$K$b$+$+$o$i(B |
189 $B$:!$%U%j!<%=%U%H$H%*!<%W%s%=!<%9$N@$3&$K%Q%C%A$,B8:_$9$kBg$-$JM}M3$O$=$N(B | |
190 \emph{$B5!IR$5(B}$B$K$"$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
191 |
324 | 192 %Traditional revision control tools make a permanent, irreversible |
193 %record of everything that you do. While this has great value, it's | |
194 %also somewhat stifling. If you want to perform a wild-eyed | |
195 %experiment, you have to be careful in how you go about it, or you risk | |
196 %leaving unneeded---or worse, misleading or destabilising---traces of | |
197 %your missteps and errors in the permanent revision record. | |
198 | |
199 $BEAE}E*$J%j%S%8%g%s%3%s%H%m!<%k%D!<%k$O!$9T$J$C$?A`:n$N1J5WE*$GIT2D5UE*$J(B | |
200 $B5-O?$r;D$9!%$3$l$K$OBg$-$J2ACM$,$"$k0lJ}$G!$5g6~$K46$8$k$3$H$b$"$k!%$b$7(B | |
201 $B2a7c$J<B83$r$9$k$N$G$"$l$P!$$I$N$h$&$K?J$a$k$+?5=E$K$9$kI,MW$,$"$k!%$5$b(B | |
202 $B$J$1$l$P!$ITMW$J!$$"$k$$$O8m2r$r>7$$$?$j!$0BDj@-$rB;$J$&%H%l!<%9$H%(%i!<(B | |
203 $B$r1J5WE*$J%j%S%8%g%sMzNr$K;D$9$3$H$K$J$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
204 |
324 | 205 %By contrast, MQ's marriage of distributed revision control with |
206 %patches makes it much easier to isolate your work. Your patches live | |
207 %on top of normal revision history, and you can make them disappear or | |
208 %reappear at will. If you don't like a patch, you can drop it. If a | |
209 %patch isn't quite as you want it to be, simply fix it---as many times | |
210 %as you need to, until you have refined it into the form you desire. | |
211 | |
212 $BBP>NE*$K!$(BMQ$B$K$h$kJ,;6%j%S%8%g%s%3%s%H%m!<%k$H%Q%C%A$N7k9g$O!$:n6H$r3VN%(B | |
213 $B$9$k$3$H$rMZ$+$KMF0W$K$9$k!%%Q%C%A$ODL>o$N%j%S%8%g%sMzNr$N>e$K>h$C$F$*$j!$(B | |
214 $BK>$`$h$&$K>CLG$5$;$?$j:F8=$5$;$k$3$H$,$G$-$k!%%Q%C%A$r5$$KF~$i$J$1$l$P!$(B | |
215 $B$3$l$r4~5Q$9$k$3$H$b$G$-$k!%%Q%C%A$,$"$J$?$NK>$`$h$&$J$b$N$G$J$1$l$P!$4u(B | |
216 $BK>DL$j$K$J$k$^$G2?EY$G$b4JC1$K=$@5$9$k$3$H$,$G$-$k!%(B | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
217 |
324 | 218 %As an example, the integration of patches with revision control makes |
219 %understanding patches and debugging their effects---and their | |
220 %interplay with the code they're based on---\emph{enormously} easier. | |
221 %Since every applied patch has an associated changeset, you can use | |
222 %\hgcmdargs{log}{\emph{filename}} to see which changesets and patches | |
223 %affected a file. You can use the \hgext{bisect} command to | |
224 %binary-search through all changesets and applied patches to see where | |
225 %a bug got introduced or fixed. You can use the \hgcmd{annotate} | |
226 %command to see which changeset or patch modified a particular line of | |
227 %a source file. And so on. | |
228 | |
229 $BNc$($P!$%j%S%8%g%s%3%s%H%m!<%k$X$N%Q%C%A$NE}9g$O!$%Q%C%A$rM}2r$7!$$=$N1F(B | |
230 $B6A!$0M$C$FN)$D%Y!<%9%3!<%I$H$NAj8_:nMQ$r%G%P%C%0$9$k$3$H$r2DG=$K$9$k!%E,(B | |
231 $BMQ$5$l$?%Q%C%A$O!$4XO"$E$1$i$l$?%A%'%s%8%;%C%H$r;}$D$?$a!$(B | |
232 \hgcmdargs{log}{\emph{filename}}$B$K$h$C$F$I$N%A%'%s%8%;%C%H$H%Q%C%A$,%U%!(B | |
233 $B%$%k$K1F6A$rM?$($F$$$k$+D4$Y$k$3$H$,$G$-$k!%(B\hgext{bisect}$B%3%^%s%I$GA4$F(B | |
234 $B$N%A%'%s%8%;%C%H$HE,MQ$5$l$?%Q%C%A$KBP$7$F%P%$%J%j%5!<%A$r9T$J$$!$$I$3$G(B | |
235 $B%P%0$,:.F~$7$?$+!$$"$k$$$O=$@5$5$l$?$+$rD4$Y$k$3$H$,$G$-$k!%(B | |
236 \hgcmd{annotate}$B%3%^%s%I$G$I$N%A%'%s%8%;%C%H$+%Q%C%A$,%=!<%9%U%!%$%k$NFC(B | |
237 $BDj$N9T$rJQ99$7$?$+8+$k$3$H$,$G$-$k!%(B | |
238 | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
239 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
240 %\section{Understanding patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
241 \section{$B%Q%C%A$H$O2?$+(B} |
26 | 242 \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
|
243 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
244 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
|
245 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
|
246 with them. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
247 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
248 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
|
249 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
|
250 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
|
251 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
|
252 these commands in action. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
253 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
254 \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
|
255 \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
|
256 \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
|
257 \label{ex:mq:diff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
258 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
259 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
260 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
|
261 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
|
262 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
|
263 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
|
264 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
265 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
|
266 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
|
267 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
|
268 \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
|
269 string ``\texttt{diff~-}''. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
270 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
271 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
|
272 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
|
273 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
|
274 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
|
275 \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
|
276 name to start modifying. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
277 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
278 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
|
279 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
|
280 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
|
281 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
|
282 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
|
283 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
|
284 \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
|
285 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
|
286 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
287 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
|
288 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
|
289 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
|
290 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
|
291 deletion and one insertion. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
292 |
66 | 293 We will return to some of the more subtle aspects of patches later (in |
26 | 294 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
|
295 now to use MQ. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
296 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
297 %\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
|
298 \section{Mercurial Queues$B$r;H$C$F$_$k(B} |
2 | 299 \label{sec:mq:start} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
300 |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
301 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
|
302 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
|
303 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
|
304 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. |
2 | 305 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
306 \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
|
307 \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
|
308 [extensions] |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
309 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
|
310 \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
|
311 \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
|
312 \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
|
313 \end{figure} |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
314 |
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
315 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
|
316 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
|
317 \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
|
318 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
|
319 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
320 \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
|
321 \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
|
322 \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
|
323 \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
|
324 \end{figure} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
325 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
326 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
|
327 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
|
328 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
|
329 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
|
330 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
|
331 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
|
332 if it succeeds. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
333 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
334 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
335 \interaction{mq.tutorial.qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
336 \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
|
337 \label{ex:mq:qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
338 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
339 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
340 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
341 \interaction{mq.tutorial.qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
342 \caption{Creating a new patch} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
343 \label{ex:mq:qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
344 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
345 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
346 %\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
|
347 \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
|
348 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
349 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
|
350 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
|
351 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
|
352 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
|
353 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
354 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
|
355 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
|
356 \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
|
357 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
|
358 \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
|
359 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
|
360 |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
361 \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
|
362 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
|
363 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
|
364 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
|
365 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
|
366 is happening. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
367 \end{note} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
368 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
369 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
|
370 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
|
371 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
|
372 they did before. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
373 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
374 %\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
|
375 \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
|
376 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
377 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
|
378 \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
|
379 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
|
380 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
|
381 changeset to contain those changes. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
382 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
383 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
384 \interaction{mq.tutorial.qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
385 \caption{Refreshing a patch} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
386 \label{ex:mq:qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
387 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
388 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
389 You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way |
13 | 390 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
|
391 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
|
392 \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
|
393 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
394 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
395 \interaction{mq.tutorial.qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
396 \caption{Refresh a patch many times to accumulate changes} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
397 \label{ex:mq:qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
398 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
399 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
400 %\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
|
401 \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
|
402 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
403 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
|
404 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
|
405 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
|
406 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
|
407 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
|
408 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
|
409 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
410 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
411 \interaction{mq.tutorial.qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
412 \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
|
413 \label{ex:mq:qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
414 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
415 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
416 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
|
417 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
|
418 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
|
419 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
|
420 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
421 \begin{itemize} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
422 \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
|
423 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
|
424 \emph{created}). |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
425 \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
|
426 \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
|
427 recently applied). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
428 \end{itemize} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
429 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
430 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
431 \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
|
432 \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
|
433 \hgxcmd{mq}{qapplied}} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
434 \label{ex:mq:qseries} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
435 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
436 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
437 %\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
|
438 \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
|
439 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
440 The previous discussion implied that there must be a difference |
11 | 441 between ``known'' and ``applied'' patches, and there is. MQ can |
442 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
|
443 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
444 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
|
445 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
|
446 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
|
447 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
|
448 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
|
449 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
|
450 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
|
451 difference between applied and tracked patches. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
452 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
453 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
454 \centering |
35
e68f4a96c16e
Fixed the \grafix macro to work for PDFs again.
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
30
diff
changeset
|
455 \grafix{mq-stack} |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
456 \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
|
457 \label{fig:mq:stack} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
458 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
459 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
460 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
|
461 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
|
462 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
|
463 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
|
464 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
|
465 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
|
466 that of \hgxcmd{mq}{qapplied} has changed. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
467 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
468 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
469 \interaction{mq.tutorial.qpop} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
470 \caption{Modifying the stack of applied patches} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
471 \label{ex:mq:qpop} |
11 | 472 \end{figure} |
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{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
|
475 \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
|
476 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
477 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
|
478 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
|
479 \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
|
480 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
|
481 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
|
482 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
|
483 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
484 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
485 \interaction{mq.tutorial.qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
486 \caption{Pushing all unapplied patches} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
487 \label{ex:mq:qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
488 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
489 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
490 %\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
|
491 \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
|
492 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
493 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
|
494 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
|
495 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
|
496 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
|
497 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
|
498 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
|
499 \filename{file3}. |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
500 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
501 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
502 \interaction{mq.tutorial.add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
503 \caption{Forcibly creating a patch} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
504 \label{ex:mq:add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
505 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
506 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
507 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
|
508 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
|
509 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
|
510 \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
|
511 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
|
512 \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
|
513 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
|
514 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
|
515 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
516 %\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
|
517 \subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} |
13 | 518 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
519 The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} |
13 | 520 applied patch. This means that you can suspend work on one patch (by |
521 refreshing it), pop or push to make a different patch the top, and | |
522 work on \emph{that} patch for a while. | |
523 | |
524 Here's an example that illustrates how you can use this ability. | |
525 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
|
526 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
|
527 top of the first---changes the user interface to use the code you just |
13 | 528 added to the core. If you notice a bug in the core while you're |
529 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
|
530 \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
|
531 \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
|
532 \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI |
13 | 533 patch to continue where you left off. |
534 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
535 %\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
|
536 \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
|
537 \label{sec:mq:adv-patch} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
538 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
539 MQ uses the GNU \command{patch} command to apply patches, so it's |
26 | 540 helpful to know a few more detailed aspects of how \command{patch} |
541 works, and about patches themselves. | |
542 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
543 %\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
|
544 \subsection{$B%9%H%j%C%W%+%&%s%H(B} |
26 | 545 |
546 If you look at the file headers in a patch, you will notice that the | |
547 pathnames usually have an extra component on the front that isn't | |
548 present in the actual path name. This is a holdover from the way that | |
549 people used to generate patches (people still do this, but it's | |
550 somewhat rare with modern revision control tools). | |
551 | |
552 Alice would unpack a tarball, edit her files, then decide that she | |
553 wanted to create a patch. So she'd rename her working directory, | |
554 unpack the tarball again (hence the need for the rename), and use the | |
555 \cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to | |
556 recursively generate a patch between the unmodified directory and the | |
557 modified one. The result would be that the name of the unmodified | |
558 directory would be at the front of the left-hand path in every file | |
559 header, and the name of the modified directory would be at the front | |
560 of the right-hand path. | |
561 | |
562 Since someone receiving a patch from the Alices of the net would be | |
563 unlikely to have unmodified and modified directories with exactly the | |
564 same names, the \command{patch} command has a \cmdopt{patch}{-p} | |
565 option that indicates the number of leading path name components to | |
566 strip when trying to apply a patch. This number is called the | |
567 \emph{strip count}. | |
568 | |
569 An option of ``\texttt{-p1}'' means ``use a strip count of one''. If | |
570 \command{patch} sees a file name \filename{foo/bar/baz} in a file | |
571 header, it will strip \filename{foo} and try to patch a file named | |
572 \filename{bar/baz}. (Strictly speaking, the strip count refers to the | |
573 number of \emph{path separators} (and the components that go with them | |
574 ) to strip. A strip count of one will turn \filename{foo/bar} into | |
575 \filename{bar}, but \filename{/foo/bar} (notice the extra leading | |
576 slash) into \filename{foo/bar}.) | |
577 | |
578 The ``standard'' strip count for patches is one; almost all patches | |
579 contain one leading path name component that needs to be stripped. | |
580 Mercurial's \hgcmd{diff} command generates path names in this form, | |
581 and the \hgcmd{import} command and MQ expect patches to have a strip | |
582 count of one. | |
583 | |
584 If you receive a patch from someone that you want to add to your patch | |
585 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
|
586 just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet |
26 | 587 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
|
588 \hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} |
26 | 589 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
|
590 files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. |
26 | 591 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
|
592 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
593 %\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
|
594 \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
|
595 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
596 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
|
597 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
|
598 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
|
599 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
|
600 against a newer version of that file. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
601 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
602 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
|
603 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
|
604 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
|
605 context, without honouring the line numbering information. If this |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
606 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
|
607 but at some \emph{offset} from the original line number. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
608 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
609 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
|
610 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
|
611 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
|
612 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
|
613 after the fuzz factor indicates how many lines of context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
614 \command{patch} had to trim before the patch applied). |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
615 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
616 When neither of these techniques works, \command{patch} prints a |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
617 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
|
618 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
|
619 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
|
620 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
|
621 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
|
622 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
|
623 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
|
624 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
|
625 \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
|
626 the changes made by the five successful five hunks. |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
627 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
628 %\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
|
629 \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
|
630 |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
631 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
|
632 with files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
633 \begin{itemize} |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
634 \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
|
635 handle binary files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
636 \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
|
637 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
|
638 \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
|
639 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
|
640 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
|
641 deleted'' in a patch. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
642 \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
|
643 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
|
644 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
|
645 \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
|
646 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
|
647 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
|
648 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
|
649 \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
|
650 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
|
651 tree''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
652 \end{itemize} |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
653 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
654 %\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
|
655 \subsection{$B[#Kf$JE@$K$D$$$F(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
656 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
657 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
|
658 be completely successful, these inexact techniques naturally leave |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
659 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
|
660 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
|
661 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
|
662 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
|
663 modified files are correct afterwards. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
664 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
665 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
|
666 offset or fuzz factor; refreshing the patch generates new context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
667 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
|
668 ``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
|
669 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
|
670 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
|
671 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
|
672 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
|
673 patching process in such cases. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
674 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
675 %\subsection{Handling rejection} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
676 \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
|
677 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
678 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
|
679 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
|
680 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
|
681 or do any further work. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
682 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
683 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
|
684 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
|
685 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
|
686 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
687 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
|
688 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
|
689 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
|
690 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
691 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
|
692 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
|
693 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
|
694 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
695 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
|
696 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
|
697 \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
|
698 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
|
699 \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
|
700 may be rejected: |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
701 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
702 \begin{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
703 \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
|
704 \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
|
705 \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
|
706 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
|
707 \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
|
708 currently present in the file. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
709 \end{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
710 |
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
|
711 If you use \command{wiggle} or \command{mpatch}, you should be doubly |
55 | 712 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
|
713 \command{mpatch} enforces this method of double-checking the tool's |
55 | 714 output, by automatically dropping you into a merge program when it has |
715 done its job, so that you can verify its work and finish off any | |
716 remaining merges. | |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
717 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
718 %\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
|
719 \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
|
720 \label{sec:mq:perf} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
721 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
722 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
|
723 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
|
724 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
|
725 set the Linux 2.6.17-mm1 patch series, which consists of 1,738 |
66 | 726 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
|
727 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
|
728 2.6.17. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
729 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
730 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
|
731 \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
|
732 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
|
733 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
|
734 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
|
735 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
|
736 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
737 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
|
738 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
|
739 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
740 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
|
741 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
|
742 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
|
743 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
|
744 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
|
745 (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
|
746 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
747 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
|
748 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
|
749 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
|
750 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
|
751 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
|
752 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
|
753 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
754 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
|
755 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
|
756 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
|
757 is one, and so on. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
758 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
759 %\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
|
760 \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
|
761 \label{sec:mq:merge} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
762 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
763 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
|
764 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
|
765 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
|
766 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
|
767 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
|
768 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
|
769 patch series. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
770 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
771 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
|
772 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
|
773 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
|
774 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
|
775 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
|
776 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
|
777 until you have fixed your entire stack. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
778 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
779 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
|
780 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
|
781 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
|
782 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
|
783 hunks by hand quickly becomes tiresome. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
784 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
785 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
|
786 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
|
787 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
|
788 patches and a different revision. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
789 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
790 The process is a little involved. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
791 \begin{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
792 \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
|
793 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
|
794 \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
|
795 \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
|
796 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
|
797 save the patches to a directory called |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
798 \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
|
799 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
|
800 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
|
801 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
|
802 \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
|
803 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
|
804 \item Update to the new tip revision, using |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
805 \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
|
806 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
|
807 \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
|
808 \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
|
809 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
|
810 \end{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
811 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
812 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
|
813 \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
|
814 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
|
815 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
|
816 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
|
817 merge tool to help you to resolve problems. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
818 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
819 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
|
820 patch based on the result of the merge. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
821 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
822 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
|
823 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
|
824 \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
|
825 \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
|
826 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
|
827 you are sure that you no longer need it as a backup. |
13 | 828 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
829 %\section{Identifying patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
830 \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
|
831 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
832 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
|
833 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
|
834 name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will |
55 | 835 push patches until \filename{foo.patch} is applied. |
836 | |
837 As a shortcut, you can refer to a patch using both a name and a | |
838 numeric offset; \texttt{foo.patch-2} means ``two patches before | |
839 \texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches | |
840 after \texttt{bar.patch}''. | |
50
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 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
|
843 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
|
844 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
|
845 so on |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
846 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
847 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
|
848 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
|
849 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
|
850 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
|
851 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
|
852 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
|
853 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
|
854 topmost applied patches, respectively. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
855 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
856 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
|
857 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
|
858 \begin{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
859 \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
|
860 changes? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
861 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
862 hg email qbase:qtip |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
863 \end{codesample4} |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
864 (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
|
865 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
|
866 \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
|
867 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
|
868 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
869 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
|
870 \end{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
871 \end{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
872 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
873 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
|
874 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
|
875 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
|
876 name. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
877 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
878 \begin{figure}[ht] |
155
914babdc99c8
run-example: better error if bogus section name found.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
879 \interaction{mq.id.output} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
880 \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
|
881 \label{ex:mq:id} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
882 \end{figure} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
883 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
884 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
|
885 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
|
886 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
|
887 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
|
888 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
|
889 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
|
890 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
891 %\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
|
892 \section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} |
26 | 893 |
894 There are a number of aspects of MQ usage that don't fit tidily into | |
895 sections of their own, but that are good to know. Here they are, in | |
896 one place. | |
897 | |
898 \begin{itemize} | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
899 \item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it |
26 | 900 again, the changeset that represents the patch after the pop/push |
901 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
|
902 represented the hash beforehand. See |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
903 section~\ref{sec:mqref:cmd:qpush} for information as to why this is. |
26 | 904 \item It's not a good idea to \hgcmd{merge} changes from another |
905 branch with a patch changeset, at least if you want to maintain the | |
906 ``patchiness'' of that changeset and changesets below it on the | |
907 patch stack. If you try to do this, it will appear to succeed, but | |
908 MQ will become confused. | |
909 \end{itemize} | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
910 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
911 %\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
|
912 \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
|
913 \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
|
914 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
915 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
|
916 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
|
917 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
|
918 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
919 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
|
920 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
|
921 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
|
922 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
|
923 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
|
924 later on. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
925 |
26 | 926 You can then share different versions of the same patch stack among |
927 multiple underlying repositories. I use this when I am developing a | |
928 Linux kernel feature. I have a pristine copy of my kernel sources for | |
929 each of several CPU architectures, and a cloned repository under each | |
930 that contains the patches I am working on. When I want to test a | |
931 change on a different architecture, I push my current patches to the | |
932 patch repository associated with that kernel tree, pop and push all of | |
933 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
|
934 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
935 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
|
936 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
|
937 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
|
938 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
|
939 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
940 %\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
|
941 \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
|
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 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
|
944 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
|
945 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
|
946 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
|
947 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
948 \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
|
949 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
|
950 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
|
951 \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
|
952 \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
|
953 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
954 (\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
|
955 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
|
956 \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
|
957 \end{note} |
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 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
|
960 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
|
961 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
|
962 |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
963 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
|
964 \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
|
965 some bothersome typing. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
966 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
967 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
|
968 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
|
969 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
|
970 snippet in your \tildefile{.bashrc}. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
971 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
972 \begin{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
973 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
|
974 \end{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
975 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
976 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
|
977 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
|
978 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
979 %\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
|
980 \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
|
981 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
982 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
|
983 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
|
984 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
985 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
|
986 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
|
987 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
|
988 \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
|
989 \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
|
990 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
|
991 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
|
992 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
993 %\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
|
994 \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
|
995 \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
|
996 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
997 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
|
998 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
|
999 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
|
1000 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1001 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
|
1002 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
|
1003 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
|
1004 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
|
1005 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
|
1006 \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
|
1007 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
|
1008 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
|
1009 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1010 \begin{figure}[ht] |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1011 \interaction{mq.tools.tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1012 \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
|
1013 \label{ex:mq:tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1014 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1015 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1016 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
|
1017 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
|
1018 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
|
1019 \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
|
1020 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
|
1021 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
|
1022 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
|
1023 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
|
1024 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
|
1025 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1026 %\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
|
1027 \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
|
1028 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1029 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
|
1030 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
|
1031 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
|
1032 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
|
1033 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1034 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
|
1035 \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
|
1036 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
|
1037 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
|
1038 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
|
1039 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
|
1040 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
|
1041 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
|
1042 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1043 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
|
1044 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
|
1045 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
|
1046 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
|
1047 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
|
1048 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
|
1049 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1050 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
|
1051 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
|
1052 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
|
1053 \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
|
1054 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
|
1055 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
|
1056 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1057 %\section{MQ cookbook} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1058 \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
|
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{Manage ``trivial'' patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1061 \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
|
1062 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1063 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
|
1064 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
|
1065 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
|
1066 downloaded. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1067 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1068 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
|
1069 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
|
1070 \interaction{mq.tarball.download} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1071 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1072 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
|
1073 \interaction{mq.tarball.qinit} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1074 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1075 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
|
1076 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
|
1077 \interaction{mq.tarball.newsource} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1078 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
|
1079 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
|
1080 \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
|
1081 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
|
1082 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1083 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
|
1084 \interaction{mq.tarball.repush} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1085 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1086 %\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
|
1087 \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
|
1088 \label{sec:mq:combine} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1089 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1090 MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire |
55 | 1091 patches. This ``folds'' the patches you name, in the order you name |
1092 them, into the topmost applied patch, and concatenates their | |
1093 descriptions onto the end of its description. The patches that you | |
1094 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
|
1095 |
55 | 1096 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
|
1097 patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and |
55 | 1098 \texttt{quux} into it, you will end up with a patch that has the same |
1099 effect as if you applied first \texttt{foo}, then \texttt{bar}, | |
1100 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
|
1101 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1102 %\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
|
1103 \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
|
1104 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1105 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
|
1106 combining entire patches. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1107 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1108 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
|
1109 \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
|
1110 \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
|
1111 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
|
1112 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
|
1113 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
|
1114 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
|
1115 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
|
1116 the duplicate hunks. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1117 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1118 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
|
1119 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
|
1120 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
|
1121 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
|
1122 \interaction{mq.tools.lsdiff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1123 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1124 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
|
1125 \begin{itemize} |
26 | 1126 \item (in the first column) a \emph{file number} to identify each file |
1127 modified in the patch; | |
1128 \item (on the next line, indented) the line number within a modified | |
1129 file where a hunk starts; and | |
1130 \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
|
1131 \end{itemize} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1132 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1133 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
|
1134 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
|
1135 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
|
1136 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
|
1137 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
|
1138 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1139 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
|
1140 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
|
1141 section~\ref{sec:mq:combine}. |
26 | 1142 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1143 %\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
|
1144 \section{$B%-%k%H$H(BMQ$B$N0c$$(B} |
26 | 1145 |
1146 If you are already familiar with quilt, MQ provides a similar command | |
1147 set. There are a few differences in the way that it works. | |
1148 | |
1149 You will already have noticed that most quilt commands have MQ | |
1150 counterparts that simply begin with a ``\texttt{q}''. The exceptions | |
1151 are quilt's \texttt{add} and \texttt{remove} commands, the | |
1152 counterparts for which are the normal Mercurial \hgcmd{add} and | |
1153 \hgcmd{remove} commands. There is no MQ equivalent of the quilt | |
1154 \texttt{edit} command. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1155 |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1156 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
1157 %%% mode: yatex |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1158 %%% TeX-master: "00book" |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1159 %%% End: |