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