Mercurial > hgbook
annotate ja/mq.tex @ 327:7dbc8f2a5f7a
small fix
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Sat, 29 Mar 2008 05:30:34 +0900 |
parents | e03366f4d1e5 |
children | 8bdd9bc948d4 |
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 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
9 %Here is a common scenario: you need to install a software package from |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
10 %source, but you find a bug that you must fix in the source before you |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
11 %can start using the package. You make your changes, forget about the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
12 %package for a while, and a few months later you need to upgrade to a |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
13 %newer version of the package. If the newer version of the package |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
14 %still has the bug, you must extract your fix from the older source |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
15 %tree and apply it against the newer version. This is a tedious task, |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
16 %and it's easy to make mistakes. |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
17 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
18 $B$h$/$"$k%7%J%j%*!'%=!<%9$+$i%=%U%H%&%'%"%Q%C%1!<%8$r%$%s%9%H!<%k$9$kI,MW(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
19 $B$,$"$k!%$7$+$7%Q%C%1!<%8$r;H$&A0$K%=!<%9$+$iD>$9$Y$-%P%0$r8+$D$1$?!%JQ99(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
20 $B$r2C$($F!$;C$/%Q%C%1!<%8$N$3$H$OK:$l$F$$$k!%?t%v7n8e!$?7$7$$%P!<%8%g%s$r(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
21 $B%$%s%9%H!<%k$9$k$3$H$K$J$C$?!%$b$7?7$7$$%P!<%8%g%s$,!$0MA3$H$7$F$=$N%P%0(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
22 $B$r;}$C$F$$$?>l9g!$=$@5$r8E$$%=!<%9$+$iCj=P$7$F!$?7$7$$%P!<%8%g%s$KE,MQ$7(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
23 $B$J$1$l$P$J$i$J$$!%$3$l$OB`6~$G$7$+$b4V0c$$$d$9$$;E;v$@!%(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
24 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
25 %This is a simple case of the ``patch management'' problem. You have |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
26 %an ``upstream'' source tree that you can't change; you need to make |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
27 %some local changes on top of the upstream tree; and you'd like to be |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
28 %able to keep those changes separate, so that you can apply them to |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
29 %newer versions of the upstream source. |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
30 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
31 $B$3$l$,%Q%C%A4IM}LdBj$N%7%s%W%k$JNc$G$"$k!%$b$7$"$J$?$,JQ99$G$-$J$$>eN.$N(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
32 $B%=!<%9%D%j!<$,$"$l$P!$%"%C%W%9%H%j!<%`$N%D%j!<$N>e$G%m!<%+%k$JJQ99$r$7$J(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
33 $B$1$l$P$J$i$J$$!%$"$J$?$O%"%C%W%9%H%j!<%`%=!<%9$KE,MQ$G$-$k$h$&$K$-$C$H$3(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
34 $B$NJQ99$rJ,N%$7$F$*$-$?$$$H;W$&$O$:$@!%(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
35 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
36 %The patch management problem arises in many situations. Probably the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
37 %most visible is that a user of an open source software project will |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
38 %contribute a bug fix or new feature to the project's maintainers in the |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
39 %form of a patch. |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
40 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
41 $B%Q%C%A4IM}LdBj$O$$$m$$$m$J>u67$G5/$3$k!%$*$=$i$/:G$bL@$i$+$J$N$O!$%*!<%W(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
42 $B%s%=!<%9%=%U%H%&%'%"%W%m%8%'%/%H$N%f!<%6$,!$%W%m%8%'%/%H$N%a%s%F%J$K%P%0(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
43 $B%U%#%C%/%9$d?75!G=$r%Q%C%A$N7A$G9W8%$9$k$3$H$G$"$m$&!%(B |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
44 |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
45 %Distributors of operating systems that include open source software |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
46 %often need to make changes to the packages they distribute so that |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
47 %they will build properly in their environments. |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
48 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
49 $B%*!<%W%s%=%U%H%&%'%"$r4^$`%*%Z%l!<%F%#%s%0%7%9%F%`$NG[I[<T$O!$G[I[$9$k%Q%C(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
50 $B%1!<%8$,H`$i$N4D6-$G@5$7$/%S%k%I$G$-$k$h$&$K%Q%C%1!<%8$XJQ99$r2C$($k$3$H(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
51 $B$,B?$$!%(B |
1
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 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
|
54 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
|
55 (see section~\ref{sec:mq:patch} for a discussion of these tools). |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
56 |
285
814698eebbaf
fixed a typo and formatted the notify hook configuration example nicer.
Timo Paulssen <timonator@perpetuum-immobile.de>
parents:
283
diff
changeset
|
57 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
|
58 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
|
59 patch will contain only one bug fix (the patch might modify several |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
60 files, but it's doing ``only one thing''), |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
61 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
62 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
63 and you may have a number |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
64 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
|
65 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
|
66 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
|
67 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
|
68 updating to the newer release. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
69 |
327 | 70 $B$b$7%a%s%F%J%s%9$7$F$$$kJQ99$,$o$:$+$J$i!$I8=`$N(B\command{diff}$B%3%^%s%I$H(B |
71 \command{patch}$B%3%^%s%I$r;H$C$FC10l$N%Q%C%A$r4IM}$9$k$N$,4JC1$@!%!J$3$l$i(B | |
72 $B$N%D!<%k$K$D$$$F$O(B~\ref{sec:mq:patch}$B$N@a$r;2>H!%!K(B | |
326
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
73 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
74 $BJQ99$N?t$,A}$($F$/$k$H!$C10l$N%P%0%U%#%C%/%9$@$1$r4^$`8DJL$N%Q%C%A$N=89g(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
75 $B$H$7$F4IM}$9$k$3$H$,8=<BL#$rBS$S$F$/$k!%!J$=$l$>$l$N%Q%C%A$OJ#?t$N%U%!%$(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
76 $B%k$rJQ99$9$k$+$b$7$l$J$$$,!$L\E*$O(B1$B$D$-$j$G$"$k!%!K(B |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
77 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
78 |
e03366f4d1e5
more mq.tex. in the mid of a paragraph, but I'm feeling tired.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
325
diff
changeset
|
79 |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
80 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
|
81 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
|
82 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
|
83 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
|
84 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
|
85 from messy to overwhelming. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
86 |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
87 Fortunately, Mercurial includes a powerful extension, Mercurial Queues |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
88 (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
|
89 problem. |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
90 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
91 %\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
|
92 \section{Mercurial Queues$BA0;K(B} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
93 \label{sec:mq:history} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
94 |
323 | 95 %During the late 1990s, several Linux kernel developers started to |
96 %maintain ``patch series'' that modified the behaviour of the Linux | |
97 %kernel. Some of these series were focused on stability, some on | |
98 %feature coverage, and others were more speculative. | |
99 | |
100 1990$BG/Be$N=*$o$j:"!$(BLinux$B%+!<%M%k$N3+H/<TC#$O!$(BLinux$B%+!<%M%k$r2~A1$9$k0l(B | |
101 $BO"$N%Q%C%A$N4IM}$r;O$a$?!%$=$l$i$N$&$A!$$"$k$b$N$O0BDj@-$K!$JL$N$b$N$OFC(B | |
102 $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
|
103 |
323 | 104 %The sizes of these patch series grew rapidly. In 2002, Andrew Morton |
105 %published some shell scripts he had been using to automate the task of | |
106 %managing his patch queues. Andrew was successfully using these | |
107 %scripts to manage hundreds (sometimes thousands) of patches on top of | |
108 %the Linux kernel. | |
109 | |
110 $B$3$l$i$N%Q%C%A%7%j!<%:$N%5%$%:$O$O$9$0$KKD$l>e$,$C$?!%(B2002$BG/$K(BAndrew | |
111 Morton$B$OH`$N%Q%C%A%-%e!<$N4IM}$r<+F02=$9$k$$$/$D$+$N%7%'%k%9%/%j%W%H$r8x(B | |
112 $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 | |
113 $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
|
114 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
115 %\subsection{A patchwork quilt} |
323 | 116 \subsection{patchwork quilt} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
117 \label{sec:mq:quilt} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
118 |
323 | 119 %In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the |
120 %approach of Andrew's scripts and published a tool called ``patchwork | |
121 %quilt''~\cite{web:quilt}, or simply ``quilt'' | |
122 %(see~\cite{gruenbacher:2005} for a paper describing it). Because | |
123 %quilt substantially automated patch management, it rapidly gained a | |
124 %large following among open source software developers. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
125 |
323 | 126 2003$BG/$N;O$a!$(BAndreas Gruenbacher$B$H(BMartin Quinson$B$O(BAndrew$B$N%9%/%j%W%H$N$d(B |
127 $B$jJ}$r??;w$F!$(B``patchwork quilt''~\cite{web:quilt}$B$"$k$$$OC1$K(B``quilt''$B$H(B | |
128 $B8F$P$l$k%D!<%k$r%j%j!<%9$7$?!%!J>\$7$/$OO@J8(B~\cite{gruenbacher:2005}$B$r;2(B | |
129 $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 | |
130 $B%&%'%"3+H/<T$NBg$-$J;Y;}$r5^B.$K3MF@$7$F$$$C$?!%(B | |
131 | |
132 %Quilt manages a \emph{stack of patches} on top of a directory tree. | |
133 %To begin, you tell quilt to manage a directory tree, and tell it which | |
134 %files you want to manage; it stores away the names and contents of | |
135 %those files. To fix a bug, you create a new patch (using a single | |
136 %command), edit the files you need to fix, then ``refresh'' the patch. | |
137 | |
138 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 | |
139 $B4IM}$r;O$a$k$K$O!$(Bquilt$B$K4IM}$9$Y$-%G%#%l%/%H%j%D%j!<$H!$4IM}BP>]$N%U%!%$(B | |
140 $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 | |
141 $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 | |
142 $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
|
143 |
323 | 144 %The refresh step causes quilt to scan the directory tree; it updates |
145 %the patch with all of the changes you have made. You can create | |
146 %another patch on top of the first, which will track the changes | |
147 %required to modify the tree from ``tree with one patch applied'' to | |
148 %``tree with two patches applied''. | |
149 | |
150 $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 | |
151 $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 | |
152 $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 | |
153 $B$3$H$b$G$-$k!%(B | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
154 |
323 | 155 %You can \emph{change} which patches are applied to the tree. If you |
156 %``pop'' a patch, the changes made by that patch will vanish from the | |
157 %directory tree. Quilt remembers which patches you have popped, | |
158 %though, so you can ``push'' a popped patch again, and the directory | |
159 %tree will be restored to contain the modifications in the patch.Most | |
160 %importantly, you can run the ``refresh'' command at any time, and the | |
161 %topmost applied patch will be updated. This means that you can, at | |
162 %any time, change both which patches are applied and what | |
163 %modifications those patches make. | |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
164 |
323 | 165 $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 |
166 $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 | |
167 $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 | |
168 $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 | |
169 $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 | |
170 $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 | |
171 $B%A$=$l<+BN$r$$$D$G$b99?7$G$-$k$H$$$&$3$H$G$"$k!%(B | |
172 | |
173 %Quilt knows nothing about revision control tools, so it works equally | |
174 %well on top of an unpacked tarball or a Subversion working copy. | |
175 | |
176 quilt$B$O%j%S%8%g%s4IM}%D!<%k$K$D$$$F$OA4$/4XCN$7$J$$$?$a!$E83+$5$l$?(Btar$B%\!<(B | |
177 $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
|
178 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
179 %\subsection{From patchwork quilt to Mercurial Queues} |
323 | 180 \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
|
181 \label{sec:mq:quilt-mq} |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
182 |
324 | 183 %In mid-2005, Chris Mason took the features of quilt and wrote an |
184 %extension that he called Mercurial Queues, which added quilt-like | |
185 %behaviour to Mercurial. | |
186 | |
187 2005$BG/$NCf:"(BChris Mason$B$O!$(Bquilt$B$N5!G=$r<h$jF~$l$F!$(BMercurial$B$K(Bquilt$B$N$h(B | |
188 $B$&$JF0:n$rDI2C$9$k(BMercurial Queues$B$H$$$&%(%/%9%F%s%7%g%s$r=q$$$?!%(B | |
189 | |
190 %The key difference between quilt and MQ is that quilt knows nothing | |
191 %about revision control systems, while MQ is \emph{integrated} into | |
192 %Mercurial. Each patch that you push is represented as a Mercurial | |
193 %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
|
194 |
324 | 195 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 |
196 $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 | |
197 $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 | |
198 $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
|
199 |
324 | 200 %Because quilt does not care about revision control tools, it is still |
201 %a tremendously useful piece of software to know about for situations | |
202 %where you cannot use Mercurial and MQ. | |
203 | |
204 quilt$B$O%j%S%8%g%s4IM}%D!<%k$HL54X78$KMxMQ2DG=$J$?$a!$(BMercurial$B$H(BMQ$B$,;H$((B | |
205 $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 | |
206 $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
|
207 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
208 %\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
|
209 \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
|
210 |
324 | 211 %I cannot overstate the value that MQ offers through the unification of |
212 %patches and revision control. | |
213 | |
214 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 | |
215 $B$1$K$O$$$+$J$$!%(B | |
216 | |
217 %A major reason that patches have persisted in the free software and | |
218 %open source world---in spite of the availability of increasingly | |
219 %capable revision control tools over the years---is the \emph{agility} | |
220 %they offer. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
221 |
324 | 222 $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 |
223 $B$:!$%U%j!<%=%U%H$H%*!<%W%s%=!<%9$N@$3&$K%Q%C%A$,B8:_$9$kBg$-$JM}M3$O$=$N(B | |
224 \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
|
225 |
324 | 226 %Traditional revision control tools make a permanent, irreversible |
227 %record of everything that you do. While this has great value, it's | |
228 %also somewhat stifling. If you want to perform a wild-eyed | |
229 %experiment, you have to be careful in how you go about it, or you risk | |
230 %leaving unneeded---or worse, misleading or destabilising---traces of | |
231 %your missteps and errors in the permanent revision record. | |
232 | |
233 $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 | |
234 $B5-O?$r;D$9!%$3$l$K$OBg$-$J2ACM$,$"$k0lJ}$G!$5g6~$K46$8$k$3$H$b$"$k!%$b$7(B | |
235 $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 | |
236 $B$J$1$l$P!$ITMW$J!$$"$k$$$O8m2r$r>7$$$?$j!$0BDj@-$rB;$J$&%H%l!<%9$H%(%i!<(B | |
237 $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
|
238 |
324 | 239 %By contrast, MQ's marriage of distributed revision control with |
240 %patches makes it much easier to isolate your work. Your patches live | |
241 %on top of normal revision history, and you can make them disappear or | |
242 %reappear at will. If you don't like a patch, you can drop it. If a | |
243 %patch isn't quite as you want it to be, simply fix it---as many times | |
244 %as you need to, until you have refined it into the form you desire. | |
245 | |
246 $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 | |
247 $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 | |
248 $BK>$`$h$&$K>CLG$5$;$?$j:F8=$5$;$k$3$H$,$G$-$k!%%Q%C%A$r5$$KF~$i$J$1$l$P!$(B | |
249 $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 | |
250 $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
|
251 |
324 | 252 %As an example, the integration of patches with revision control makes |
253 %understanding patches and debugging their effects---and their | |
254 %interplay with the code they're based on---\emph{enormously} easier. | |
255 %Since every applied patch has an associated changeset, you can use | |
256 %\hgcmdargs{log}{\emph{filename}} to see which changesets and patches | |
257 %affected a file. You can use the \hgext{bisect} command to | |
258 %binary-search through all changesets and applied patches to see where | |
259 %a bug got introduced or fixed. You can use the \hgcmd{annotate} | |
260 %command to see which changeset or patch modified a particular line of | |
261 %a source file. And so on. | |
262 | |
263 $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 | |
264 $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 | |
265 $BMQ$5$l$?%Q%C%A$O!$4XO"$E$1$i$l$?%A%'%s%8%;%C%H$r;}$D$?$a!$(B | |
266 \hgcmdargs{log}{\emph{filename}}$B$K$h$C$F$I$N%A%'%s%8%;%C%H$H%Q%C%A$,%U%!(B | |
267 $B%$%k$K1F6A$rM?$($F$$$k$+D4$Y$k$3$H$,$G$-$k!%(B\hgext{bisect}$B%3%^%s%I$GA4$F(B | |
268 $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 | |
269 $B%P%0$,:.F~$7$?$+!$$"$k$$$O=$@5$5$l$?$+$rD4$Y$k$3$H$,$G$-$k!%(B | |
270 \hgcmd{annotate}$B%3%^%s%I$G$I$N%A%'%s%8%;%C%H$+%Q%C%A$,%=!<%9%U%!%$%k$NFC(B | |
271 $BDj$N9T$rJQ99$7$?$+8+$k$3$H$,$G$-$k!%(B | |
272 | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
273 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
274 %\section{Understanding patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
275 \section{$B%Q%C%A$H$O2?$+(B} |
26 | 276 \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
|
277 |
325 | 278 %Because MQ doesn't hide its patch-oriented nature, it is helpful to |
279 %understand what patches are, and a little about the tools that work | |
280 %with them. | |
281 | |
282 MQ$B$O%Q%C%A;X8~$G$"$k@-<A$r1#JC$7$F$$$J$$$N$G!$%Q%C%A$,2?$G$"$k$+!$%D!<%k(B | |
283 $B$,%Q%C%A$r$I$&07$&$+$rM}2r$9$k$N$O$?$d$9$$!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
284 |
325 | 285 %The traditional Unix \command{diff} command compares two files, and |
286 %prints a list of differences between them. The \command{patch} command | |
287 %understands these differences as \emph{modifications} to make to a | |
288 %file. Take a look at figure~\ref{ex:mq:diff} for a simple example of | |
289 %these commands in action. | |
290 | |
291 Unix$B$NEAE}E*$J(B\command{diff}$B%3%^%s%I$O(B2$B$D$N%U%!%$%k$rHf3S$7!$:9J,$N%j%9(B | |
292 $B%H$r=PNO$9$k!%(B\command{patch}$B%3%^%s%I$O$3$N:9J,$rJQ99$H2r<a$7!$%U%!%$%k(B | |
293 $B$K5Z$\$9!%?^(B~\ref{ex:mq:diff}$B$K$3$l$i$N%3%^%s%I$NF0:n$r<($9!%(B | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
294 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
295 \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
|
296 \interaction{mq.dodiff.diff} |
325 | 297 % \caption{Simple uses of the \command{diff} and \command{patch} |
298 % commands} | |
299 \caption{\command{diff}$B%3%^%s%I$H(B\command{patch}$B%3%^%s%I$NC1=c$J;HMQNc(B} | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
300 \label{ex:mq:diff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
301 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
302 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
303 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
|
304 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
|
305 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
|
306 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
|
307 |
325 | 308 |
309 | |
310 | |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
311 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
|
312 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
|
313 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
|
314 \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
|
315 string ``\texttt{diff~-}''. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
316 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
317 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
|
318 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
|
319 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
|
320 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
|
321 \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
|
322 name to start modifying. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
323 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
324 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
|
325 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
|
326 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
|
327 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
|
328 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
|
329 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
|
330 \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
|
331 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
|
332 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
333 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
|
334 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
|
335 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
|
336 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
|
337 deletion and one insertion. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
338 |
66 | 339 We will return to some of the more subtle aspects of patches later (in |
26 | 340 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
|
341 now to use MQ. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
342 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
343 %\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
|
344 \section{Mercurial Queues$B$r;H$C$F$_$k(B} |
2 | 345 \label{sec:mq:start} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
346 |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
347 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
|
348 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
|
349 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
|
350 \tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}. |
2 | 351 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
352 \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
|
353 \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
|
354 [extensions] |
33a2e7b9978d
Make it possible to include example input and output from real programs.
Bryan O'Sullivan <bos@serpentine.com>
parents:
3
diff
changeset
|
355 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
|
356 \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
|
357 \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
|
358 \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
|
359 \end{figure} |
3
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
360 |
906d9021f9e5
Making progress on autogenerated example output.
Bryan O'Sullivan <bos@serpentine.com>
parents:
2
diff
changeset
|
361 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
|
362 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
|
363 \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
|
364 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
|
365 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
366 \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
|
367 \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
|
368 \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
|
369 \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
|
370 \end{figure} |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
371 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
372 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
|
373 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
|
374 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
|
375 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
|
376 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
|
377 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
|
378 if it succeeds. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
379 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
380 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
381 \interaction{mq.tutorial.qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
382 \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
|
383 \label{ex:mq:qinit} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
384 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
385 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
386 \begin{figure}[ht] |
7
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
387 \interaction{mq.tutorial.qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
388 \caption{Creating a new patch} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
389 \label{ex:mq:qnew} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
390 \end{figure} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
391 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
392 %\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
|
393 \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
|
394 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
395 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
|
396 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
|
397 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
|
398 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
|
399 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
400 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
|
401 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
|
402 \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
|
403 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
|
404 \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
|
405 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
|
406 |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
407 \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
|
408 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
|
409 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
|
410 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
|
411 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
|
412 is happening. |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
413 \end{note} |
339e75288632
More progress on MQ chapter and general support.
Bryan O'Sullivan <bos@serpentine.com>
parents:
4
diff
changeset
|
414 |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
415 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
|
416 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
|
417 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
|
418 they did before. |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
419 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
420 %\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
|
421 \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
|
422 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
423 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
|
424 \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
|
425 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
|
426 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
|
427 changeset to contain those changes. |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
428 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
429 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
430 \interaction{mq.tutorial.qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
431 \caption{Refreshing a patch} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
432 \label{ex:mq:qrefresh} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
433 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
434 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
435 You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way |
13 | 436 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
|
437 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
|
438 \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
|
439 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
440 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
441 \interaction{mq.tutorial.qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
442 \caption{Refresh a patch many times to accumulate changes} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
443 \label{ex:mq:qrefresh2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
444 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
445 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
446 %\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
|
447 \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
|
448 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
449 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
|
450 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
|
451 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
|
452 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
|
453 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
|
454 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
|
455 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
456 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
457 \interaction{mq.tutorial.qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
458 \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
|
459 \label{ex:mq:qnew2} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
460 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
461 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
462 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
|
463 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
|
464 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
|
465 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
|
466 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
467 \begin{itemize} |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
468 \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
|
469 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
|
470 \emph{created}). |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
471 \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
|
472 \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
|
473 recently applied). |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
474 \end{itemize} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
475 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
476 \begin{figure}[ht] |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
477 \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
|
478 \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
|
479 \hgxcmd{mq}{qapplied}} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
480 \label{ex:mq:qseries} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
481 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
482 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
483 %\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
|
484 \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
|
485 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
486 The previous discussion implied that there must be a difference |
11 | 487 between ``known'' and ``applied'' patches, and there is. MQ can |
488 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
|
489 |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
490 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
|
491 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
|
492 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
|
493 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
|
494 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
|
495 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
|
496 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
|
497 difference between applied and tracked patches. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
498 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
499 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
500 \centering |
35
e68f4a96c16e
Fixed the \grafix macro to work for PDFs again.
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
30
diff
changeset
|
501 \grafix{mq-stack} |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
502 \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
|
503 \label{fig:mq:stack} |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
504 \end{figure} |
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
505 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
506 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
|
507 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
|
508 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
|
509 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
|
510 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
|
511 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
|
512 that of \hgxcmd{mq}{qapplied} has changed. |
8
a25335b56825
Progress on MQ tutorial.
Bryan O'Sullivan <bos@serpentine.com>
parents:
7
diff
changeset
|
513 |
12
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
514 \begin{figure}[ht] |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
515 \interaction{mq.tutorial.qpop} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
516 \caption{Modifying the stack of applied patches} |
1f692024d438
More text for MQ chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
11
diff
changeset
|
517 \label{ex:mq:qpop} |
11 | 518 \end{figure} |
519 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
520 %\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
|
521 \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
|
522 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
523 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
|
524 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
|
525 \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
|
526 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
|
527 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
|
528 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
|
529 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
530 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
531 \interaction{mq.tutorial.qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
532 \caption{Pushing all unapplied patches} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
533 \label{ex:mq:qpush-a} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
534 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
535 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
536 %\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
|
537 \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
|
538 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
539 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
|
540 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
|
541 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
|
542 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
|
543 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
|
544 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
|
545 \filename{file3}. |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
546 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
547 \begin{figure}[ht] |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
548 \interaction{mq.tutorial.add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
549 \caption{Forcibly creating a patch} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
550 \label{ex:mq:add} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
551 \end{figure} |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
552 |
535e87792eb1
More MQ content and examples.
Bryan O'Sullivan <bos@serpentine.com>
parents:
26
diff
changeset
|
553 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
|
554 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
|
555 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
|
556 \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
|
557 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
|
558 \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
|
559 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
|
560 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
|
561 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
562 %\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
|
563 \subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} |
13 | 564 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
565 The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} |
13 | 566 applied patch. This means that you can suspend work on one patch (by |
567 refreshing it), pop or push to make a different patch the top, and | |
568 work on \emph{that} patch for a while. | |
569 | |
570 Here's an example that illustrates how you can use this ability. | |
571 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
|
572 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
|
573 top of the first---changes the user interface to use the code you just |
13 | 574 added to the core. If you notice a bug in the core while you're |
575 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
|
576 \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
|
577 \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
|
578 \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI |
13 | 579 patch to continue where you left off. |
580 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
581 %\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
|
582 \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
|
583 \label{sec:mq:adv-patch} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
584 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
585 MQ uses the GNU \command{patch} command to apply patches, so it's |
26 | 586 helpful to know a few more detailed aspects of how \command{patch} |
587 works, and about patches themselves. | |
588 | |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
589 %\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
|
590 \subsection{$B%9%H%j%C%W%+%&%s%H(B} |
26 | 591 |
592 If you look at the file headers in a patch, you will notice that the | |
593 pathnames usually have an extra component on the front that isn't | |
594 present in the actual path name. This is a holdover from the way that | |
595 people used to generate patches (people still do this, but it's | |
596 somewhat rare with modern revision control tools). | |
597 | |
598 Alice would unpack a tarball, edit her files, then decide that she | |
599 wanted to create a patch. So she'd rename her working directory, | |
600 unpack the tarball again (hence the need for the rename), and use the | |
601 \cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to | |
602 recursively generate a patch between the unmodified directory and the | |
603 modified one. The result would be that the name of the unmodified | |
604 directory would be at the front of the left-hand path in every file | |
605 header, and the name of the modified directory would be at the front | |
606 of the right-hand path. | |
607 | |
608 Since someone receiving a patch from the Alices of the net would be | |
609 unlikely to have unmodified and modified directories with exactly the | |
610 same names, the \command{patch} command has a \cmdopt{patch}{-p} | |
611 option that indicates the number of leading path name components to | |
612 strip when trying to apply a patch. This number is called the | |
613 \emph{strip count}. | |
614 | |
615 An option of ``\texttt{-p1}'' means ``use a strip count of one''. If | |
616 \command{patch} sees a file name \filename{foo/bar/baz} in a file | |
617 header, it will strip \filename{foo} and try to patch a file named | |
618 \filename{bar/baz}. (Strictly speaking, the strip count refers to the | |
619 number of \emph{path separators} (and the components that go with them | |
620 ) to strip. A strip count of one will turn \filename{foo/bar} into | |
621 \filename{bar}, but \filename{/foo/bar} (notice the extra leading | |
622 slash) into \filename{foo/bar}.) | |
623 | |
624 The ``standard'' strip count for patches is one; almost all patches | |
625 contain one leading path name component that needs to be stripped. | |
626 Mercurial's \hgcmd{diff} command generates path names in this form, | |
627 and the \hgcmd{import} command and MQ expect patches to have a strip | |
628 count of one. | |
629 | |
630 If you receive a patch from someone that you want to add to your patch | |
631 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
|
632 just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet |
26 | 633 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
|
634 \hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}} |
26 | 635 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
|
636 files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. |
26 | 637 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
|
638 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
639 %\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
|
640 \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
|
641 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
642 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
|
643 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
|
644 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
|
645 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
|
646 against a newer version of that file. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
647 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
648 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
|
649 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
|
650 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
|
651 context, without honouring the line numbering information. If this |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
652 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
|
653 but at some \emph{offset} from the original line number. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
654 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
655 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
|
656 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
|
657 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
|
658 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
|
659 after the fuzz factor indicates how many lines of context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
660 \command{patch} had to trim before the patch applied). |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
661 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
662 When neither of these techniques works, \command{patch} prints a |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
663 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
|
664 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
|
665 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
|
666 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
|
667 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
|
668 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
|
669 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
|
670 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
|
671 \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
|
672 the changes made by the five successful five hunks. |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
673 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
674 %\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
|
675 \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
|
676 |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
677 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
|
678 with files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
679 \begin{itemize} |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
680 \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
|
681 handle binary files. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
682 \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
|
683 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
|
684 \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
|
685 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
|
686 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
|
687 deleted'' in a patch. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
688 \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
|
689 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
|
690 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
|
691 \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
|
692 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
|
693 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
|
694 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
|
695 \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
|
696 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
|
697 tree''. |
9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Bryan O'Sullivan <bos@serpentine.com>
parents:
19
diff
changeset
|
698 \end{itemize} |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
699 |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
700 %\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
|
701 \subsection{$B[#Kf$JE@$K$D$$$F(B} |
14
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
702 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
703 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
|
704 be completely successful, these inexact techniques naturally leave |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
705 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
|
706 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
|
707 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
|
708 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
|
709 modified files are correct afterwards. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
710 |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
711 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
|
712 offset or fuzz factor; refreshing the patch generates new context |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
713 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
|
714 ``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
|
715 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
|
716 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
|
717 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
|
718 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
|
719 patching process in such cases. |
e2aa527bafa0
Describe unified diffs
Bryan O'Sullivan <bos@serpentine.com>
parents:
13
diff
changeset
|
720 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
721 %\subsection{Handling rejection} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
722 \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
|
723 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
724 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
|
725 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
|
726 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
|
727 or do any further work. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
728 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
729 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
|
730 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
|
731 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
|
732 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
733 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
|
734 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
|
735 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
|
736 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
737 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
|
738 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
|
739 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
|
740 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
741 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
|
742 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
|
743 \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
|
744 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
|
745 \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
|
746 may be rejected: |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
747 |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
748 \begin{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
749 \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
|
750 \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
|
751 \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
|
752 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
|
753 \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
|
754 currently present in the file. |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
755 \end{itemize} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
756 |
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
|
757 If you use \command{wiggle} or \command{mpatch}, you should be doubly |
55 | 758 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
|
759 \command{mpatch} enforces this method of double-checking the tool's |
55 | 760 output, by automatically dropping you into a merge program when it has |
761 done its job, so that you can verify its work and finish off any | |
762 remaining merges. | |
15
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
763 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
764 %\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
|
765 \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
|
766 \label{sec:mq:perf} |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
767 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
768 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
|
769 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
|
770 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
|
771 set the Linux 2.6.17-mm1 patch series, which consists of 1,738 |
66 | 772 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
|
773 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
|
774 2.6.17. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
775 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
776 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
|
777 \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
|
778 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
|
779 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
|
780 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
|
781 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
|
782 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
783 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
|
784 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
|
785 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
786 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
|
787 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
|
788 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
|
789 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
|
790 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
|
791 (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
|
792 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
793 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
|
794 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
|
795 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
|
796 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
|
797 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
|
798 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
|
799 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
800 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
|
801 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
|
802 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
|
803 is one, and so on. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
804 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
805 %\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
|
806 \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
|
807 \label{sec:mq:merge} |
b8ac9f312a47
Document wiggle and rej
Bryan O'Sullivan <bos@serpentine.com>
parents:
14
diff
changeset
|
808 |
17
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
809 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
|
810 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
|
811 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
|
812 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
|
813 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
|
814 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
|
815 patch series. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
816 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
817 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
|
818 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
|
819 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
|
820 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
|
821 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
|
822 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
|
823 until you have fixed your entire stack. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
824 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
825 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
|
826 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
|
827 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
|
828 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
|
829 hunks by hand quickly becomes tiresome. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
830 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
831 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
|
832 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
|
833 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
|
834 patches and a different revision. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
835 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
836 The process is a little involved. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
837 \begin{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
838 \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
|
839 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
|
840 \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
|
841 \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
|
842 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
|
843 save the patches to a directory called |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
844 \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
|
845 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
|
846 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
|
847 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
|
848 \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
|
849 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
|
850 \item Update to the new tip revision, using |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
851 \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
|
852 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
|
853 \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
|
854 \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
|
855 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
|
856 \end{enumerate} |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
857 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
858 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
|
859 \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
|
860 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
|
861 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
|
862 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
|
863 merge tool to help you to resolve problems. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
864 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
865 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
|
866 patch based on the result of the merge. |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
867 |
2668e15c76e9
MQ: write up patch rebasing.
Bryan O'Sullivan <bos@serpentine.com>
parents:
16
diff
changeset
|
868 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
|
869 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
|
870 \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
|
871 \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
|
872 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
|
873 you are sure that you no longer need it as a backup. |
13 | 874 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
875 %\section{Identifying patches} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
876 \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
|
877 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
878 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
|
879 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
|
880 name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will |
55 | 881 push patches until \filename{foo.patch} is applied. |
882 | |
883 As a shortcut, you can refer to a patch using both a name and a | |
884 numeric offset; \texttt{foo.patch-2} means ``two patches before | |
885 \texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches | |
886 after \texttt{bar.patch}''. | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
887 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
888 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
|
889 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
|
890 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
|
891 so on |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
892 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
893 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
|
894 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
|
895 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
|
896 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
|
897 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
|
898 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
|
899 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
|
900 topmost applied patches, respectively. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
901 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
902 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
|
903 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
|
904 \begin{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
905 \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
|
906 changes? |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
907 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
908 hg email qbase:qtip |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
909 \end{codesample4} |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
910 (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
|
911 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
|
912 \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
|
913 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
|
914 \begin{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
915 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
|
916 \end{codesample4} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
917 \end{itemize} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
918 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
919 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
|
920 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
|
921 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
|
922 name. |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
923 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
924 \begin{figure}[ht] |
155
914babdc99c8
run-example: better error if bogus section name found.
Bryan O'Sullivan <bos@serpentine.com>
parents:
106
diff
changeset
|
925 \interaction{mq.id.output} |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
926 \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
|
927 \label{ex:mq:id} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
928 \end{figure} |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
929 |
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
930 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
|
931 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
|
932 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
|
933 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
|
934 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
|
935 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
|
936 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
937 %\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
|
938 \section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} |
26 | 939 |
940 There are a number of aspects of MQ usage that don't fit tidily into | |
941 sections of their own, but that are good to know. Here they are, in | |
942 one place. | |
943 | |
944 \begin{itemize} | |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
945 \item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it |
26 | 946 again, the changeset that represents the patch after the pop/push |
947 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
|
948 represented the hash beforehand. See |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
155
diff
changeset
|
949 section~\ref{sec:mqref:cmd:qpush} for information as to why this is. |
26 | 950 \item It's not a good idea to \hgcmd{merge} changes from another |
951 branch with a patch changeset, at least if you want to maintain the | |
952 ``patchiness'' of that changeset and changesets below it on the | |
953 patch stack. If you try to do this, it will appear to succeed, but | |
954 MQ will become confused. | |
955 \end{itemize} | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
956 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
957 %\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
|
958 \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
|
959 \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
|
960 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
961 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
|
962 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
|
963 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
|
964 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
965 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
|
966 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
|
967 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
|
968 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
|
969 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
|
970 later on. |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
971 |
26 | 972 You can then share different versions of the same patch stack among |
973 multiple underlying repositories. I use this when I am developing a | |
974 Linux kernel feature. I have a pristine copy of my kernel sources for | |
975 each of several CPU architectures, and a cloned repository under each | |
976 that contains the patches I am working on. When I want to test a | |
977 change on a different architecture, I push my current patches to the | |
978 patch repository associated with that kernel tree, pop and push all of | |
979 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
|
980 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
981 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
|
982 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
|
983 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
|
984 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
|
985 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
986 %\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
|
987 \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
|
988 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
989 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
|
990 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
|
991 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
|
992 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
|
993 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
994 \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
|
995 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
|
996 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
|
997 \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
|
998 \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
|
999 |
234
30e97616d808
Tag all MQ command options as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
233
diff
changeset
|
1000 (\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
|
1001 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
|
1002 \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
|
1003 \end{note} |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1004 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1005 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
|
1006 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
|
1007 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
|
1008 |
283
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1009 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
|
1010 \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
|
1011 some bothersome typing. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1012 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1013 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
|
1014 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
|
1015 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
|
1016 snippet in your \tildefile{.bashrc}. |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1017 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1018 \begin{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1019 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
|
1020 \end{codesample2} |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1021 |
4ed483f08e33
Mention how to define mq alias.
Faheem Mitha <faheem@email.unc.edu>
parents:
282
diff
changeset
|
1022 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
|
1023 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
|
1024 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1025 %\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
|
1026 \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
|
1027 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1028 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
|
1029 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
|
1030 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1031 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
|
1032 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
|
1033 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
|
1034 \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
|
1035 \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
|
1036 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
|
1037 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
|
1038 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1039 %\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
|
1040 \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
|
1041 \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
|
1042 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1043 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
|
1044 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
|
1045 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
|
1046 |
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1047 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
|
1048 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
|
1049 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
|
1050 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
|
1051 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
|
1052 \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
|
1053 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
|
1054 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
|
1055 |
19
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1056 \begin{figure}[ht] |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1057 \interaction{mq.tools.tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1058 \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
|
1059 \label{ex:mq:tools} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1060 \end{figure} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1061 |
16
81454425eee9
Progress on a few fronts, mainly indexing and MQ chapter content
Bryan O'Sullivan <bos@serpentine.com>
parents:
15
diff
changeset
|
1062 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
|
1063 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
|
1064 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
|
1065 \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
|
1066 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
|
1067 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
|
1068 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
|
1069 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
|
1070 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
|
1071 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1072 %\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
|
1073 \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
|
1074 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1075 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
|
1076 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
|
1077 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
|
1078 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
|
1079 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1080 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
|
1081 \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
|
1082 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
|
1083 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
|
1084 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
|
1085 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
|
1086 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
|
1087 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
|
1088 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1089 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
|
1090 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
|
1091 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
|
1092 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
|
1093 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
|
1094 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
|
1095 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1096 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
|
1097 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
|
1098 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
|
1099 \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
|
1100 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
|
1101 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
|
1102 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1103 %\section{MQ cookbook} |
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1104 \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
|
1105 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1106 %\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
|
1107 \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
|
1108 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1109 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
|
1110 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
|
1111 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
|
1112 downloaded. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1113 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1114 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
|
1115 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
|
1116 \interaction{mq.tarball.download} |
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 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
|
1119 \interaction{mq.tarball.qinit} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1120 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1121 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
|
1122 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
|
1123 \interaction{mq.tarball.newsource} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1124 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
|
1125 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
|
1126 \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
|
1127 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
|
1128 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1129 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
|
1130 \interaction{mq.tarball.repush} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1131 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1132 %\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
|
1133 \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
|
1134 \label{sec:mq:combine} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1135 |
233
696b1e0c01df
Tag all MQ commands as belonging to the mq extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
1136 MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire |
55 | 1137 patches. This ``folds'' the patches you name, in the order you name |
1138 them, into the topmost applied patch, and concatenates their | |
1139 descriptions onto the end of its description. The patches that you | |
1140 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
|
1141 |
55 | 1142 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
|
1143 patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and |
55 | 1144 \texttt{quux} into it, you will end up with a patch that has the same |
1145 effect as if you applied first \texttt{foo}, then \texttt{bar}, | |
1146 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
|
1147 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1148 %\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
|
1149 \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
|
1150 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1151 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
|
1152 combining entire patches. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1153 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1154 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
|
1155 \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
|
1156 \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
|
1157 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
|
1158 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
|
1159 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
|
1160 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
|
1161 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
|
1162 the duplicate hunks. |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1163 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1164 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
|
1165 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
|
1166 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
|
1167 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
|
1168 \interaction{mq.tools.lsdiff} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1169 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1170 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
|
1171 \begin{itemize} |
26 | 1172 \item (in the first column) a \emph{file number} to identify each file |
1173 modified in the patch; | |
1174 \item (on the next line, indented) the line number within a modified | |
1175 file where a hunk starts; and | |
1176 \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
|
1177 \end{itemize} |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1178 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1179 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
|
1180 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
|
1181 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
|
1182 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
|
1183 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
|
1184 |
187702df428b
Piles of new content for MQ chapter - cookbook stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
18
diff
changeset
|
1185 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
|
1186 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
|
1187 section~\ref{sec:mq:combine}. |
26 | 1188 |
322
4301500fca37
started mq.tex. it's a quite massive chank.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1189 %\section{Differences between quilt and MQ} |
325 | 1190 \section{quilt$B$H(BMQ$B$N0c$$(B} |
26 | 1191 |
325 | 1192 %If you are already familiar with quilt, MQ provides a similar command |
1193 %set. There are a few differences in the way that it works. | |
1194 | |
1195 $B$9$G$K(Bquilt$B$KFk@w$s$G$$$k%f!<%6$N$?$a$K!$(BMQ$B$OF1MM$N%3%^%s%I%;%C%H$rMQ0U(B | |
1196 $B$7$F$$$k!%%3%^%s%I$N5sF0$K$O2?E@$+0c$$$,$"$k!%(B | |
26 | 1197 |
325 | 1198 %You will already have noticed that most quilt commands have MQ |
1199 %counterparts that simply begin with a ``\texttt{q}''. The exceptions | |
1200 %are quilt's \texttt{add} and \texttt{remove} commands, the | |
1201 %counterparts for which are the normal Mercurial \hgcmd{add} and | |
1202 %\hgcmd{remove} commands. There is no MQ equivalent of the quilt | |
1203 %\texttt{edit} command. | |
1204 | |
1205 $B$9$G$K$[$H$s$I$N(Bquilt$B%3%^%s%I$K$O!$BP1~$9$k(B``\texttt{q}''$B$G;O$^$k(BMQ$B%3%^%s(B | |
1206 $B%I$,$"$k$3$H$K5$$E$$$F$$$k$3$H$H;W$&!%Nc30$O!$(Bquilt$B$N(B\texttt{add}$B%3%^%s%I(B | |
1207 $B$H(B\texttt{remove}$B%3%^%s%I$G!$$3$l$i$K$O$=$l$>$lDL>o$N(BMercurial$B%3%^%s%I$N(B | |
1208 \hgcmd{add}$B$H(B\hgcmd{remove}$B$,BP1~$9$k!%$^$?!$(Bquilt$B$N(B\texttt{edit}$B%3%^%s%I(B | |
1209 $B$KBP1~$9$k(BMQ$B%3%^%s%I$O$J$$!%(B | |
1210 | |
50
8b0d389cf6e0
Update MQ chapter to match recent bug fixes.
Bryan O'Sullivan <bos@serpentine.com>
parents:
46
diff
changeset
|
1211 |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1212 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
1213 %%% mode: yatex |
1
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1214 %%% TeX-master: "00book" |
04e469de601e
Early content for chapter on MQ.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1215 %%% End: |