hgbook
changeset 682:ef53d025f410
Mention qdelete and qimport -r.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Apr 23 22:24:02 2009 -0700 (2009-04-23) |
parents | 557552d4699f |
children | 1a0a78e197c3 |
files | en/ch09-hook.xml en/ch10-template.xml en/ch11-mq.xml en/examples/auto-snippets.xml en/examples/ch11/qdelete |
line diff
1.1 --- a/en/ch09-hook.xml Tue Apr 21 23:51:47 2009 -0700 1.2 +++ b/en/ch09-hook.xml Thu Apr 23 22:24:02 2009 -0700 1.3 @@ -147,8 +147,8 @@ 1.4 incoming</command>), remember that it is the other 1.5 repository's hooks you should be checking, not your own. 1.6 </para> 1.7 - 1.8 - </sect2> 1.9 + </sect2> 1.10 + 1.11 <sect2> 1.12 <title>Hooks do not propagate</title> 1.13 1.14 @@ -178,8 +178,8 @@ 1.15 filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 1.16 see. However, this too has its limits; see below. 1.17 </para> 1.18 - 1.19 - </sect2> 1.20 + </sect2> 1.21 + 1.22 <sect2> 1.23 <title>Hooks can be overridden</title> 1.24 1.25 @@ -193,8 +193,8 @@ 1.26 hooks, you should thus understand that your users can disable 1.27 or override those hooks. 1.28 </para> 1.29 - 1.30 - </sect2> 1.31 + </sect2> 1.32 + 1.33 <sect2> 1.34 <title>Ensuring that critical hooks are run</title> 1.35 1.36 @@ -232,116 +232,7 @@ 1.37 1.38 </sect2> 1.39 </sect1> 1.40 - <sect1> 1.41 - <title>Care with <literal>pretxn</literal> hooks in a 1.42 - shared-access repository</title> 1.43 - 1.44 - <para id="x_206">If you want to use hooks to do some automated work in a 1.45 - repository that a number of people have shared access to, you 1.46 - need to be careful in how you do this. 1.47 - </para> 1.48 - 1.49 - <para id="x_207">Mercurial only locks a repository when it is writing to the 1.50 - repository, and only the parts of Mercurial that write to the 1.51 - repository pay attention to locks. Write locks are necessary to 1.52 - prevent multiple simultaneous writers from scribbling on each 1.53 - other's work, corrupting the repository. 1.54 - </para> 1.55 - 1.56 - <para id="x_208">Because Mercurial is careful with the order in which it 1.57 - reads and writes data, it does not need to acquire a lock when 1.58 - it wants to read data from the repository. The parts of 1.59 - Mercurial that read from the repository never pay attention to 1.60 - locks. This lockless reading scheme greatly increases 1.61 - performance and concurrency. 1.62 - </para> 1.63 - 1.64 - <para id="x_209">With great performance comes a trade-off, though, one which 1.65 - has the potential to cause you trouble unless you're aware of 1.66 - it. To describe this requires a little detail about how 1.67 - Mercurial adds changesets to a repository and reads those 1.68 - changes. 1.69 - </para> 1.70 - 1.71 - <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it 1.72 - writes it straight into the destination file. It writes file 1.73 - data first, then manifest data (which contains pointers to the 1.74 - new file data), then changelog data (which contains pointers to 1.75 - the new manifest data). Before the first write to each file, it 1.76 - stores a record of where the end of the file was in its 1.77 - transaction log. If the transaction must be rolled back, 1.78 - Mercurial simply truncates each file back to the size it was 1.79 - before the transaction began. 1.80 - </para> 1.81 - 1.82 - <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads 1.83 - the changelog first, then everything else. Since a reader will 1.84 - only access parts of the manifest or file metadata that it can 1.85 - see in the changelog, it can never see partially written data. 1.86 - </para> 1.87 - 1.88 - <para id="x_20c">Some controlling hooks (<literal 1.89 - role="hook">pretxncommit</literal> and <literal 1.90 - role="hook">pretxnchangegroup</literal>) run when a 1.91 - transaction is almost complete. All of the metadata has been 1.92 - written, but Mercurial can still roll the transaction back and 1.93 - cause the newly-written data to disappear. 1.94 - </para> 1.95 - 1.96 - <para id="x_20d">If one of these hooks runs for long, it opens a window of 1.97 - time during which a reader can see the metadata for changesets 1.98 - that are not yet permanent, and should not be thought of as 1.99 - <quote>really there</quote>. The longer the hook runs, the 1.100 - longer that window is open. 1.101 - </para> 1.102 - 1.103 - <sect2> 1.104 - <title>The problem illustrated</title> 1.105 - 1.106 - <para id="x_20e">In principle, a good use for the <literal 1.107 - role="hook">pretxnchangegroup</literal> hook would be to 1.108 - automatically build and test incoming changes before they are 1.109 - accepted into a central repository. This could let you 1.110 - guarantee that nobody can push changes to this repository that 1.111 - <quote>break the build</quote>. But if a client can pull 1.112 - changes while they're being tested, the usefulness of the test 1.113 - is zero; an unsuspecting someone can pull untested changes, 1.114 - potentially breaking their build. 1.115 - </para> 1.116 - 1.117 - <para id="x_20f">The safest technological answer to this challenge is to 1.118 - set up such a <quote>gatekeeper</quote> repository as 1.119 - <emphasis>unidirectional</emphasis>. Let it take changes 1.120 - pushed in from the outside, but do not allow anyone to pull 1.121 - changes from it (use the <literal 1.122 - role="hook">preoutgoing</literal> hook to lock it down). 1.123 - Configure a <literal role="hook">changegroup</literal> hook so 1.124 - that if a build or test succeeds, the hook will push the new 1.125 - changes out to another repository that people 1.126 - <emphasis>can</emphasis> pull from. 1.127 - </para> 1.128 - 1.129 - <para id="x_210">In practice, putting a centralised bottleneck like this in 1.130 - place is not often a good idea, and transaction visibility has 1.131 - nothing to do with the problem. As the size of a 1.132 - project&emdash;and the time it takes to build and 1.133 - test&emdash;grows, you rapidly run into a wall with this 1.134 - <quote>try before you buy</quote> approach, where you have 1.135 - more changesets to test than time in which to deal with them. 1.136 - The inevitable result is frustration on the part of all 1.137 - involved. 1.138 - </para> 1.139 - 1.140 - <para id="x_211">An approach that scales better is to get people to build 1.141 - and test before they push, then run automated builds and tests 1.142 - centrally <emphasis>after</emphasis> a push, to be sure all is 1.143 - well. The advantage of this approach is that it does not 1.144 - impose a limit on the rate at which the repository can accept 1.145 - changes. 1.146 - </para> 1.147 - 1.148 - </sect2> 1.149 - </sect1> 1.150 + 1.151 <sect1 id="sec:hook:simple"> 1.152 <title>A short tutorial on using hooks</title> 1.153 1.154 @@ -509,8 +400,8 @@ 1.155 <literal>foo</literal>, while the environment variable for an 1.156 external hook will be named <literal>HG_FOO</literal>. 1.157 </para> 1.158 - 1.159 - </sect2> 1.160 + </sect2> 1.161 + 1.162 <sect2> 1.163 <title>Hook return values and activity control</title> 1.164 1.165 @@ -526,8 +417,8 @@ 1.166 zero/false means <quote>allow</quote>, while 1.167 non-zero/true/exception means <quote>deny</quote>. 1.168 </para> 1.169 - 1.170 - </sect2> 1.171 + </sect2> 1.172 + 1.173 <sect2> 1.174 <title>Writing an external hook</title> 1.175 1.176 @@ -555,8 +446,8 @@ 1.177 should not rely on environment variables being set to the 1.178 values you have in your environment when testing the hook. 1.179 </para> 1.180 - 1.181 - </sect2> 1.182 + </sect2> 1.183 + 1.184 <sect2> 1.185 <title>Telling Mercurial to use an in-process hook</title> 1.186 1.187 @@ -585,8 +476,8 @@ 1.188 for the callable object named <literal>myhook</literal>, and 1.189 calls it. 1.190 </para> 1.191 - 1.192 - </sect2> 1.193 + </sect2> 1.194 + 1.195 <sect2> 1.196 <title>Writing an in-process hook</title> 1.197 1.198 @@ -622,8 +513,8 @@ 1.199 </para> 1.200 1.201 &interaction.hook.msglen.go; 1.202 - 1.203 - </sect2> 1.204 + </sect2> 1.205 + 1.206 <sect2> 1.207 <title>Checking for trailing whitespace</title> 1.208 1.209 @@ -838,8 +729,8 @@ 1.210 forbidding pushes from specific users. 1.211 </para> 1.212 1.213 - </sect3> 1.214 - </sect2> 1.215 + </sect3> </sect2> 1.216 + 1.217 <sect2> 1.218 <title><literal 1.219 role="hg-ext">bugzilla</literal>&emdash;integration with 1.220 @@ -1144,8 +1035,8 @@ 1.221 a valid Bugzilla user name. 1.222 </para> 1.223 1.224 - </sect3> 1.225 - </sect2> 1.226 + </sect3> </sect2> 1.227 + 1.228 <sect2> 1.229 <title><literal role="hg-ext">notify</literal>&emdash;send email 1.230 notifications</title> 1.231 @@ -1344,8 +1235,8 @@ 1.232 APIs normally use. To convert a hash from hex to binary, use 1.233 the <literal>bin</literal> function. 1.234 </para> 1.235 - 1.236 - </sect2> 1.237 + </sect2> 1.238 + 1.239 <sect2> 1.240 <title>External hook execution</title> 1.241 1.242 @@ -1382,8 +1273,8 @@ 1.243 have succeeded. If it exits with a non-zero status, it is 1.244 considered to have failed. 1.245 </para> 1.246 - 1.247 - </sect2> 1.248 + </sect2> 1.249 + 1.250 <sect2> 1.251 <title>Finding out where changesets come from</title> 1.252 1.253 @@ -1425,8 +1316,8 @@ 1.254 being transferred to or from a bundle. 1.255 </para> 1.256 </listitem></itemizedlist> 1.257 - 1.258 </sect3> 1.259 + 1.260 <sect3 id="sec:hook:url"> 1.261 <title>Where changes are going&emdash;remote repository 1.262 URLs</title> 1.263 @@ -1462,7 +1353,6 @@ 1.264 discovered about the remote client. 1.265 </para> 1.266 </listitem></itemizedlist> 1.267 - 1.268 </sect3> 1.269 </sect2> 1.270 </sect1> 1.271 @@ -1520,8 +1410,8 @@ 1.272 role="hook">pretxnchangegroup</literal> (<xref 1.273 linkend="sec:hook:pretxnchangegroup"/>) 1.274 </para> 1.275 - 1.276 - </sect2> 1.277 + </sect2> 1.278 + 1.279 <sect2 id="sec:hook:commit"> 1.280 <title><literal role="hook">commit</literal>&emdash;after a new 1.281 changeset is created</title> 1.282 @@ -1553,8 +1443,8 @@ 1.283 role="hook">pretxncommit</literal> (<xref 1.284 linkend="sec:hook:pretxncommit"/>) 1.285 </para> 1.286 - 1.287 - </sect2> 1.288 + </sect2> 1.289 + 1.290 <sect2 id="sec:hook:incoming"> 1.291 <title><literal role="hook">incoming</literal>&emdash;after one 1.292 remote changeset is added</title> 1.293 @@ -1599,8 +1489,8 @@ 1.294 role="hook">pretxnchangegroup</literal> (<xref 1.295 linkend="sec:hook:pretxnchangegroup"/>) 1.296 </para> 1.297 - 1.298 - </sect2> 1.299 + </sect2> 1.300 + 1.301 <sect2 id="sec:hook:outgoing"> 1.302 <title><literal role="hook">outgoing</literal>&emdash;after 1.303 changesets are propagated</title> 1.304 @@ -1646,8 +1536,8 @@ 1.305 role="hook">preoutgoing</literal> (<xref 1.306 linkend="sec:hook:preoutgoing"/>) 1.307 </para> 1.308 - 1.309 - </sect2> 1.310 + </sect2> 1.311 + 1.312 <sect2 id="sec:hook:prechangegroup"> 1.313 <title><literal 1.314 role="hook">prechangegroup</literal>&emdash;before starting 1.315 @@ -1692,8 +1582,8 @@ 1.316 role="hook">pretxnchangegroup</literal> (<xref 1.317 linkend="sec:hook:pretxnchangegroup"/>) 1.318 </para> 1.319 - 1.320 - </sect2> 1.321 + </sect2> 1.322 + 1.323 <sect2 id="sec:hook:precommit"> 1.324 <title><literal role="hook">precommit</literal>&emdash;before 1.325 starting to commit a changeset</title> 1.326 @@ -1732,8 +1622,8 @@ 1.327 role="hook">pretxncommit</literal> (<xref 1.328 linkend="sec:hook:pretxncommit"/>) 1.329 </para> 1.330 - 1.331 - </sect2> 1.332 + </sect2> 1.333 + 1.334 <sect2 id="sec:hook:preoutgoing"> 1.335 <title><literal role="hook">preoutgoing</literal>&emdash;before 1.336 starting to propagate changesets</title> 1.337 @@ -1769,8 +1659,8 @@ 1.338 role="hook">outgoing</literal> (<xref 1.339 linkend="sec:hook:outgoing"/>) 1.340 </para> 1.341 - 1.342 - </sect2> 1.343 + </sect2> 1.344 + 1.345 <sect2 id="sec:hook:pretag"> 1.346 <title><literal role="hook">pretag</literal>&emdash;before 1.347 tagging a changeset</title> 1.348 @@ -1811,6 +1701,7 @@ 1.349 (<xref linkend="sec:hook:tag"/>) 1.350 </para> 1.351 </sect2> 1.352 + 1.353 <sect2 id="sec:hook:pretxnchangegroup"> 1.354 <title><literal 1.355 role="hook">pretxnchangegroup</literal>&emdash;before 1.356 @@ -1875,8 +1766,8 @@ 1.357 role="hook">prechangegroup</literal> (<xref 1.358 linkend="sec:hook:prechangegroup"/>) 1.359 </para> 1.360 - 1.361 - </sect2> 1.362 + </sect2> 1.363 + 1.364 <sect2 id="sec:hook:pretxncommit"> 1.365 <title><literal role="hook">pretxncommit</literal>&emdash;before 1.366 completing commit of new changeset</title> 1.367 @@ -1901,8 +1792,8 @@ 1.368 race conditions if you do not take steps to avoid them. 1.369 </para> 1.370 1.371 - <para id="x_2d2">Parameters to this hook: 1.372 - </para> 1.373 + <para id="x_2d2">Parameters to this hook:</para> 1.374 + 1.375 <itemizedlist> 1.376 <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 1.377 changeset ID of the newly committed changeset. 1.378 @@ -1923,8 +1814,8 @@ 1.379 role="hook">precommit</literal> (<xref 1.380 linkend="sec:hook:precommit"/>) 1.381 </para> 1.382 - 1.383 - </sect2> 1.384 + </sect2> 1.385 + 1.386 <sect2 id="sec:hook:preupdate"> 1.387 <title><literal role="hook">preupdate</literal>&emdash;before 1.388 updating or merging working directory</title> 1.389 @@ -1955,8 +1846,8 @@ 1.390 1.391 <para id="x_2db">See also: <literal role="hook">update</literal> 1.392 (<xref linkend="sec:hook:update"/>)</para> 1.393 - 1.394 - </sect2> 1.395 + </sect2> 1.396 + 1.397 <sect2 id="sec:hook:tag"> 1.398 <title><literal role="hook">tag</literal>&emdash;after tagging a 1.399 changeset</title> 1.400 @@ -1992,8 +1883,8 @@ 1.401 <para id="x_2e2">See also: <literal role="hook">pretag</literal> 1.402 (<xref linkend="sec:hook:pretag"/>) 1.403 </para> 1.404 - 1.405 - </sect2> 1.406 + </sect2> 1.407 + 1.408 <sect2 id="sec:hook:update"> 1.409 <title><literal role="hook">update</literal>&emdash;after 1.410 updating or merging working directory</title>
2.1 --- a/en/ch10-template.xml Tue Apr 21 23:51:47 2009 -0700 2.2 +++ b/en/ch10-template.xml Thu Apr 23 22:24:02 2009 -0700 2.3 @@ -56,9 +56,9 @@ 2.4 file into a location where Mercurial can find it (typically 2.5 the <literal>templates</literal> subdirectory of your 2.6 Mercurial install directory).</para> 2.7 - 2.8 </sect2> 2.9 </sect1> 2.10 + 2.11 <sect1> 2.12 <title>Commands that support styles and templates</title> 2.13 2.14 @@ -125,8 +125,8 @@ 2.15 braces and text with the expansion of whatever is inside. To 2.16 print a literal curly brace, you must escape it, as described in 2.17 <xref linkend="sec:template:escape"/>.</para> 2.18 - 2.19 - </sect1> 2.20 + </sect1> 2.21 + 2.22 <sect1 id="sec:template:keyword"> 2.23 <title>Common template keywords</title> 2.24 2.25 @@ -199,8 +199,8 @@ 2.26 in <xref linkend="sec:template:filter"/>.</para> 2.27 2.28 &interaction.template.simple.datekeyword; 2.29 - 2.30 - </sect1> 2.31 + </sect1> 2.32 + 2.33 <sect1 id="sec:template:escape"> 2.34 <title>Escape sequences</title> 2.35 2.36 @@ -241,8 +241,8 @@ 2.37 <quote><literal>{</literal></quote>, or 2.38 <quote><literal>{</literal></quote> character, you must escape 2.39 it.</para> 2.40 - 2.41 - </sect1> 2.42 + </sect1> 2.43 + 2.44 <sect1 id="sec:template:filter"> 2.45 <title>Filtering keywords to change their results</title> 2.46 2.47 @@ -410,7 +410,7 @@ 2.48 <quote><literal>bos</literal></quote>.</para> 2.49 </listitem></itemizedlist> 2.50 2.51 -&interaction.template.simple.manyfilters; 2.52 + &interaction.template.simple.manyfilters; 2.53 2.54 <note> 2.55 <para id="x_5b7"> If you try to apply a filter to a piece of data that it 2.56 @@ -445,10 +445,9 @@ 2.57 on. For example, using <literal>fill68|tabindent</literal> 2.58 gives very different results from 2.59 <literal>tabindent|fill68</literal>.</para> 2.60 - 2.61 - 2.62 </sect2> 2.63 </sect1> 2.64 + 2.65 <sect1> 2.66 <title>From templates to styles</title> 2.67 2.68 @@ -513,9 +512,9 @@ 2.69 treated as the name of a file; the contents of this file 2.70 will be read and used as a template body.</para> 2.71 </listitem></itemizedlist> 2.72 - 2.73 </sect2> 2.74 </sect1> 2.75 + 2.76 <sect1> 2.77 <title>Style files by example</title> 2.78 2.79 @@ -566,8 +565,8 @@ 2.80 is almost always trivial to visually inspect the offending 2.81 line in the style file and see what is wrong.</para> 2.82 </listitem></itemizedlist> 2.83 - 2.84 </sect2> 2.85 + 2.86 <sect2> 2.87 <title>Uniquely identifying a repository</title> 2.88 2.89 @@ -602,8 +601,8 @@ 2.90 or other activity, so that you can <quote>replay</quote> 2.91 the build later if necessary.</para> 2.92 </listitem></itemizedlist> 2.93 - 2.94 </sect2> 2.95 + 2.96 <sect2> 2.97 <title>Mimicking Subversion's output</title> 2.98 2.99 @@ -661,7 +660,6 @@ 2.100 file points to. If the style file will look too big or 2.101 cluttered if you insert a literal piece of text, drop it into 2.102 a template instead.</para> 2.103 - 2.104 </sect2> 2.105 </sect1> 2.106 </chapter>
3.1 --- a/en/ch11-mq.xml Tue Apr 21 23:51:47 2009 -0700 3.2 +++ b/en/ch11-mq.xml Thu Apr 23 22:24:02 2009 -0700 3.3 @@ -118,8 +118,8 @@ 3.4 <para id="x_3b9">Quilt knows nothing about revision control tools, so it 3.5 works equally well on top of an unpacked tarball or a 3.6 Subversion working copy.</para> 3.7 - 3.8 - </sect2> 3.9 + </sect2> 3.10 + 3.11 <sect2 id="sec:mq:quilt-mq"> 3.12 <title>From patchwork quilt to Mercurial Queues</title> 3.13 3.14 @@ -181,8 +181,8 @@ 3.15 role="hg-cmd">hg annotate</command> command to see which 3.16 changeset or patch modified a particular line of a source file. 3.17 And so on.</para> 3.18 - 3.19 - </sect1> 3.20 + </sect1> 3.21 + 3.22 <sect1 id="sec:mq:patch"> 3.23 <title>Understanding patches</title> 3.24 3.25 @@ -244,8 +244,8 @@ 3.26 later (in <xref linkend="sec:mq:adv-patch"/>), but you 3.27 should have 3.28 enough information now to use MQ.</para> 3.29 - 3.30 - </sect1> 3.31 + </sect1> 3.32 + 3.33 <sect1 id="sec:mq:start"> 3.34 <title>Getting started with Mercurial Queues</title> 3.35 3.36 @@ -265,14 +265,14 @@ 3.37 the <command role="hg-ext-mq">qinit</command> command is now 3.38 available.</para> 3.39 3.40 -&interaction.mq.qinit-help.help; 3.41 + &interaction.mq.qinit-help.help; 3.42 3.43 <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 3.44 repository, and its commands only operate within that 3.45 repository. To get started, simply prepare the repository using 3.46 the <command role="hg-ext-mq">qinit</command> command.</para> 3.47 3.48 -&interaction.mq.tutorial.qinit; 3.49 + &interaction.mq.tutorial.qinit; 3.50 3.51 <para id="x_3cd">This command creates an empty directory called <filename 3.52 role="special" class="directory">.hg/patches</filename>, where 3.53 @@ -292,7 +292,7 @@ 3.54 class="directory">.hg/patches</filename> directory, as you 3.55 can see below.</para> 3.56 3.57 -&interaction.mq.tutorial.qnew; 3.58 + &interaction.mq.tutorial.qnew; 3.59 3.60 <para id="x_3d0">Also newly present in the <filename role="special" 3.61 class="directory">.hg/patches</filename> directory are two 3.62 @@ -320,8 +320,8 @@ 3.63 normal Mercurial commands, such as <command role="hg-cmd">hg 3.64 diff</command> and <command role="hg-cmd">hg 3.65 annotate</command>, work exactly as they did before.</para> 3.66 - 3.67 - </sect2> 3.68 + </sect2> 3.69 + 3.70 <sect2> 3.71 <title>Refreshing a patch</title> 3.72 3.73 @@ -329,7 +329,7 @@ 3.74 use the <command role="hg-ext-mq">qrefresh</command> command 3.75 to update the patch you are working on.</para> 3.76 3.77 -&interaction.mq.tutorial.qrefresh; 3.78 + &interaction.mq.tutorial.qrefresh; 3.79 3.80 <para id="x_3d4">This command folds the changes you have made in the 3.81 working directory into your patch, and updates its 3.82 @@ -342,9 +342,9 @@ 3.83 doesn't work out, <command role="hg-cmd">hg revert</command> 3.84 your modifications back to the last time you refreshed.</para> 3.85 3.86 -&interaction.mq.tutorial.qrefresh2; 3.87 - 3.88 - </sect2> 3.89 + &interaction.mq.tutorial.qrefresh2; 3.90 + </sect2> 3.91 + 3.92 <sect2> 3.93 <title>Stacking and tracking patches</title> 3.94 3.95 @@ -354,7 +354,8 @@ 3.96 new patch. Mercurial will apply this patch on top of your 3.97 existing patch.</para> 3.98 3.99 -&interaction.mq.tutorial.qnew2; 3.100 + &interaction.mq.tutorial.qnew2; 3.101 + 3.102 <para id="x_3d7">Notice that the patch contains the changes in our prior 3.103 patch as part of its context (you can see this more clearly in 3.104 the output of <command role="hg-cmd">hg 3.105 @@ -367,7 +368,7 @@ 3.106 many commands that are easier to use when you are thinking 3.107 about patches, as illustrated below.</para> 3.108 3.109 -&interaction.mq.tutorial.qseries; 3.110 + &interaction.mq.tutorial.qseries; 3.111 3.112 <itemizedlist> 3.113 <listitem><para id="x_3d9">The <command 3.114 @@ -382,8 +383,8 @@ 3.115 repository, again from oldest to newest (most recently 3.116 applied).</para> 3.117 </listitem></itemizedlist> 3.118 - 3.119 - </sect2> 3.120 + </sect2> 3.121 + 3.122 <sect2> 3.123 <title>Manipulating the patch stack</title> 3.124 3.125 @@ -420,15 +421,16 @@ 3.126 directory. See below for examples of <command 3.127 role="hg-ext-mq">qpop</command> and <command 3.128 role="hg-ext-mq">qpush</command> in action.</para> 3.129 -&interaction.mq.tutorial.qpop; 3.130 + 3.131 + &interaction.mq.tutorial.qpop; 3.132 3.133 <para id="x_3df">Notice that once we have popped a patch or two patches, 3.134 the output of <command role="hg-ext-mq">qseries</command> 3.135 remains the same, while that of <command 3.136 role="hg-ext-mq">qapplied</command> has changed.</para> 3.137 3.138 - 3.139 - </sect2> 3.140 + </sect2> 3.141 + 3.142 <sect2> 3.143 <title>Pushing and popping many patches</title> 3.144 3.145 @@ -444,9 +446,9 @@ 3.146 patches. (For some more ways to push and pop many patches, 3.147 see <xref linkend="sec:mq:perf"/> below.)</para> 3.148 3.149 -&interaction.mq.tutorial.qpush-a; 3.150 - 3.151 - </sect2> 3.152 + &interaction.mq.tutorial.qpush-a; 3.153 + </sect2> 3.154 + 3.155 <sect2> 3.156 <title>Safety checks, and overriding them</title> 3.157 3.158 @@ -460,7 +462,7 @@ 3.159 case by the <command role="hg-cmd">hg add</command> of 3.160 <filename>file3</filename>.</para> 3.161 3.162 -&interaction.mq.tutorial.add; 3.163 + &interaction.mq.tutorial.add; 3.164 3.165 <para id="x_3e2">Commands that check the working directory all take an 3.166 <quote>I know what I'm doing</quote> option, which is always 3.167 @@ -474,8 +476,8 @@ 3.168 will revert modifications to any files affected by the patch 3.169 that it is popping. Be sure to read the documentation for a 3.170 command's <option>-f</option> option before you use it!</para> 3.171 - 3.172 - </sect2> 3.173 + </sect2> 3.174 + 3.175 <sect2> 3.176 <title>Working on several patches at once</title> 3.177 3.178 @@ -499,9 +501,9 @@ 3.179 the core bug, <command role="hg-ext-mq">qrefresh</command> the 3.180 core patch, and <command role="hg-ext-mq">qpush</command> back 3.181 to the UI patch to continue where you left off.</para> 3.182 - 3.183 - </sect2> 3.184 - </sect1> 3.185 + </sect2> 3.186 + </sect1> 3.187 + 3.188 <sect1 id="sec:mq:adv-patch"> 3.189 <title>More about patches</title> 3.190 3.191 @@ -580,6 +582,7 @@ 3.192 311</ulink> for details. 3.193 </para> 3.194 </sect2> 3.195 + 3.196 <sect2> 3.197 <title>Strategies for applying a patch</title> 3.198 3.199 @@ -623,8 +626,8 @@ 3.200 <filename>foo.orig</filename>, a <filename>foo.rej</filename> 3.201 containing one hunk, and <filename>foo</filename>, containing 3.202 the changes made by the five successful hunks.</para> 3.203 - 3.204 - </sect2> 3.205 + </sect2> 3.206 + 3.207 <sect2> 3.208 <title>Some quirks of patch representation</title> 3.209 3.210 @@ -663,6 +666,7 @@ 3.211 tree</quote>.</para> 3.212 </listitem></itemizedlist> 3.213 </sect2> 3.214 + 3.215 <sect2> 3.216 <title>Beware the fuzz</title> 3.217 3.218 @@ -686,8 +690,8 @@ 3.219 on top of multiple versions of a source tree, it's acceptable 3.220 to have a patch apply with some fuzz, provided you've verified 3.221 the results of the patching process in such cases.</para> 3.222 - 3.223 - </sect2> 3.224 + </sect2> 3.225 + 3.226 <sect2> 3.227 <title>Handling rejection</title> 3.228 3.229 @@ -707,15 +711,10 @@ 3.230 the <filename role="special">.rej</filename> file and edit the 3.231 target file, applying the rejected hunks by hand.</para> 3.232 3.233 - <para id="x_3fc">If you're feeling adventurous, Neil Brown, a Linux kernel 3.234 - hacker, wrote a tool called <command>wiggle</command> 3.235 - <citation>web:wiggle</citation>, which is more vigorous than 3.236 - <command>patch</command> in its attempts to make a patch 3.237 - apply.</para> 3.238 - 3.239 - <para id="x_3fd">Another Linux kernel hacker, Chris Mason (the author of 3.240 - Mercurial Queues), wrote a similar tool called 3.241 - <command>mpatch</command> <citation>web:mpatch</citation>, 3.242 + <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author 3.243 + of Mercurial Queues), wrote a tool called 3.244 + <command>mpatch</command> (<ulink 3.245 + url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 3.246 which takes a simple approach to automating the application of 3.247 hunks rejected by <command>patch</command>. The 3.248 <command>mpatch</command> command can help with four common 3.249 @@ -736,24 +735,67 @@ 3.250 content than those currently present in the file.</para> 3.251 </listitem></itemizedlist> 3.252 3.253 - <para id="x_402">If you use <command>wiggle</command> or 3.254 - <command>mpatch</command>, you should be doubly careful to 3.255 - check your results when you're done. In fact, 3.256 - <command>mpatch</command> enforces this method of 3.257 - double-checking the tool's output, by automatically dropping 3.258 - you into a merge program when it has done its job, so that you 3.259 - can verify its work and finish off any remaining 3.260 + <para id="x_402">If you use <command>mpatch</command>, you 3.261 + should be doubly careful to check your results when you're 3.262 + done. In fact, <command>mpatch</command> enforces this method 3.263 + of double-checking the tool's output, by automatically 3.264 + dropping you into a merge program when it has done its job, so 3.265 + that you can verify its work and finish off any remaining 3.266 merges.</para> 3.267 - 3.268 - </sect2> 3.269 - </sect1> 3.270 + </sect2> 3.271 + </sect1> 3.272 + 3.273 + <sect1> 3.274 + <title>More on patch management</title> 3.275 + 3.276 + <para>As you grow familiar with MQ, you will find yourself wanting 3.277 + to perform other kinds of patch management operations.</para> 3.278 + 3.279 + <sect2> 3.280 + <title>Deleting unwanted patches</title> 3.281 + 3.282 + <para>If you want to get rid of a patch, use the <command 3.283 + role="hg-ext-mq">hg qdelete</command> command to delete the 3.284 + patch file and remove its entry from the patch series. If you 3.285 + try to delete a patch that is still applied, <command 3.286 + role="hg-ext-mq">hg qdelete</command> will refuse.</para> 3.287 + 3.288 + &interaction.ch11-qdelete.go; 3.289 + </sect2> 3.290 + 3.291 + <sect2> 3.292 + <title>Converting to and from permanent revisions</title> 3.293 + 3.294 + <para>Once you're done working on a patch and want to turn it 3.295 + into a permanent changeset, use the <command 3.296 + role="hg-ext-mq">hg qdelete -r</command> command. Pass a 3.297 + revision to the <option>-r</option> option to identify the 3.298 + patch that you want to turn into a regular changeset; this 3.299 + patch must already be applied.</para> 3.300 + 3.301 + &interaction.ch11-qdelete.convert; 3.302 + 3.303 + <para>It is also possible to turn an existing changeset into a 3.304 + patch, by passing the <option>-r</option> option to <command 3.305 + role="hg-ext-mq">hg qimport</command>.</para> 3.306 + 3.307 + &interaction.ch11-qdelete.import; 3.308 + 3.309 + <para>Note that it only makes sense to convert a changeset into 3.310 + a patch if you have not propagated that changeset into any 3.311 + other repositories. The imported changeset's ID will change 3.312 + every time you refresh the patch, which will make Mercurial 3.313 + treat it as unrelated to the original changeset if you have 3.314 + pushed it somewhere else.</para> 3.315 + </sect2> 3.316 + </sect1> 3.317 + 3.318 <sect1 id="sec:mq:perf"> 3.319 <title>Getting the best performance out of MQ</title> 3.320 3.321 <para id="x_403">MQ is very efficient at handling a large number of patches. 3.322 I ran some performance experiments in mid-2006 for a talk that I 3.323 - gave at the 2006 EuroPython conference 3.324 - <citation>web:europython</citation>. I used as my data set the 3.325 + gave at the 2006 EuroPython conference. I used as my data set the 3.326 Linux 2.6.17-mm1 patch series, which consists of 1,738 patches. 3.327 I applied these on top of a Linux kernel repository containing 3.328 all 27,472 revisions between Linux 2.6.12-rc2 and Linux 3.329 @@ -799,8 +841,8 @@ 3.330 of the patch, or by number. If you use numeric addressing, 3.331 patches are counted from zero; this means that the first patch 3.332 is zero, the second is one, and so on.</para> 3.333 - 3.334 - </sect1> 3.335 + </sect1> 3.336 + 3.337 <sect1 id="sec:mq:merge"> 3.338 <title>Updating your patches when the underlying code 3.339 changes</title> 3.340 @@ -899,8 +941,8 @@ 3.341 strip</command>. You can delete <filename role="special" 3.342 class="directory">.hg/patches.N</filename> once you are sure 3.343 that you no longer need it as a backup.</para> 3.344 - 3.345 - </sect1> 3.346 + </sect1> 3.347 + 3.348 <sect1> 3.349 <title>Identifying patches</title> 3.350 3.351 @@ -963,9 +1005,9 @@ 3.352 few normal Mercurial commands in use with applied 3.353 patches.</para> 3.354 3.355 -&interaction.mq.id.output; 3.356 - 3.357 - </sect1> 3.358 + &interaction.mq.id.output; 3.359 + </sect1> 3.360 + 3.361 <sect1> 3.362 <title>Useful things to know about</title> 3.363 3.364 @@ -991,8 +1033,8 @@ 3.365 this, it will appear to succeed, but MQ will become 3.366 confused.</para> 3.367 </listitem></itemizedlist> 3.368 - 3.369 - </sect1> 3.370 + </sect1> 3.371 + 3.372 <sect1 id="sec:mq:repo"> 3.373 <title>Managing patches in a repository</title> 3.374 3.375 @@ -1077,8 +1119,8 @@ 3.376 3.377 <para id="x_42d">You can then issue commands of the form <command>mq 3.378 pull</command> from the main repository.</para> 3.379 - 3.380 - </sect2> 3.381 + </sect2> 3.382 + 3.383 <sect2> 3.384 <title>A few things to watch out for</title> 3.385 3.386 @@ -1216,8 +1258,8 @@ 3.387 tree.</para> 3.388 3.389 &interaction.mq.tarball.repush; 3.390 - 3.391 - </sect2> 3.392 + </sect2> 3.393 + 3.394 <sect2 id="sec:mq:combine"> 3.395 <title>Combining entire patches</title> 3.396 3.397 @@ -1237,8 +1279,8 @@ 3.398 you applied first <literal>foo</literal>, then 3.399 <literal>bar</literal>, followed by 3.400 <literal>quux</literal>.</para> 3.401 - 3.402 - </sect2> 3.403 + </sect2> 3.404 + 3.405 <sect2> 3.406 <title>Merging part of one patch into another</title> 3.407
4.1 --- a/en/examples/auto-snippets.xml Tue Apr 21 23:51:47 2009 -0700 4.2 +++ b/en/examples/auto-snippets.xml Thu Apr 23 22:24:02 2009 -0700 4.3 @@ -60,6 +60,9 @@ 4.4 <!ENTITY interaction.ch04-resolve.merge SYSTEM "results/ch04-resolve.merge.lxo"> 4.5 <!ENTITY interaction.ch04-resolve.pull SYSTEM "results/ch04-resolve.pull.lxo"> 4.6 <!ENTITY interaction.ch04-resolve.right SYSTEM "results/ch04-resolve.right.lxo"> 4.7 +<!ENTITY interaction.ch11-qdelete.convert SYSTEM "results/ch11-qdelete.convert.lxo"> 4.8 +<!ENTITY interaction.ch11-qdelete.go SYSTEM "results/ch11-qdelete.go.lxo"> 4.9 +<!ENTITY interaction.ch11-qdelete.import SYSTEM "results/ch11-qdelete.import.lxo"> 4.10 <!ENTITY interaction.cmdref.diff-p SYSTEM "results/cmdref.diff-p.lxo"> 4.11 <!ENTITY interaction.daily.copy.after SYSTEM "results/daily.copy.after.lxo"> 4.12 <!ENTITY interaction.daily.copy.cat SYSTEM "results/daily.copy.cat.lxo">
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/examples/ch11/qdelete Thu Apr 23 22:24:02 2009 -0700 5.3 @@ -0,0 +1,32 @@ 5.4 +#!/bin/bash 5.5 + 5.6 +echo '[extensions]' >> $HGRC 5.7 +echo 'hgext.mq =' >> $HGRC 5.8 + 5.9 +#$ name: go 5.10 + 5.11 +hg init myrepo 5.12 +cd myrepo 5.13 +hg qinit 5.14 +hg qnew bad.patch 5.15 +echo a > a 5.16 +hg add a 5.17 +hg qrefresh 5.18 +hg qdelete bad.patch 5.19 +hg qpop 5.20 +hg qdelete bad.patch 5.21 + 5.22 +#$ name: convert 5.23 + 5.24 +hg qnew good.patch 5.25 +echo a > a 5.26 +hg add a 5.27 +hg qrefresh -m 'Good change' 5.28 +hg qdelete -r tip 5.29 +hg qapplied 5.30 +hg tip --style=compact 5.31 + 5.32 +#$ name: import 5.33 + 5.34 +hg qimport -r tip 5.35 +hg qapplied