hgbook
changeset 584:c838b3975bc6
Add IDs to paragraphs.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Mar 19 21:18:52 2009 -0700 (2009-03-19) |
| parents | 28b5a5befb08 |
| children | 3b062018273a |
| files | en/appA-cmdref.xml en/appB-mq-ref.xml en/appC-srcinstall.xml en/appD-license.xml en/autoid.py en/ch00-preface.xml en/ch01-tour-basic.xml en/ch02-tour-merge.xml en/ch03-concepts.xml en/ch04-daily.xml en/ch05-collab.xml en/ch06-filenames.xml en/ch07-branch.xml en/ch08-undo.xml en/ch09-hook.xml en/ch10-template.xml en/ch11-mq.xml en/ch12-mq-collab.xml en/ch13-hgext.xml |
line diff
1.1 --- a/en/appA-cmdref.xml Thu Mar 19 20:54:12 2009 -0700 1.2 +++ b/en/appA-cmdref.xml Thu Mar 19 21:18:52 2009 -0700 1.3 @@ -3,113 +3,113 @@ 1.4 <appendix id="cmdref"> 1.5 <title>Command reference</title> 1.6 1.7 -<para>\cmdref{add}{add files at the next commit} 1.8 +<para id="x_653">\cmdref{add}{add files at the next commit} 1.9 \optref{add}{I}{include} 1.10 \optref{add}{X}{exclude} 1.11 \optref{add}{n}{dry-run}</para> 1.12 1.13 -<para>\cmdref{diff}{print changes in history or working directory}</para> 1.14 - 1.15 -<para>Show differences between revisions for the specified files or 1.16 +<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para> 1.17 + 1.18 +<para id="x_655">Show differences between revisions for the specified files or 1.19 directories, using the unified diff format. For a description of the 1.20 unified diff format, see section <xref linkend="sec:mq:patch"/>.</para> 1.21 1.22 -<para>By default, this command does not print diffs for files that Mercurial 1.23 +<para id="x_656">By default, this command does not print diffs for files that Mercurial 1.24 considers to contain binary data. To control this behaviour, see the 1.25 <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para> 1.26 1.27 <sect2> 1.28 <title>Options</title> 1.29 1.30 -<para>\loptref{diff}{nodates}</para> 1.31 - 1.32 -<para>Omit date and time information when printing diff headers.</para> 1.33 - 1.34 -<para>\optref{diff}{B}{ignore-blank-lines}</para> 1.35 - 1.36 -<para>Do not print changes that only insert or delete blank lines. A line 1.37 +<para id="x_657">\loptref{diff}{nodates}</para> 1.38 + 1.39 +<para id="x_658">Omit date and time information when printing diff headers.</para> 1.40 + 1.41 +<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para> 1.42 + 1.43 +<para id="x_65a">Do not print changes that only insert or delete blank lines. A line 1.44 that contains only whitespace is not considered blank. 1.45 </para> 1.46 1.47 -<para>\optref{diff}{I}{include} 1.48 -</para> 1.49 - 1.50 -<para>Include files and directories whose names match the given patterns. 1.51 -</para> 1.52 - 1.53 -<para>\optref{diff}{X}{exclude} 1.54 -</para> 1.55 - 1.56 -<para>Exclude files and directories whose names match the given patterns. 1.57 -</para> 1.58 - 1.59 -<para>\optref{diff}{a}{text} 1.60 -</para> 1.61 - 1.62 -<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print 1.63 +<para id="x_65b">\optref{diff}{I}{include} 1.64 +</para> 1.65 + 1.66 +<para id="x_65c">Include files and directories whose names match the given patterns. 1.67 +</para> 1.68 + 1.69 +<para id="x_65d">\optref{diff}{X}{exclude} 1.70 +</para> 1.71 + 1.72 +<para id="x_65e">Exclude files and directories whose names match the given patterns. 1.73 +</para> 1.74 + 1.75 +<para id="x_65f">\optref{diff}{a}{text} 1.76 +</para> 1.77 + 1.78 +<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print 1.79 diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option> 1.80 forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for 1.81 all of them. 1.82 </para> 1.83 1.84 -<para>This option is useful for files that are <quote>mostly text</quote> but have a 1.85 +<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a 1.86 few embedded NUL characters. If you use it on files that contain a 1.87 lot of binary data, its output will be incomprehensible. 1.88 </para> 1.89 1.90 -<para>\optref{diff}{b}{ignore-space-change} 1.91 -</para> 1.92 - 1.93 -<para>Do not print a line if the only change to that line is in the amount 1.94 +<para id="x_662">\optref{diff}{b}{ignore-space-change} 1.95 +</para> 1.96 + 1.97 +<para id="x_663">Do not print a line if the only change to that line is in the amount 1.98 of white space it contains. 1.99 </para> 1.100 1.101 -<para>\optref{diff}{g}{git} 1.102 -</para> 1.103 - 1.104 -<para>Print <command>git</command>-compatible diffs. XXX reference a format 1.105 +<para id="x_664">\optref{diff}{g}{git} 1.106 +</para> 1.107 + 1.108 +<para id="x_665">Print <command>git</command>-compatible diffs. XXX reference a format 1.109 description. 1.110 </para> 1.111 1.112 -<para>\optref{diff}{p}{show-function} 1.113 -</para> 1.114 - 1.115 -<para>Display the name of the enclosing function in a hunk header, using a 1.116 +<para id="x_666">\optref{diff}{p}{show-function} 1.117 +</para> 1.118 + 1.119 +<para id="x_667">Display the name of the enclosing function in a hunk header, using a 1.120 simple heuristic. This functionality is enabled by default, so the 1.121 <option role="hg-opt-diff">-p</option> option has no effect unless you change the value of 1.122 the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para> 1.123 1.124 <!-- &interaction.cmdref.diff-p; --> 1.125 1.126 -<para>\optref{diff}{r}{rev} 1.127 -</para> 1.128 - 1.129 -<para>Specify one or more revisions to compare. The <command role="hg-cmd">hg diff</command> command 1.130 +<para id="x_668">\optref{diff}{r}{rev} 1.131 +</para> 1.132 + 1.133 +<para id="x_669">Specify one or more revisions to compare. The <command role="hg-cmd">hg diff</command> command 1.134 accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to 1.135 compare. 1.136 </para> 1.137 1.138 <orderedlist> 1.139 -<listitem><para>Display the differences between the parent revision of the 1.140 +<listitem><para id="x_66a">Display the differences between the parent revision of the 1.141 working directory and the working directory. 1.142 </para> 1.143 </listitem> 1.144 -<listitem><para>Display the differences between the specified changeset and the 1.145 +<listitem><para id="x_66b">Display the differences between the specified changeset and the 1.146 working directory. 1.147 </para> 1.148 </listitem> 1.149 -<listitem><para>Display the differences between the two specified changesets. 1.150 +<listitem><para id="x_66c">Display the differences between the two specified changesets. 1.151 </para> 1.152 </listitem></orderedlist> 1.153 1.154 -<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option> 1.155 +<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option> 1.156 options or revision range notation. For example, the two revision 1.157 specifications below are equivalent. 1.158 </para> 1.159 <programlisting>hg diff -r 10 -r 20 1.160 hg diff -r10:20</programlisting> 1.161 1.162 -<para>When you provide two revisions, Mercurial treats the order of those 1.163 +<para id="x_66e">When you provide two revisions, Mercurial treats the order of those 1.164 revisions as significant. Thus, <command role="hg-cmd">hg diff -r10:20</command> will 1.165 produce a diff that will transform files from their contents as of 1.166 revision 10 to their contents as of revision 20, while 1.167 @@ -119,23 +119,23 @@ 1.168 diffing against the working directory. 1.169 </para> 1.170 1.171 -<para>\optref{diff}{w}{ignore-all-space} 1.172 -</para> 1.173 - 1.174 -<para>\cmdref{version}{print version and copyright information} 1.175 -</para> 1.176 - 1.177 -<para>This command displays the version of Mercurial you are running, and 1.178 +<para id="x_66f">\optref{diff}{w}{ignore-all-space} 1.179 +</para> 1.180 + 1.181 +<para id="x_670">\cmdref{version}{print version and copyright information} 1.182 +</para> 1.183 + 1.184 +<para id="x_671">This command displays the version of Mercurial you are running, and 1.185 its copyright license. There are four kinds of version string that 1.186 you may see. 1.187 </para> 1.188 <itemizedlist> 1.189 -<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was 1.190 +<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was 1.191 not built in a Mercurial repository, and cannot determine its own 1.192 version. 1.193 </para> 1.194 </listitem> 1.195 -<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a 1.196 +<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a 1.197 build of a revision of Mercurial that was identified by a specific 1.198 tag in the repository where it was built. (This doesn't necessarily 1.199 mean that you're running an official release; someone else could 1.200 @@ -143,11 +143,11 @@ 1.201 built Mercurial.) 1.202 </para> 1.203 </listitem> 1.204 -<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This 1.205 +<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This 1.206 is a build of the given revision of Mercurial. 1.207 </para> 1.208 </listitem> 1.209 -<listitem><para>A hexadecimal string followed by a date, such as 1.210 +<listitem><para id="x_675">A hexadecimal string followed by a date, such as 1.211 <quote><literal>875489e31abe+20070205</literal></quote>. This is a build of the given 1.212 revision of Mercurial, where the build repository contained some 1.213 local changes that had not been committed. 1.214 @@ -161,14 +161,14 @@ 1.215 <sect3 id="cmdref:diff-vs-status"> 1.216 <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title> 1.217 1.218 -<para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files 1.219 +<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files 1.220 that Mercurial will record changes for the next time you perform a 1.221 commit. If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it 1.222 prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command> 1.223 listed. There are two possible reasons for this. 1.224 </para> 1.225 1.226 -<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications 1.227 +<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications 1.228 that <command role="hg-cmd">hg diff</command> doesn't normally display. The <command role="hg-cmd">hg diff</command> command 1.229 normally outputs unified diffs, which don't have the ability to 1.230 represent some changes that Mercurial can track. Most notably, 1.231 @@ -176,12 +176,12 @@ 1.232 executable, but Mercurial records this information. 1.233 </para> 1.234 1.235 -<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will 1.236 +<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will 1.237 display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this 1.238 extra information. 1.239 </para> 1.240 1.241 -<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs 1.242 +<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs 1.243 for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you 1.244 invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the 1.245 first parent of the working directory. If you have run <command role="hg-cmd">hg merge</command> 1.246 @@ -199,14 +199,14 @@ 1.247 <sect3> 1.248 <title>Generating safe binary diffs</title> 1.249 1.250 -<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print 1.251 +<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print 1.252 diffs of files that are either <quote>mostly text</quote> or contain lots of 1.253 binary data, those diffs cannot subsequently be applied by either 1.254 Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command> 1.255 command. 1.256 </para> 1.257 1.258 -<para>If you want to generate a diff of a binary file that is safe to use as 1.259 +<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as 1.260 input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you 1.261 generate the patch. The system <command>patch</command> command cannot handle 1.262 binary patches at all.
2.1 --- a/en/appB-mq-ref.xml Thu Mar 19 20:54:12 2009 -0700 2.2 +++ b/en/appB-mq-ref.xml Thu Mar 19 21:18:52 2009 -0700 2.3 @@ -7,14 +7,14 @@ 2.4 <sect1 id="sec:mqref:cmdref"> 2.5 <title>MQ command reference</title> 2.6 2.7 - <para>For an overview of the commands provided by MQ, use the 2.8 + <para id="x_5e8">For an overview of the commands provided by MQ, use the 2.9 command <command role="hg-cmd">hg help mq</command>.</para> 2.10 2.11 <sect2> 2.12 <title><command role="hg-ext-mq">qapplied</command>&emdash;print 2.13 applied patches</title> 2.14 2.15 - <para>The <command role="hg-ext-mq">qapplied</command> command 2.16 + <para id="x_5e9">The <command role="hg-ext-mq">qapplied</command> command 2.17 prints the current stack of applied patches. Patches are 2.18 printed in oldest-to-newest order, so the last patch in the 2.19 list is the <quote>top</quote> patch.</para> 2.20 @@ -24,7 +24,7 @@ 2.21 <title><command role="hg-ext-mq">qcommit</command>&emdash;commit 2.22 changes in the queue repository</title> 2.23 2.24 - <para>The <command role="hg-ext-mq">qcommit</command> command 2.25 + <para id="x_5ea">The <command role="hg-ext-mq">qcommit</command> command 2.26 commits any outstanding changes in the <filename 2.27 role="special" class="directory">.hg/patches</filename> 2.28 repository. This command only works if the <filename 2.29 @@ -36,7 +36,7 @@ 2.30 after running <command 2.31 role="hg-ext-mq">qinit</command>.</para> 2.32 2.33 - <para>This command is shorthand for <command role="hg-cmd">hg 2.34 + <para id="x_5eb">This command is shorthand for <command role="hg-cmd">hg 2.35 commit --cwd .hg/patches</command>.</para> 2.36 </sect2> 2.37 <sect2> 2.38 @@ -45,7 +45,7 @@ 2.39 from the <filename role="special">series</filename> 2.40 file}</title> 2.41 2.42 - <para>The <command role="hg-ext-mq">qdelete</command> command 2.43 + <para id="x_5ec">The <command role="hg-ext-mq">qdelete</command> command 2.44 removes the entry for a patch from the <filename 2.45 role="special">series</filename> file in the <filename 2.46 role="special" class="directory">.hg/patches</filename> 2.47 @@ -54,9 +54,9 @@ 2.48 the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option 2.49 to do that.</para> 2.50 2.51 - <para>Options:</para> 2.52 - <itemizedlist> 2.53 - <listitem><para><option 2.54 + <para id="x_5ed">Options:</para> 2.55 + <itemizedlist> 2.56 + <listitem><para id="x_5ee"><option 2.57 role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the 2.58 patch file.</para> 2.59 </listitem></itemizedlist> 2.60 @@ -66,7 +66,7 @@ 2.61 <title><command role="hg-ext-mq">qdiff</command>&emdash;print a 2.62 diff of the topmost applied patch</title> 2.63 2.64 - <para>The <command role="hg-ext-mq">qdiff</command> command 2.65 + <para id="x_5ef">The <command role="hg-ext-mq">qdiff</command> command 2.66 prints a diff of the topmost applied patch. It is equivalent 2.67 to <command role="hg-cmd">hg diff -r-2:-1</command>.</para> 2.68 2.69 @@ -75,12 +75,12 @@ 2.70 <title><command role="hg-ext-mq">qfold</command>&emdash;merge 2.71 (<quote>fold</quote>) several patches into one</title> 2.72 2.73 - <para>The <command role="hg-ext-mq">qfold</command> command 2.74 + <para id="x_5f0">The <command role="hg-ext-mq">qfold</command> command 2.75 merges multiple patches into the topmost applied patch, so 2.76 that the topmost applied patch makes the union of all of the 2.77 changes in the patches in question.</para> 2.78 2.79 - <para>The patches to fold must not be applied; <command 2.80 + <para id="x_5f1">The patches to fold must not be applied; <command 2.81 role="hg-ext-mq">qfold</command> will exit with an error if 2.82 any is. The order in which patches are folded is significant; 2.83 <command role="hg-cmd">hg qfold a b</command> means 2.84 @@ -88,7 +88,7 @@ 2.85 <literal>a</literal>, followed by 2.86 <literal>b</literal></quote>.</para> 2.87 2.88 - <para>The comments from the folded patches are appended to the 2.89 + <para id="x_5f2">The comments from the folded patches are appended to the 2.90 comments of the destination patch, with each block of comments 2.91 separated by three asterisk 2.92 (<quote><literal>*</literal></quote>) characters. Use the 2.93 @@ -96,19 +96,19 @@ 2.94 edit the commit message for the combined patch/changeset after 2.95 the folding has completed.</para> 2.96 2.97 - <para>Options:</para> 2.98 - <itemizedlist> 2.99 - <listitem><para><option 2.100 + <para id="x_5f3">Options:</para> 2.101 + <itemizedlist> 2.102 + <listitem><para id="x_5f4"><option 2.103 role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the 2.104 commit message and patch description for the newly folded 2.105 patch.</para> 2.106 </listitem> 2.107 - <listitem><para><option 2.108 + <listitem><para id="x_5f5"><option 2.109 role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the 2.110 contents of the given file as the new commit message and 2.111 patch description for the folded patch.</para> 2.112 </listitem> 2.113 - <listitem><para><option 2.114 + <listitem><para id="x_5f6"><option 2.115 role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the 2.116 given text as the new commit message and patch description 2.117 for the folded patch.</para> 2.118 @@ -120,7 +120,7 @@ 2.119 role="hg-ext-mq">qheader</command>&emdash;display the 2.120 header/description of a patch</title> 2.121 2.122 - <para>The <command role="hg-ext-mq">qheader</command> command 2.123 + <para id="x_5f7">The <command role="hg-ext-mq">qheader</command> command 2.124 prints the header, or description, of a patch. By default, it 2.125 prints the header of the topmost applied patch. Given an 2.126 argument, it prints the header of the named patch.</para> 2.127 @@ -130,7 +130,7 @@ 2.128 <title><command role="hg-ext-mq">qimport</command>&emdash;import 2.129 a third-party patch into the queue</title> 2.130 2.131 - <para>The <command role="hg-ext-mq">qimport</command> command 2.132 + <para id="x_5f8">The <command role="hg-ext-mq">qimport</command> command 2.133 adds an entry for an external patch to the <filename 2.134 role="special">series</filename> file, and copies the patch 2.135 into the <filename role="special" 2.136 @@ -138,7 +138,7 @@ 2.137 the entry immediately after the topmost applied patch, but 2.138 does not push the patch.</para> 2.139 2.140 - <para>If the <filename role="special" 2.141 + <para id="x_5f9">If the <filename role="special" 2.142 class="directory">.hg/patches</filename> directory is a 2.143 repository, <command role="hg-ext-mq">qimport</command> 2.144 automatically does an <command role="hg-cmd">hg add</command> 2.145 @@ -149,14 +149,14 @@ 2.146 <title><command role="hg-ext-mq">qinit</command>&emdash;prepare 2.147 a repository to work with MQ</title> 2.148 2.149 - <para>The <command role="hg-ext-mq">qinit</command> command 2.150 + <para id="x_5fa">The <command role="hg-ext-mq">qinit</command> command 2.151 prepares a repository to work with MQ. It creates a directory 2.152 called <filename role="special" 2.153 class="directory">.hg/patches</filename>.</para> 2.154 2.155 - <para>Options:</para> 2.156 - <itemizedlist> 2.157 - <listitem><para><option 2.158 + <para id="x_5fb">Options:</para> 2.159 + <itemizedlist> 2.160 + <listitem><para id="x_5fc"><option 2.161 role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create 2.162 <filename role="special" 2.163 class="directory">.hg/patches</filename> as a repository 2.164 @@ -166,7 +166,7 @@ 2.165 file.</para> 2.166 </listitem></itemizedlist> 2.167 2.168 - <para>When the <filename role="special" 2.169 + <para id="x_5fd">When the <filename role="special" 2.170 class="directory">.hg/patches</filename> directory is a 2.171 repository, the <command role="hg-ext-mq">qimport</command> 2.172 and <command role="hg-ext-mq">qnew</command> commands 2.173 @@ -178,7 +178,7 @@ 2.174 <title><command role="hg-ext-mq">qnew</command>&emdash;create a 2.175 new patch</title> 2.176 2.177 - <para>The <command role="hg-ext-mq">qnew</command> command 2.178 + <para id="x_5fe">The <command role="hg-ext-mq">qnew</command> command 2.179 creates a new patch. It takes one mandatory argument, the 2.180 name to use for the patch file. The newly created patch is 2.181 created empty by default. It is added to the <filename 2.182 @@ -186,7 +186,7 @@ 2.183 topmost applied patch, and is immediately pushed on top of 2.184 that patch.</para> 2.185 2.186 - <para>If <command role="hg-ext-mq">qnew</command> finds modified 2.187 + <para id="x_5ff">If <command role="hg-ext-mq">qnew</command> finds modified 2.188 files in the working directory, it will refuse to create a new 2.189 patch unless the <option 2.190 role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used 2.191 @@ -194,16 +194,16 @@ 2.192 role="hg-ext-mq">qrefresh</command> your topmost applied 2.193 patch before you apply a new patch on top of it.</para> 2.194 2.195 - <para>Options:</para> 2.196 - <itemizedlist> 2.197 - <listitem><para><option 2.198 + <para id="x_600">Options:</para> 2.199 + <itemizedlist> 2.200 + <listitem><para id="x_601"><option 2.201 role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new 2.202 patch if the contents of the working directory are 2.203 modified. Any outstanding modifications are added to the 2.204 newly created patch, so after this command completes, the 2.205 working directory will no longer be modified.</para> 2.206 </listitem> 2.207 - <listitem><para><option 2.208 + <listitem><para id="x_602"><option 2.209 role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given 2.210 text as the commit message. This text will be stored at 2.211 the beginning of the patch file, before the patch 2.212 @@ -215,7 +215,7 @@ 2.213 <title><command role="hg-ext-mq">qnext</command>&emdash;print 2.214 the name of the next patch</title> 2.215 2.216 - <para>The <command role="hg-ext-mq">qnext</command> command 2.217 + <para id="x_603">The <command role="hg-ext-mq">qnext</command> command 2.218 prints the name name of the next patch in the <filename 2.219 role="special">series</filename> file after the topmost 2.220 applied patch. This patch will become the topmost applied 2.221 @@ -227,15 +227,15 @@ 2.222 <title><command role="hg-ext-mq">qpop</command>&emdash;pop 2.223 patches off the stack</title> 2.224 2.225 - <para>The <command role="hg-ext-mq">qpop</command> command 2.226 + <para id="x_604">The <command role="hg-ext-mq">qpop</command> command 2.227 removes applied patches from the top of the stack of applied 2.228 patches. By default, it removes only one patch.</para> 2.229 2.230 - <para>This command removes the changesets that represent the 2.231 + <para id="x_605">This command removes the changesets that represent the 2.232 popped patches from the repository, and updates the working 2.233 directory to undo the effects of the patches.</para> 2.234 2.235 - <para>This command takes an optional argument, which it uses as 2.236 + <para id="x_606">This command takes an optional argument, which it uses as 2.237 the name or index of the patch to pop to. If given a name, it 2.238 will pop patches until the named patch is the topmost applied 2.239 patch. If given a number, <command 2.240 @@ -245,7 +245,7 @@ 2.241 It pops patches until the patch identified by the given index 2.242 is the topmost applied patch.</para> 2.243 2.244 - <para>The <command role="hg-ext-mq">qpop</command> command does 2.245 + <para id="x_607">The <command role="hg-ext-mq">qpop</command> command does 2.246 not read or write patches or the <filename 2.247 role="special">series</filename> file. It is thus safe to 2.248 <command role="hg-ext-mq">qpop</command> a patch that you have 2.249 @@ -254,31 +254,31 @@ 2.250 In the latter two cases, use the name of the patch as it was 2.251 when you applied it.</para> 2.252 2.253 - <para>By default, the <command role="hg-ext-mq">qpop</command> 2.254 + <para id="x_608">By default, the <command role="hg-ext-mq">qpop</command> 2.255 command will not pop any patches if the working directory has 2.256 been modified. You can override this behaviour using the 2.257 <option role="hg-ext-mq-cmd-qpop-opt">-f</option> option, 2.258 which reverts all modifications in the working 2.259 directory.</para> 2.260 2.261 - <para>Options:</para> 2.262 - <itemizedlist> 2.263 - <listitem><para><option 2.264 + <para id="x_609">Options:</para> 2.265 + <itemizedlist> 2.266 + <listitem><para id="x_60a"><option 2.267 role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all 2.268 applied patches. This returns the repository to its state 2.269 before you applied any patches.</para> 2.270 </listitem> 2.271 - <listitem><para><option 2.272 + <listitem><para id="x_60b"><option 2.273 role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly 2.274 revert any modifications to the working directory when 2.275 popping.</para> 2.276 </listitem> 2.277 - <listitem><para><option 2.278 + <listitem><para id="x_60c"><option 2.279 role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch 2.280 from the named queue.</para> 2.281 </listitem></itemizedlist> 2.282 2.283 - <para>The <command role="hg-ext-mq">qpop</command> command 2.284 + <para id="x_60d">The <command role="hg-ext-mq">qpop</command> command 2.285 removes one line from the end of the <filename 2.286 role="special">status</filename> file for each patch that it 2.287 pops.</para> 2.288 @@ -288,7 +288,7 @@ 2.289 <title><command role="hg-ext-mq">qprev</command>&emdash;print 2.290 the name of the previous patch</title> 2.291 2.292 - <para>The <command role="hg-ext-mq">qprev</command> command 2.293 + <para id="x_60e">The <command role="hg-ext-mq">qprev</command> command 2.294 prints the name of the patch in the <filename 2.295 role="special">series</filename> file that comes before the 2.296 topmost applied patch. This will become the topmost applied 2.297 @@ -300,18 +300,18 @@ 2.298 <title><command role="hg-ext-mq">qpush</command>&emdash;push 2.299 patches onto the stack</title> 2.300 2.301 - <para>The <command role="hg-ext-mq">qpush</command> command adds 2.302 + <para id="x_60f">The <command role="hg-ext-mq">qpush</command> command adds 2.303 patches onto the applied stack. By default, it adds only one 2.304 patch.</para> 2.305 2.306 - <para>This command creates a new changeset to represent each 2.307 + <para id="x_610">This command creates a new changeset to represent each 2.308 applied patch, and updates the working directory to apply the 2.309 effects of the patches.</para> 2.310 2.311 - <para>The default data used when creating a changeset are as 2.312 + <para id="x_611">The default data used when creating a changeset are as 2.313 follows:</para> 2.314 <itemizedlist> 2.315 - <listitem><para>The commit date and time zone are the current 2.316 + <listitem><para id="x_612">The commit date and time zone are the current 2.317 date and time zone. Because these data are used to 2.318 compute the identity of a changeset, this means that if 2.319 you <command role="hg-ext-mq">qpop</command> a patch and 2.320 @@ -319,32 +319,32 @@ 2.321 changeset that you push will have a different identity 2.322 than the changeset you popped.</para> 2.323 </listitem> 2.324 - <listitem><para>The author is the same as the default used by 2.325 + <listitem><para id="x_613">The author is the same as the default used by 2.326 the <command role="hg-cmd">hg commit</command> 2.327 command.</para> 2.328 </listitem> 2.329 - <listitem><para>The commit message is any text from the patch 2.330 + <listitem><para id="x_614">The commit message is any text from the patch 2.331 file that comes before the first diff header. If there is 2.332 no such text, a default commit message is used that 2.333 identifies the name of the patch.</para> 2.334 </listitem></itemizedlist> 2.335 - <para>If a patch contains a Mercurial patch header (XXX add 2.336 + <para id="x_615">If a patch contains a Mercurial patch header (XXX add 2.337 link), the information in the patch header overrides these 2.338 defaults.</para> 2.339 2.340 - <para>Options:</para> 2.341 - <itemizedlist> 2.342 - <listitem><para><option 2.343 + <para id="x_616">Options:</para> 2.344 + <itemizedlist> 2.345 + <listitem><para id="x_617"><option 2.346 role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all 2.347 unapplied patches from the <filename 2.348 role="special">series</filename> file until there are 2.349 none left to push.</para> 2.350 </listitem> 2.351 - <listitem><para><option 2.352 + <listitem><para id="x_618"><option 2.353 role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name 2.354 of the patch to the end of the commit message.</para> 2.355 </listitem> 2.356 - <listitem><para><option 2.357 + <listitem><para id="x_619"><option 2.358 role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch 2.359 fails to apply cleanly, use the entry for the patch in 2.360 another saved queue to compute the parameters for a 2.361 @@ -352,12 +352,12 @@ 2.362 normal Mercurial merge machinery. Use the resolution of 2.363 the merge as the new patch content.</para> 2.364 </listitem> 2.365 - <listitem><para><option 2.366 + <listitem><para id="x_61a"><option 2.367 role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the 2.368 named queue if merging while pushing.</para> 2.369 </listitem></itemizedlist> 2.370 2.371 - <para>The <command role="hg-ext-mq">qpush</command> command 2.372 + <para id="x_61b">The <command role="hg-ext-mq">qpush</command> command 2.373 reads, but does not modify, the <filename 2.374 role="special">series</filename> file. It appends one line 2.375 to the <command role="hg-cmd">hg status</command> file for 2.376 @@ -369,24 +369,24 @@ 2.377 role="hg-ext-mq">qrefresh</command>&emdash;update the 2.378 topmost applied patch</title> 2.379 2.380 - <para>The <command role="hg-ext-mq">qrefresh</command> command 2.381 + <para id="x_61c">The <command role="hg-ext-mq">qrefresh</command> command 2.382 updates the topmost applied patch. It modifies the patch, 2.383 removes the old changeset that represented the patch, and 2.384 creates a new changeset to represent the modified 2.385 patch.</para> 2.386 2.387 - <para>The <command role="hg-ext-mq">qrefresh</command> command 2.388 + <para id="x_61d">The <command role="hg-ext-mq">qrefresh</command> command 2.389 looks for the following modifications:</para> 2.390 <itemizedlist> 2.391 - <listitem><para>Changes to the commit message, i.e. the text 2.392 + <listitem><para id="x_61e">Changes to the commit message, i.e. the text 2.393 before the first diff header in the patch file, are 2.394 reflected in the new changeset that represents the 2.395 patch.</para> 2.396 </listitem> 2.397 - <listitem><para>Modifications to tracked files in the working 2.398 + <listitem><para id="x_61f">Modifications to tracked files in the working 2.399 directory are added to the patch.</para> 2.400 </listitem> 2.401 - <listitem><para>Changes to the files tracked using <command 2.402 + <listitem><para id="x_620">Changes to the files tracked using <command 2.403 role="hg-cmd">hg add</command>, <command 2.404 role="hg-cmd">hg copy</command>, <command 2.405 role="hg-cmd">hg remove</command>, or <command 2.406 @@ -395,25 +395,25 @@ 2.407 removed files and rename sources are removed.</para> 2.408 </listitem></itemizedlist> 2.409 2.410 - <para>Even if <command role="hg-ext-mq">qrefresh</command> 2.411 + <para id="x_621">Even if <command role="hg-ext-mq">qrefresh</command> 2.412 detects no changes, it still recreates the changeset that 2.413 represents the patch. This causes the identity of the 2.414 changeset to differ from the previous changeset that 2.415 identified the patch.</para> 2.416 2.417 - <para>Options:</para> 2.418 - <itemizedlist> 2.419 - <listitem><para><option 2.420 + <para id="x_622">Options:</para> 2.421 + <itemizedlist> 2.422 + <listitem><para id="x_623"><option 2.423 role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify 2.424 the commit and patch description, using the preferred text 2.425 editor.</para> 2.426 </listitem> 2.427 - <listitem><para><option 2.428 + <listitem><para id="x_624"><option 2.429 role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify 2.430 the commit message and patch description, using the given 2.431 text.</para> 2.432 </listitem> 2.433 - <listitem><para><option 2.434 + <listitem><para id="x_625"><option 2.435 role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify 2.436 the commit message and patch description, using text from 2.437 the given file.</para> 2.438 @@ -424,11 +424,11 @@ 2.439 <title><command role="hg-ext-mq">qrename</command>&emdash;rename 2.440 a patch</title> 2.441 2.442 - <para>The <command role="hg-ext-mq">qrename</command> command 2.443 + <para id="x_626">The <command role="hg-ext-mq">qrename</command> command 2.444 renames a patch, and changes the entry for the patch in the 2.445 <filename role="special">series</filename> file.</para> 2.446 2.447 - <para>With a single argument, <command 2.448 + <para id="x_627">With a single argument, <command 2.449 role="hg-ext-mq">qrename</command> renames the topmost 2.450 applied patch. With two arguments, it renames its first 2.451 argument to its second.</para> 2.452 @@ -439,21 +439,21 @@ 2.453 role="hg-ext-mq">qrestore</command>&emdash;restore saved 2.454 queue state</title> 2.455 2.456 - <para>XXX No idea what this does.</para> 2.457 + <para id="x_628">XXX No idea what this does.</para> 2.458 2.459 </sect2> 2.460 <sect2> 2.461 <title><command role="hg-ext-mq">qsave</command>&emdash;save 2.462 current queue state</title> 2.463 2.464 - <para>XXX Likewise.</para> 2.465 + <para id="x_629">XXX Likewise.</para> 2.466 2.467 </sect2> 2.468 <sect2> 2.469 <title><command role="hg-ext-mq">qseries</command>&emdash;print 2.470 the entire patch series</title> 2.471 2.472 - <para>The <command role="hg-ext-mq">qseries</command> command 2.473 + <para id="x_62a">The <command role="hg-ext-mq">qseries</command> command 2.474 prints the entire patch series from the <filename 2.475 role="special">series</filename> file. It prints only patch 2.476 names, not empty lines or comments. It prints in order from 2.477 @@ -464,7 +464,7 @@ 2.478 <title><command role="hg-ext-mq">qtop</command>&emdash;print the 2.479 name of the current patch</title> 2.480 2.481 - <para>The <command role="hg-ext-mq">qtop</command> prints the 2.482 + <para id="x_62b">The <command role="hg-ext-mq">qtop</command> prints the 2.483 name of the topmost currently applied patch.</para> 2.484 2.485 </sect2> 2.486 @@ -473,7 +473,7 @@ 2.487 role="hg-ext-mq">qunapplied</command>&emdash;print patches 2.488 not yet applied</title> 2.489 2.490 - <para>The <command role="hg-ext-mq">qunapplied</command> command 2.491 + <para id="x_62c">The <command role="hg-ext-mq">qunapplied</command> command 2.492 prints the names of patches from the <filename 2.493 role="special">series</filename> file that are not yet 2.494 applied. It prints them in order from the next patch that 2.495 @@ -484,28 +484,28 @@ 2.496 <title><command role="hg-cmd">hg strip</command>&emdash;remove a 2.497 revision and descendants</title> 2.498 2.499 - <para>The <command role="hg-cmd">hg strip</command> command 2.500 + <para id="x_62d">The <command role="hg-cmd">hg strip</command> command 2.501 removes a revision, and all of its descendants, from the 2.502 repository. It undoes the effects of the removed revisions 2.503 from the repository, and updates the working directory to the 2.504 first parent of the removed revision.</para> 2.505 2.506 - <para>The <command role="hg-cmd">hg strip</command> command 2.507 + <para id="x_62e">The <command role="hg-cmd">hg strip</command> command 2.508 saves a backup of the removed changesets in a bundle, so that 2.509 they can be reapplied if removed in error.</para> 2.510 2.511 - <para>Options:</para> 2.512 - <itemizedlist> 2.513 - <listitem><para><option role="hg-opt-strip">-b</option>: Save 2.514 + <para id="x_62f">Options:</para> 2.515 + <itemizedlist> 2.516 + <listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save 2.517 unrelated changesets that are intermixed with the stripped 2.518 changesets in the backup bundle.</para> 2.519 </listitem> 2.520 - <listitem><para><option role="hg-opt-strip">-f</option>: If a 2.521 + <listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a 2.522 branch has multiple heads, remove all heads. XXX This 2.523 should be renamed, and use <literal>-f</literal> to strip 2.524 revs when there are pending changes.</para> 2.525 </listitem> 2.526 - <listitem><para><option role="hg-opt-strip">-n</option>: Do 2.527 + <listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do 2.528 not save a backup bundle.</para> 2.529 </listitem></itemizedlist> 2.530 2.531 @@ -518,18 +518,18 @@ 2.532 <title>The <filename role="special">series</filename> 2.533 file</title> 2.534 2.535 - <para>The <filename role="special">series</filename> file 2.536 + <para id="x_633">The <filename role="special">series</filename> file 2.537 contains a list of the names of all patches that MQ can apply. 2.538 It is represented as a list of names, with one name saved per 2.539 line. Leading and trailing white space in each line are 2.540 ignored.</para> 2.541 2.542 - <para>Lines may contain comments. A comment begins with the 2.543 + <para id="x_634">Lines may contain comments. A comment begins with the 2.544 <quote><literal>#</literal></quote> character, and extends to 2.545 the end of the line. Empty lines, and lines that contain only 2.546 comments, are ignored.</para> 2.547 2.548 - <para>You will often need to edit the <filename 2.549 + <para id="x_635">You will often need to edit the <filename 2.550 role="special">series</filename> file by hand, hence the 2.551 support for comments and empty lines noted above. For 2.552 example, you can comment out a patch temporarily, and <command 2.553 @@ -538,7 +538,7 @@ 2.554 patches are applied by reordering their entries in the 2.555 <filename role="special">series</filename> file.</para> 2.556 2.557 - <para>Placing the <filename role="special">series</filename> 2.558 + <para id="x_636">Placing the <filename role="special">series</filename> 2.559 file under revision control is also supported; it is a good 2.560 idea to place all of the patches that it refers to under 2.561 revision control, as well. If you create a patch directory 2.562 @@ -551,7 +551,7 @@ 2.563 <title>The <filename role="special">status</filename> 2.564 file</title> 2.565 2.566 - <para>The <filename role="special">status</filename> file 2.567 + <para id="x_637">The <filename role="special">status</filename> file 2.568 contains the names and changeset hashes of all patches that MQ 2.569 currently has applied. Unlike the <filename 2.570 role="special">series</filename> file, this file is not
3.1 --- a/en/appC-srcinstall.xml Thu Mar 19 20:54:12 2009 -0700 3.2 +++ b/en/appC-srcinstall.xml Thu Mar 19 21:18:52 2009 -0700 3.3 @@ -7,29 +7,29 @@ 3.4 <sect1 id="sec:srcinstall:unixlike"> 3.5 <title>On a Unix-like system</title> 3.6 3.7 - <para>If you are using a Unix-like system that has a sufficiently 3.8 + <para id="x_5e0">If you are using a Unix-like system that has a sufficiently 3.9 recent version of Python (2.3 or newer) available, it is easy to 3.10 install Mercurial from source.</para> 3.11 <orderedlist> 3.12 - <listitem><para>Download a recent source tarball from <ulink 3.13 + <listitem><para id="x_5e1">Download a recent source tarball from <ulink 3.14 url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para> 3.15 </listitem> 3.16 - <listitem><para>Unpack the tarball:</para> 3.17 + <listitem><para id="x_5e2">Unpack the tarball:</para> 3.18 <programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting> 3.19 </listitem> 3.20 - <listitem><para>Go into the source directory and run the 3.21 + <listitem><para id="x_5e3">Go into the source directory and run the 3.22 installer script. This will build Mercurial and install it 3.23 in your home directory.</para> 3.24 <programlisting>cd mercurial-MYVERSION 3.25 python setup.py install --force --home=$HOME</programlisting> 3.26 </listitem> 3.27 </orderedlist> 3.28 - <para>Once the install finishes, Mercurial will be in the 3.29 + <para id="x_5e4">Once the install finishes, Mercurial will be in the 3.30 <literal>bin</literal> subdirectory of your home directory. 3.31 Don't forget to make sure that this directory is present in your 3.32 shell's search path.</para> 3.33 3.34 - <para>You will probably need to set the <envar>PYTHONPATH</envar> 3.35 + <para id="x_5e5">You will probably need to set the <envar>PYTHONPATH</envar> 3.36 environment variable so that the Mercurial executable can find 3.37 the rest of the Mercurial packages. For example, on my laptop, 3.38 I have set it to <literal>/home/bos/lib/python</literal>. The 3.39 @@ -43,14 +43,14 @@ 3.40 <sect1> 3.41 <title>On Windows</title> 3.42 3.43 - <para>Building and installing Mercurial on Windows requires a 3.44 + <para id="x_5e6">Building and installing Mercurial on Windows requires a 3.45 variety of tools, a fair amount of technical knowledge, and 3.46 considerable patience. I very much <emphasis>do not 3.47 recommend</emphasis> this route if you are a <quote>casual 3.48 user</quote>. Unless you intend to hack on Mercurial, I 3.49 strongly suggest that you use a binary package instead.</para> 3.50 3.51 - <para>If you are intent on building Mercurial from source on 3.52 + <para id="x_5e7">If you are intent on building Mercurial from source on 3.53 Windows, follow the <quote>hard way</quote> directions on the 3.54 Mercurial wiki at <ulink 3.55 url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>,
4.1 --- a/en/appD-license.xml Thu Mar 19 20:54:12 2009 -0700 4.2 +++ b/en/appD-license.xml Thu Mar 19 21:18:52 2009 -0700 4.3 @@ -4,24 +4,24 @@ 4.4 <?dbhtml filename="open-publication-license.html"?> 4.5 <title>Open Publication License</title> 4.6 4.7 - <para>Version 1.0, 8 June 1999</para> 4.8 + <para id="x_638">Version 1.0, 8 June 1999</para> 4.9 4.10 <sect1> 4.11 <title>Requirements on both unmodified and modified 4.12 versions</title> 4.13 4.14 - <para>The Open Publication works may be reproduced and distributed 4.15 + <para id="x_639">The Open Publication works may be reproduced and distributed 4.16 in whole or in part, in any medium physical or electronic, 4.17 provided that the terms of this license are adhered to, and that 4.18 this license or an incorporation of it by reference (with any 4.19 options elected by the author(s) and/or publisher) is displayed 4.20 in the reproduction.</para> 4.21 4.22 - <para>Proper form for an incorporation by reference is as 4.23 + <para id="x_63a">Proper form for an incorporation by reference is as 4.24 follows:</para> 4.25 4.26 <blockquote> 4.27 - <para> Copyright (c) <emphasis>year</emphasis> by 4.28 + <para id="x_63b"> Copyright (c) <emphasis>year</emphasis> by 4.29 <emphasis>author's name or designee</emphasis>. This material 4.30 may be distributed only subject to the terms and conditions 4.31 set forth in the Open Publication License, 4.32 @@ -30,14 +30,14 @@ 4.33 url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para> 4.34 </blockquote> 4.35 4.36 - <para>The reference must be immediately followed with any options 4.37 + <para id="x_63c">The reference must be immediately followed with any options 4.38 elected by the author(s) and/or publisher of the document (see 4.39 section <xref linkend="sec:opl:options"/>).</para> 4.40 4.41 - <para>Commercial redistribution of Open Publication-licensed 4.42 + <para id="x_63d">Commercial redistribution of Open Publication-licensed 4.43 material is permitted.</para> 4.44 4.45 - <para>Any publication in standard (paper) book form shall require 4.46 + <para id="x_63e">Any publication in standard (paper) book form shall require 4.47 the citation of the original publisher and author. The publisher 4.48 and author's names shall appear on all outer surfaces of the 4.49 book. On all outer surfaces of the book the original publisher's 4.50 @@ -48,30 +48,30 @@ 4.51 <sect1> 4.52 <title>Copyright</title> 4.53 4.54 - <para>The copyright to each Open Publication is owned by its 4.55 + <para id="x_63f">The copyright to each Open Publication is owned by its 4.56 author(s) or designee.</para> 4.57 4.58 </sect1> 4.59 <sect1> 4.60 <title>Scope of license</title> 4.61 4.62 - <para>The following license terms apply to all Open Publication 4.63 + <para id="x_640">The following license terms apply to all Open Publication 4.64 works, unless otherwise explicitly stated in the 4.65 document.</para> 4.66 4.67 - <para>Mere aggregation of Open Publication works or a portion of 4.68 + <para id="x_641">Mere aggregation of Open Publication works or a portion of 4.69 an Open Publication work with other works or programs on the 4.70 same media shall not cause this license to apply to those other 4.71 works. The aggregate work shall contain a notice specifying the 4.72 inclusion of the Open Publication material and appropriate 4.73 copyright notice.</para> 4.74 4.75 - <para><emphasis role="bold">Severability</emphasis>. If any part 4.76 + <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part 4.77 of this license is found to be unenforceable in any 4.78 jurisdiction, the remaining portions of the license remain in 4.79 force.</para> 4.80 4.81 - <para><emphasis role="bold">No warranty</emphasis>. Open 4.82 + <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open 4.83 Publication works are licensed and provided <quote>as is</quote> 4.84 without warranty of any kind, express or implied, including, but 4.85 not limited to, the implied warranties of merchantability and 4.86 @@ -82,25 +82,25 @@ 4.87 <sect1> 4.88 <title>Requirements on modified works</title> 4.89 4.90 - <para>All modified versions of documents covered by this license, 4.91 + <para id="x_644">All modified versions of documents covered by this license, 4.92 including translations, anthologies, compilations and partial 4.93 documents, must meet the following requirements:</para> 4.94 4.95 <orderedlist> 4.96 - <listitem><para>The modified version must be labeled as 4.97 + <listitem><para id="x_645">The modified version must be labeled as 4.98 such.</para> 4.99 </listitem> 4.100 - <listitem><para>The person making the modifications must be 4.101 + <listitem><para id="x_646">The person making the modifications must be 4.102 identified and the modifications dated.</para> 4.103 </listitem> 4.104 - <listitem><para>Acknowledgement of the original author and 4.105 + <listitem><para id="x_647">Acknowledgement of the original author and 4.106 publisher if applicable must be retained according to normal 4.107 academic citation practices.</para> 4.108 </listitem> 4.109 - <listitem><para>The location of the original unmodified document 4.110 + <listitem><para id="x_648">The location of the original unmodified document 4.111 must be identified.</para> 4.112 </listitem> 4.113 - <listitem><para>The original author's (or authors') name(s) may 4.114 + <listitem><para id="x_649">The original author's (or authors') name(s) may 4.115 not be used to assert or imply endorsement of the resulting 4.116 document without the original author's (or authors') 4.117 permission.</para> 4.118 @@ -110,23 +110,23 @@ 4.119 <sect1> 4.120 <title>Good-practice recommendations</title> 4.121 4.122 - <para>In addition to the requirements of this license, it is 4.123 + <para id="x_64a">In addition to the requirements of this license, it is 4.124 requested from and strongly recommended of redistributors 4.125 that:</para> 4.126 4.127 <orderedlist> 4.128 - <listitem><para>If you are distributing Open Publication works 4.129 + <listitem><para id="x_64b">If you are distributing Open Publication works 4.130 on hardcopy or CD-ROM, you provide email notification to the 4.131 authors of your intent to redistribute at least thirty days 4.132 before your manuscript or media freeze, to give the authors 4.133 time to provide updated documents. This notification should 4.134 describe modifications, if any, made to the document.</para> 4.135 </listitem> 4.136 - <listitem><para>All substantive modifications (including 4.137 + <listitem><para id="x_64c">All substantive modifications (including 4.138 deletions) be either clearly marked up in the document or 4.139 else described in an attachment to the document.</para> 4.140 </listitem> 4.141 - <listitem><para>Finally, while it is not mandatory under this 4.142 + <listitem><para id="x_64d">Finally, while it is not mandatory under this 4.143 license, it is considered good form to offer a free copy of 4.144 any hardcopy and CD-ROM expression of an Open 4.145 Publication-licensed work to its author(s).</para> 4.146 @@ -136,7 +136,7 @@ 4.147 <sect1 id="sec:opl:options"> 4.148 <title>License options</title> 4.149 4.150 - <para>The author(s) and/or publisher of an Open 4.151 + <para id="x_64e">The author(s) and/or publisher of an Open 4.152 Publication-licensed document may elect certain options by 4.153 appending language to the reference to or copy of the license. 4.154 These options are considered part of the license instance and 4.155 @@ -144,25 +144,25 @@ 4.156 reference) in derived works.</para> 4.157 4.158 <orderedlist> 4.159 - <listitem><para>To prohibit distribution of substantively 4.160 + <listitem><para id="x_64f">To prohibit distribution of substantively 4.161 modified versions without the explicit permission of the 4.162 author(s). <quote>Substantive modification</quote> is 4.163 defined as a change to the semantic content of the document, 4.164 and excludes mere changes in format or typographical 4.165 corrections.</para> 4.166 </listitem> 4.167 - <listitem><para> To accomplish this, add the phrase 4.168 + <listitem><para id="x_650"> To accomplish this, add the phrase 4.169 <quote>Distribution of substantively modified versions of 4.170 this document is prohibited without the explicit 4.171 permission of the copyright holder.</quote> to the license 4.172 reference or copy.</para> 4.173 </listitem> 4.174 - <listitem><para>To prohibit any publication of this work or 4.175 + <listitem><para id="x_651">To prohibit any publication of this work or 4.176 derivative works in whole or in part in standard (paper) 4.177 book form for commercial purposes is prohibited unless prior 4.178 permission is obtained from the copyright holder.</para> 4.179 </listitem> 4.180 - <listitem><para>To accomplish this, add the phrase 4.181 + <listitem><para id="x_652">To accomplish this, add the phrase 4.182 <quote>Distribution of the work or derivative of the work in 4.183 any standard (paper) book form is prohibited unless prior 4.184 permission is obtained from the copyright holder.</quote>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/autoid.py Thu Mar 19 21:18:52 2009 -0700 5.3 @@ -0,0 +1,47 @@ 5.4 +#!/usr/bin/env python 5.5 +# 5.6 +# Add unique ID attributes to para tags. This script should only be 5.7 +# run by one person, since otherwise it introduces the possibility of 5.8 +# chaotic conflicts among tags. 5.9 + 5.10 +import glob, os, re, sys 5.11 + 5.12 +tagged = re.compile('<para[^>]* id="x_([0-9a-f]+)"[^>]*>', re.M) 5.13 +untagged = re.compile('<para>') 5.14 + 5.15 +names = glob.glob('ch*.xml') + glob.glob('app*.xml') 5.16 + 5.17 +# First pass: find the highest-numbered paragraph ID. 5.18 + 5.19 +biggest_id = 0 5.20 +seen = set() 5.21 +errs = 0 5.22 + 5.23 +for name in names: 5.24 + for m in tagged.finditer(open(name).read()): 5.25 + i = int(m.group(1),16) 5.26 + if i in seen: 5.27 + print >> sys.stderr, '%s: duplication of ID %s' % (name, i) 5.28 + errs += 1 5.29 + seen.add(i) 5.30 + if i > biggest_id: 5.31 + biggest_id = i 5.32 + 5.33 +def retag(s): 5.34 + global biggest_id 5.35 + biggest_id += 1 5.36 + return '<para id="x_%x">' % biggest_id 5.37 + 5.38 +# Second pass: add IDs to paragraphs that currently lack them. 5.39 + 5.40 +for name in names: 5.41 + f = open(name).read() 5.42 + f1 = untagged.sub(retag, f) 5.43 + if f1 != f: 5.44 + tmpname = name + '.tmp' 5.45 + fp = open(tmpname, 'w') 5.46 + fp.write(f1) 5.47 + fp.close() 5.48 + os.rename(tmpname, name) 5.49 + 5.50 +sys.exit(errs)
6.1 --- a/en/ch00-preface.xml Thu Mar 19 20:54:12 2009 -0700 6.2 +++ b/en/ch00-preface.xml Thu Mar 19 21:18:52 2009 -0700 6.3 @@ -6,13 +6,13 @@ 6.4 <sect1> 6.5 <title>Why revision control? Why Mercurial?</title> 6.6 6.7 - <para>Revision control is the process of managing multiple 6.8 + <para id="x_6d">Revision control is the process of managing multiple 6.9 versions of a piece of information. In its simplest form, this 6.10 is something that many people do by hand: every time you modify 6.11 a file, save it under a new name that contains a number, each 6.12 one higher than the number of the preceding version.</para> 6.13 6.14 - <para>Manually managing multiple versions of even a single file is 6.15 + <para id="x_6e">Manually managing multiple versions of even a single file is 6.16 an error-prone task, though, so software tools to help automate 6.17 this process have long been available. The earliest automated 6.18 revision control tools were intended to help a single user to 6.19 @@ -23,11 +23,11 @@ 6.20 problem coping with thousands of people working together on 6.21 projects that consist of hundreds of thousands of files.</para> 6.22 6.23 - <para>The arrival of distributed revision control is relatively 6.24 + <para id="x_6f">The arrival of distributed revision control is relatively 6.25 recent, and so far this new field has grown due to people's 6.26 willingness to explore ill-charted territory.</para> 6.27 6.28 - <para>I am writing a book about distributed revision control 6.29 + <para id="x_70">I am writing a book about distributed revision control 6.30 because I believe that it is an important subject that deserves 6.31 a field guide. I chose to write about Mercurial because it is 6.32 the easiest tool to learn the terrain with, and yet it scales to 6.33 @@ -37,41 +37,41 @@ 6.34 <sect2> 6.35 <title>Why use revision control?</title> 6.36 6.37 - <para>There are a number of reasons why you or your team might 6.38 + <para id="x_71">There are a number of reasons why you or your team might 6.39 want to use an automated revision control tool for a 6.40 project.</para> 6.41 6.42 <itemizedlist> 6.43 - <listitem><para>It will track the history and evolution of 6.44 + <listitem><para id="x_72">It will track the history and evolution of 6.45 your project, so you don't have to. For every change, 6.46 you'll have a log of <emphasis>who</emphasis> made it; 6.47 <emphasis>why</emphasis> they made it; 6.48 <emphasis>when</emphasis> they made it; and 6.49 <emphasis>what</emphasis> the change 6.50 was.</para></listitem> 6.51 - <listitem><para>When you're working with other people, 6.52 + <listitem><para id="x_73">When you're working with other people, 6.53 revision control software makes it easier for you to 6.54 collaborate. For example, when people more or less 6.55 simultaneously make potentially incompatible changes, the 6.56 software will help you to identify and resolve those 6.57 conflicts.</para></listitem> 6.58 - <listitem><para>It can help you to recover from mistakes. If 6.59 + <listitem><para id="x_74">It can help you to recover from mistakes. If 6.60 you make a change that later turns out to be in error, you 6.61 can revert to an earlier version of one or more files. In 6.62 fact, a <emphasis>really</emphasis> good revision control 6.63 tool will even help you to efficiently figure out exactly 6.64 when a problem was introduced (see section <xref 6.65 linkend="sec:undo:bisect"/> for details).</para></listitem> 6.66 - <listitem><para>It will help you to work simultaneously on, 6.67 + <listitem><para id="x_75">It will help you to work simultaneously on, 6.68 and manage the drift between, multiple versions of your 6.69 project.</para></listitem> 6.70 </itemizedlist> 6.71 6.72 - <para>Most of these reasons are equally valid---at least in 6.73 + <para id="x_76">Most of these reasons are equally valid---at least in 6.74 theory---whether you're working on a project by yourself, or 6.75 with a hundred other people.</para> 6.76 6.77 - <para>A key question about the practicality of revision control 6.78 + <para id="x_77">A key question about the practicality of revision control 6.79 at these two different scales (<quote>lone hacker</quote> and 6.80 <quote>huge team</quote>) is how its 6.81 <emphasis>benefits</emphasis> compare to its 6.82 @@ -79,19 +79,19 @@ 6.83 difficult to understand or use is going to impose a high 6.84 cost.</para> 6.85 6.86 - <para>A five-hundred-person project is likely to collapse under 6.87 + <para id="x_78">A five-hundred-person project is likely to collapse under 6.88 its own weight almost immediately without a revision control 6.89 tool and process. In this case, the cost of using revision 6.90 control might hardly seem worth considering, since 6.91 <emphasis>without</emphasis> it, failure is almost 6.92 guaranteed.</para> 6.93 6.94 - <para>On the other hand, a one-person <quote>quick hack</quote> 6.95 + <para id="x_79">On the other hand, a one-person <quote>quick hack</quote> 6.96 might seem like a poor place to use a revision control tool, 6.97 because surely the cost of using one must be close to the 6.98 overall cost of the project. Right?</para> 6.99 6.100 - <para>Mercurial uniquely supports <emphasis>both</emphasis> of 6.101 + <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of 6.102 these scales of development. You can learn the basics in just 6.103 a few minutes, and due to its low overhead, you can apply 6.104 revision control to the smallest of projects with ease. Its 6.105 @@ -101,7 +101,7 @@ 6.106 time, Mercurial's high performance and peer-to-peer nature let 6.107 you scale painlessly to handle large projects.</para> 6.108 6.109 - <para>No revision control tool can rescue a poorly run project, 6.110 + <para id="x_7b">No revision control tool can rescue a poorly run project, 6.111 but a good choice of tools can make a huge difference to the 6.112 fluidity with which you can work on a project.</para> 6.113 6.114 @@ -110,19 +110,19 @@ 6.115 <sect2> 6.116 <title>The many names of revision control</title> 6.117 6.118 - <para>Revision control is a diverse field, so much so that it is 6.119 + <para id="x_7c">Revision control is a diverse field, so much so that it is 6.120 referred to by many names and acronyms. Here are a few of the 6.121 more common variations you'll encounter:</para> 6.122 <itemizedlist> 6.123 - <listitem><para>Revision control (RCS)</para></listitem> 6.124 - <listitem><para>Software configuration management (SCM), or 6.125 + <listitem><para id="x_7d">Revision control (RCS)</para></listitem> 6.126 + <listitem><para id="x_7e">Software configuration management (SCM), or 6.127 configuration management</para></listitem> 6.128 - <listitem><para>Source code management</para></listitem> 6.129 - <listitem><para>Source code control, or source 6.130 + <listitem><para id="x_7f">Source code management</para></listitem> 6.131 + <listitem><para id="x_80">Source code control, or source 6.132 control</para></listitem> 6.133 - <listitem><para>Version control 6.134 + <listitem><para id="x_81">Version control 6.135 (VCS)</para></listitem></itemizedlist> 6.136 - <para>Some people claim that these terms actually have different 6.137 + <para id="x_82">Some people claim that these terms actually have different 6.138 meanings, but in practice they overlap so much that there's no 6.139 agreed or even useful way to tease them apart.</para> 6.140 6.141 @@ -132,7 +132,7 @@ 6.142 <sect1> 6.143 <title>This book is a work in progress</title> 6.144 6.145 - <para>I am releasing this book while I am still writing it, in the 6.146 + <para id="x_83">I am releasing this book while I am still writing it, in the 6.147 hope that it will prove useful to others. I am writing under an 6.148 open license in the hope that you, my readers, will contribute 6.149 feedback and perhaps content of your own.</para> 6.150 @@ -141,21 +141,21 @@ 6.151 <sect1> 6.152 <title>About the examples in this book</title> 6.153 6.154 - <para>This book takes an unusual approach to code samples. Every 6.155 + <para id="x_84">This book takes an unusual approach to code samples. Every 6.156 example is <quote>live</quote>---each one is actually the result 6.157 of a shell script that executes the Mercurial commands you see. 6.158 Every time an image of the book is built from its sources, all 6.159 the example scripts are automatically run, and their current 6.160 results compared against their expected results.</para> 6.161 6.162 - <para>The advantage of this approach is that the examples are 6.163 + <para id="x_85">The advantage of this approach is that the examples are 6.164 always accurate; they describe <emphasis>exactly</emphasis> the 6.165 behaviour of the version of Mercurial that's mentioned at the 6.166 front of the book. If I update the version of Mercurial that 6.167 I'm documenting, and the output of some command changes, the 6.168 build fails.</para> 6.169 6.170 - <para>There is a small disadvantage to this approach, which is 6.171 + <para id="x_86">There is a small disadvantage to this approach, which is 6.172 that the dates and times you'll see in examples tend to be 6.173 <quote>squashed</quote> together in a way that they wouldn't be 6.174 if the same commands were being typed by a human. Where a human 6.175 @@ -163,13 +163,13 @@ 6.176 resulting timestamps correspondingly spread out, my automated 6.177 example scripts run many commands in one second.</para> 6.178 6.179 - <para>As an instance of this, several consecutive commits in an 6.180 + <para id="x_87">As an instance of this, several consecutive commits in an 6.181 example can show up as having occurred during the same second. 6.182 You can see this occur in the <literal 6.183 role="hg-ext">bisect</literal> example in section <xref 6.184 id="sec:undo:bisect"/>, for instance.</para> 6.185 6.186 - <para>So when you're reading examples, don't place too much weight 6.187 + <para id="x_88">So when you're reading examples, don't place too much weight 6.188 on the dates or times you see in the output of commands. But 6.189 <emphasis>do</emphasis> be confident that the behaviour you're 6.190 seeing is consistent and reproducible.</para> 6.191 @@ -179,18 +179,18 @@ 6.192 <sect1> 6.193 <title>Trends in the field</title> 6.194 6.195 - <para>There has been an unmistakable trend in the development and 6.196 + <para id="x_89">There has been an unmistakable trend in the development and 6.197 use of revision control tools over the past four decades, as 6.198 people have become familiar with the capabilities of their tools 6.199 and constrained by their limitations.</para> 6.200 6.201 - <para>The first generation began by managing single files on 6.202 + <para id="x_8a">The first generation began by managing single files on 6.203 individual computers. Although these tools represented a huge 6.204 advance over ad-hoc manual revision control, their locking model 6.205 and reliance on a single computer limited them to small, 6.206 tightly-knit teams.</para> 6.207 6.208 - <para>The second generation loosened these constraints by moving 6.209 + <para id="x_8b">The second generation loosened these constraints by moving 6.210 to network-centered architectures, and managing entire projects 6.211 at a time. As projects grew larger, they ran into new problems. 6.212 With clients needing to talk to servers very frequently, server 6.213 @@ -202,7 +202,7 @@ 6.214 tools to interact with a project in a natural way, as they could 6.215 not record their changes.</para> 6.216 6.217 - <para>The current generation of revision control tools is 6.218 + <para id="x_8c">The current generation of revision control tools is 6.219 peer-to-peer in nature. All of these systems have dropped the 6.220 dependency on a single central server, and allow people to 6.221 distribute their revision control data to where it's actually 6.222 @@ -217,14 +217,14 @@ 6.223 <title>A few of the advantages of distributed revision 6.224 control</title> 6.225 6.226 - <para>Even though distributed revision control tools have for 6.227 + <para id="x_8d">Even though distributed revision control tools have for 6.228 several years been as robust and usable as their 6.229 previous-generation counterparts, people using older tools have 6.230 not yet necessarily woken up to their advantages. There are a 6.231 number of ways in which distributed tools shine relative to 6.232 centralised ones.</para> 6.233 6.234 - <para>For an individual developer, distributed tools are almost 6.235 + <para id="x_8e">For an individual developer, distributed tools are almost 6.236 always much faster than centralised tools. This is for a simple 6.237 reason: a centralised tool needs to talk over the network for 6.238 many common operations, because most metadata is stored in a 6.239 @@ -235,7 +235,7 @@ 6.240 going to spend a lot of time interacting with your revision 6.241 control software.</para> 6.242 6.243 - <para>Distributed tools are indifferent to the vagaries of your 6.244 + <para id="x_8f">Distributed tools are indifferent to the vagaries of your 6.245 server infrastructure, again because they replicate metadata to 6.246 so many locations. If you use a centralised system and your 6.247 server catches fire, you'd better hope that your backup media 6.248 @@ -243,7 +243,7 @@ 6.249 worked. With a distributed tool, you have many backups 6.250 available on every contributor's computer.</para> 6.251 6.252 - <para>The reliability of your network will affect distributed 6.253 + <para id="x_90">The reliability of your network will affect distributed 6.254 tools far less than it will centralised tools. You can't even 6.255 use a centralised tool without a network connection, except for 6.256 a few highly constrained commands. With a distributed tool, if 6.257 @@ -256,7 +256,7 @@ 6.258 <sect2> 6.259 <title>Advantages for open source projects</title> 6.260 6.261 - <para>If you take a shine to an open source project and decide 6.262 + <para id="x_91">If you take a shine to an open source project and decide 6.263 that you would like to start hacking on it, and that project 6.264 uses a distributed revision control tool, you are at once a 6.265 peer with the people who consider themselves the 6.266 @@ -274,7 +274,7 @@ 6.267 <sect3> 6.268 <title>The forking non-problem</title> 6.269 6.270 - <para>It has been suggested that distributed revision control 6.271 + <para id="x_92">It has been suggested that distributed revision control 6.272 tools pose some sort of risk to open source projects because 6.273 they make it easy to <quote>fork</quote> the development of 6.274 a project. A fork happens when there are differences in 6.275 @@ -284,7 +284,7 @@ 6.276 project's source code, and goes off in its own 6.277 direction.</para> 6.278 6.279 - <para>Sometimes the camps in a fork decide to reconcile their 6.280 + <para id="x_93">Sometimes the camps in a fork decide to reconcile their 6.281 differences. With a centralised revision control system, the 6.282 <emphasis>technical</emphasis> process of reconciliation is 6.283 painful, and has to be performed largely by hand. You have 6.284 @@ -293,7 +293,7 @@ 6.285 the tree somehow. This usually loses some or all of one 6.286 side's revision history.</para> 6.287 6.288 - <para>What distributed tools do with respect to forking is 6.289 + <para id="x_94">What distributed tools do with respect to forking is 6.290 they make forking the <emphasis>only</emphasis> way to 6.291 develop a project. Every single change that you make is 6.292 potentially a fork point. The great strength of this 6.293 @@ -302,23 +302,23 @@ 6.294 because forks are absolutely fundamental: they happen all 6.295 the time.</para> 6.296 6.297 - <para>If every piece of work that everybody does, all the 6.298 + <para id="x_95">If every piece of work that everybody does, all the 6.299 time, is framed in terms of forking and merging, then what 6.300 the open source world refers to as a <quote>fork</quote> 6.301 becomes <emphasis>purely</emphasis> a social issue. If 6.302 anything, distributed tools <emphasis>lower</emphasis> the 6.303 likelihood of a fork:</para> 6.304 <itemizedlist> 6.305 - <listitem><para>They eliminate the social distinction that 6.306 + <listitem><para id="x_96">They eliminate the social distinction that 6.307 centralised tools impose: that between insiders (people 6.308 with commit access) and outsiders (people 6.309 without).</para></listitem> 6.310 - <listitem><para>They make it easier to reconcile after a 6.311 + <listitem><para id="x_97">They make it easier to reconcile after a 6.312 social fork, because all that's involved from the 6.313 perspective of the revision control software is just 6.314 another merge.</para></listitem></itemizedlist> 6.315 6.316 - <para>Some people resist distributed tools because they want 6.317 + <para id="x_98">Some people resist distributed tools because they want 6.318 to retain tight control over their projects, and they 6.319 believe that centralised tools give them this control. 6.320 However, if you're of this belief, and you publish your CVS 6.321 @@ -335,7 +335,7 @@ 6.322 <sect2> 6.323 <title>Advantages for commercial projects</title> 6.324 6.325 - <para>Many commercial projects are undertaken by teams that are 6.326 + <para id="x_99">Many commercial projects are undertaken by teams that are 6.327 scattered across the globe. Contributors who are far from a 6.328 central server will see slower command execution and perhaps 6.329 less reliability. Commercial revision control systems attempt 6.330 @@ -347,7 +347,7 @@ 6.331 there's no redundant communication between repositories over 6.332 expensive long-haul network links.</para> 6.333 6.334 - <para>Centralised revision control systems tend to have 6.335 + <para id="x_9a">Centralised revision control systems tend to have 6.336 relatively low scalability. It's not unusual for an expensive 6.337 centralised system to fall over under the combined load of 6.338 just a few dozen concurrent users. Once again, the typical 6.339 @@ -359,7 +359,7 @@ 6.340 replication to balance load becomes a simple matter of 6.341 scripting.</para> 6.342 6.343 - <para>If you have an employee in the field, troubleshooting a 6.344 + <para id="x_9b">If you have an employee in the field, troubleshooting a 6.345 problem at a customer's site, they'll benefit from distributed 6.346 revision control. The tool will let them generate custom 6.347 builds, try different fixes in isolation from each other, and 6.348 @@ -372,35 +372,35 @@ 6.349 <sect1> 6.350 <title>Why choose Mercurial?</title> 6.351 6.352 - <para>Mercurial has a unique set of properties that make it a 6.353 + <para id="x_9c">Mercurial has a unique set of properties that make it a 6.354 particularly good choice as a revision control system.</para> 6.355 <itemizedlist> 6.356 - <listitem><para>It is easy to learn and use.</para></listitem> 6.357 - <listitem><para>It is lightweight.</para></listitem> 6.358 - <listitem><para>It scales excellently.</para></listitem> 6.359 - <listitem><para>It is easy to 6.360 + <listitem><para id="x_9d">It is easy to learn and use.</para></listitem> 6.361 + <listitem><para id="x_9e">It is lightweight.</para></listitem> 6.362 + <listitem><para id="x_9f">It scales excellently.</para></listitem> 6.363 + <listitem><para id="x_a0">It is easy to 6.364 customise.</para></listitem></itemizedlist> 6.365 6.366 - <para>If you are at all familiar with revision control systems, 6.367 + <para id="x_a1">If you are at all familiar with revision control systems, 6.368 you should be able to get up and running with Mercurial in less 6.369 than five minutes. Even if not, it will take no more than a few 6.370 minutes longer. Mercurial's command and feature sets are 6.371 generally uniform and consistent, so you can keep track of a few 6.372 general rules instead of a host of exceptions.</para> 6.373 6.374 - <para>On a small project, you can start working with Mercurial in 6.375 + <para id="x_a2">On a small project, you can start working with Mercurial in 6.376 moments. Creating new changes and branches; transferring changes 6.377 around (whether locally or over a network); and history and 6.378 status operations are all fast. Mercurial attempts to stay 6.379 nimble and largely out of your way by combining low cognitive 6.380 overhead with blazingly fast operations.</para> 6.381 6.382 - <para>The usefulness of Mercurial is not limited to small 6.383 + <para id="x_a3">The usefulness of Mercurial is not limited to small 6.384 projects: it is used by projects with hundreds to thousands of 6.385 contributors, each containing tens of thousands of files and 6.386 hundreds of megabytes of source code.</para> 6.387 6.388 - <para>If the core functionality of Mercurial is not enough for 6.389 + <para id="x_a4">If the core functionality of Mercurial is not enough for 6.390 you, it's easy to build on. Mercurial is well suited to 6.391 scripting tasks, and its clean internals and implementation in 6.392 Python make it easy to add features in the form of extensions. 6.393 @@ -412,7 +412,7 @@ 6.394 <sect1> 6.395 <title>Mercurial compared with other tools</title> 6.396 6.397 - <para>Before you read on, please understand that this section 6.398 + <para id="x_a5">Before you read on, please understand that this section 6.399 necessarily reflects my own experiences, interests, and (dare I 6.400 say it) biases. I have used every one of the revision control 6.401 tools listed below, in most cases for several years at a 6.402 @@ -422,22 +422,22 @@ 6.403 <sect2> 6.404 <title>Subversion</title> 6.405 6.406 - <para>Subversion is a popular revision control tool, developed 6.407 + <para id="x_a6">Subversion is a popular revision control tool, developed 6.408 to replace CVS. It has a centralised client/server 6.409 architecture.</para> 6.410 6.411 - <para>Subversion and Mercurial have similarly named commands for 6.412 + <para id="x_a7">Subversion and Mercurial have similarly named commands for 6.413 performing the same operations, so if you're familiar with 6.414 one, it is easy to learn to use the other. Both tools are 6.415 portable to all popular operating systems.</para> 6.416 6.417 - <para>Prior to version 1.5, Subversion had no useful support for 6.418 + <para id="x_a8">Prior to version 1.5, Subversion had no useful support for 6.419 merges. At the time of writing, its merge tracking capability 6.420 is new, and known to be <ulink 6.421 url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 6.422 and buggy</ulink>.</para> 6.423 6.424 - <para>Mercurial has a substantial performance advantage over 6.425 + <para id="x_a9">Mercurial has a substantial performance advantage over 6.426 Subversion on every revision control operation I have 6.427 benchmarked. I have measured its advantage as ranging from a 6.428 factor of two to a factor of six when compared with Subversion 6.429 @@ -450,7 +450,7 @@ 6.430 and network bandwidth become bottlenecks for modestly large 6.431 projects.</para> 6.432 6.433 - <para>Additionally, Subversion incurs substantial storage 6.434 + <para id="x_aa">Additionally, Subversion incurs substantial storage 6.435 overhead to avoid network transactions for a few common 6.436 operations, such as finding modified files 6.437 (<literal>status</literal>) and displaying modifications 6.438 @@ -460,13 +460,13 @@ 6.439 even though the Mercurial repository contains a complete 6.440 history of the project.</para> 6.441 6.442 - <para>Subversion is widely supported by third party tools. 6.443 + <para id="x_ab">Subversion is widely supported by third party tools. 6.444 Mercurial currently lags considerably in this area. This gap 6.445 is closing, however, and indeed some of Mercurial's GUI tools 6.446 now outshine their Subversion equivalents. Like Mercurial, 6.447 Subversion has an excellent user manual.</para> 6.448 6.449 - <para>Because Subversion doesn't store revision history on the 6.450 + <para id="x_ac">Because Subversion doesn't store revision history on the 6.451 client, it is well suited to managing projects that deal with 6.452 lots of large, opaque binary files. If you check in fifty 6.453 revisions to an incompressible 10MB file, Subversion's 6.454 @@ -475,14 +475,14 @@ 6.455 of revisions, because the differences between each revision 6.456 are large.</para> 6.457 6.458 - <para>In addition, it's often difficult or, more usually, 6.459 + <para id="x_ad">In addition, it's often difficult or, more usually, 6.460 impossible to merge different versions of a binary file. 6.461 Subversion's ability to let a user lock a file, so that they 6.462 temporarily have the exclusive right to commit changes to it, 6.463 can be a significant advantage to a project where binary files 6.464 are widely used.</para> 6.465 6.466 - <para>Mercurial can import revision history from a Subversion 6.467 + <para id="x_ae">Mercurial can import revision history from a Subversion 6.468 repository. It can also export revision history to a 6.469 Subversion repository. This makes it easy to <quote>test the 6.470 waters</quote> and use Mercurial and Subversion in parallel 6.471 @@ -496,24 +496,24 @@ 6.472 <sect2> 6.473 <title>Git</title> 6.474 6.475 - <para>Git is a distributed revision control tool that was 6.476 + <para id="x_af">Git is a distributed revision control tool that was 6.477 developed for managing the Linux kernel source tree. Like 6.478 Mercurial, its early design was somewhat influenced by 6.479 Monotone.</para> 6.480 6.481 - <para>Git has a very large command set, with version 1.5.0 6.482 + <para id="x_b0">Git has a very large command set, with version 1.5.0 6.483 providing 139 individual commands. It has something of a 6.484 reputation for being difficult to learn. Compared to Git, 6.485 Mercurial has a strong focus on simplicity.</para> 6.486 6.487 - <para>In terms of performance, Git is extremely fast. In 6.488 + <para id="x_b1">In terms of performance, Git is extremely fast. In 6.489 several cases, it is faster than Mercurial, at least on Linux, 6.490 while Mercurial performs better on other operations. However, 6.491 on Windows, the performance and general level of support that 6.492 Git provides is, at the time of writing, far behind that of 6.493 Mercurial.</para> 6.494 6.495 - <para>While a Mercurial repository needs no maintenance, a Git 6.496 + <para id="x_b2">While a Mercurial repository needs no maintenance, a Git 6.497 repository requires frequent manual <quote>repacks</quote> of 6.498 its metadata. Without these, performance degrades, while 6.499 space usage grows rapidly. A server that contains many Git 6.500 @@ -524,13 +524,13 @@ 6.501 slightly smaller than a Mercurial repository, but an unpacked 6.502 repository is several orders of magnitude larger.</para> 6.503 6.504 - <para>The core of Git is written in C. Many Git commands are 6.505 + <para id="x_b3">The core of Git is written in C. Many Git commands are 6.506 implemented as shell or Perl scripts, and the quality of these 6.507 scripts varies widely. I have encountered several instances 6.508 where scripts charged along blindly in the presence of errors 6.509 that should have been fatal.</para> 6.510 6.511 - <para>Mercurial can import revision history from a Git 6.512 + <para id="x_b4">Mercurial can import revision history from a Git 6.513 repository.</para> 6.514 6.515 6.516 @@ -538,11 +538,11 @@ 6.517 <sect2> 6.518 <title>CVS</title> 6.519 6.520 - <para>CVS is probably the most widely used revision control tool 6.521 + <para id="x_b5">CVS is probably the most widely used revision control tool 6.522 in the world. Due to its age and internal untidiness, it has 6.523 been only lightly maintained for many years.</para> 6.524 6.525 - <para>It has a centralised client/server architecture. It does 6.526 + <para id="x_b6">It has a centralised client/server architecture. It does 6.527 not group related file changes into atomic commits, making it 6.528 easy for people to <quote>break the build</quote>: one person 6.529 can successfully commit part of a change and then be blocked 6.530 @@ -554,7 +554,7 @@ 6.531 the changes made to each file involved (if you even know what 6.532 those files were).</para> 6.533 6.534 - <para>CVS has a muddled notion of tags and branches that I will 6.535 + <para id="x_b7">CVS has a muddled notion of tags and branches that I will 6.536 not attempt to even describe. It does not support renaming of 6.537 files or directories well, making it easy to corrupt a 6.538 repository. It has almost no internal consistency checking 6.539 @@ -562,7 +562,7 @@ 6.540 whether or how a repository is corrupt. I would not recommend 6.541 CVS for any project, existing or new.</para> 6.542 6.543 - <para>Mercurial can import CVS revision history. However, there 6.544 + <para id="x_b8">Mercurial can import CVS revision history. However, there 6.545 are a few caveats that apply; these are true of every other 6.546 revision control tool's CVS importer, too. Due to CVS's lack 6.547 of atomic changes and unversioned filesystem hierarchy, it is 6.548 @@ -576,7 +576,7 @@ 6.549 the less interesting problems I can recall from personal 6.550 experience).</para> 6.551 6.552 - <para>Mercurial can import revision history from a CVS 6.553 + <para id="x_b9">Mercurial can import revision history from a CVS 6.554 repository.</para> 6.555 6.556 6.557 @@ -584,13 +584,13 @@ 6.558 <sect2> 6.559 <title>Commercial tools</title> 6.560 6.561 - <para>Perforce has a centralised client/server architecture, 6.562 + <para id="x_ba">Perforce has a centralised client/server architecture, 6.563 with no client-side caching of any data. Unlike modern 6.564 revision control tools, Perforce requires that a user run a 6.565 command to inform the server about every file they intend to 6.566 edit.</para> 6.567 6.568 - <para>The performance of Perforce is quite good for small teams, 6.569 + <para id="x_bb">The performance of Perforce is quite good for small teams, 6.570 but it falls off rapidly as the number of users grows beyond a 6.571 few dozen. Modestly large Perforce installations require the 6.572 deployment of proxies to cope with the load their users 6.573 @@ -601,16 +601,16 @@ 6.574 <sect2> 6.575 <title>Choosing a revision control tool</title> 6.576 6.577 - <para>With the exception of CVS, all of the tools listed above 6.578 + <para id="x_bc">With the exception of CVS, all of the tools listed above 6.579 have unique strengths that suit them to particular styles of 6.580 work. There is no single revision control tool that is best 6.581 in all situations.</para> 6.582 6.583 - <para>As an example, Subversion is a good choice for working 6.584 + <para id="x_bd">As an example, Subversion is a good choice for working 6.585 with frequently edited binary files, due to its centralised 6.586 nature and support for file locking.</para> 6.587 6.588 - <para>I personally find Mercurial's properties of simplicity, 6.589 + <para id="x_be">I personally find Mercurial's properties of simplicity, 6.590 performance, and good merge support to be a compelling 6.591 combination that has served me well for several years.</para> 6.592 6.593 @@ -620,7 +620,7 @@ 6.594 <sect1> 6.595 <title>Switching from another tool to Mercurial</title> 6.596 6.597 - <para>Mercurial is bundled with an extension named <literal 6.598 + <para id="x_bf">Mercurial is bundled with an extension named <literal 6.599 role="hg-ext">convert</literal>, which can incrementally 6.600 import revision history from several other revision control 6.601 tools. By <quote>incremental</quote>, I mean that you can 6.602 @@ -628,21 +628,21 @@ 6.603 the conversion later to obtain new changes that happened after 6.604 the initial conversion.</para> 6.605 6.606 - <para>The revision control tools supported by <literal 6.607 + <para id="x_c0">The revision control tools supported by <literal 6.608 role="hg-ext">convert</literal> are as follows:</para> 6.609 <itemizedlist> 6.610 - <listitem><para>Subversion</para></listitem> 6.611 - <listitem><para>CVS</para></listitem> 6.612 - <listitem><para>Git</para></listitem> 6.613 - <listitem><para>Darcs</para></listitem></itemizedlist> 6.614 - 6.615 - <para>In addition, <literal role="hg-ext">convert</literal> can 6.616 + <listitem><para id="x_c1">Subversion</para></listitem> 6.617 + <listitem><para id="x_c2">CVS</para></listitem> 6.618 + <listitem><para id="x_c3">Git</para></listitem> 6.619 + <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist> 6.620 + 6.621 + <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can 6.622 export changes from Mercurial to Subversion. This makes it 6.623 possible to try Subversion and Mercurial in parallel before 6.624 committing to a switchover, without risking the loss of any 6.625 work.</para> 6.626 6.627 - <para>The <command role="hg-ext-convert">convert</command> command 6.628 + <para id="x_c6">The <command role="hg-ext-convert">convert</command> command 6.629 is easy to use. Simply point it at the path or URL of the 6.630 source repository, optionally give it the name of the 6.631 destination repository, and it will start working. After the 6.632 @@ -653,7 +653,7 @@ 6.633 <sect1> 6.634 <title>A short history of revision control</title> 6.635 6.636 - <para>The best known of the old-time revision control tools is 6.637 + <para id="x_c7">The best known of the old-time revision control tools is 6.638 SCCS (Source Code Control System), which Marc Rochkind wrote at 6.639 Bell Labs, in the early 1970s. SCCS operated on individual 6.640 files, and required every person working on a project to have 6.641 @@ -664,13 +664,13 @@ 6.642 modifying those files without the help of an 6.643 administrator.</para> 6.644 6.645 - <para>Walter Tichy developed a free alternative to SCCS in the 6.646 + <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the 6.647 early 1980s; he called his program RCS (Revision Control System). 6.648 Like SCCS, RCS required developers to work in a single shared 6.649 workspace, and to lock files to prevent multiple people from 6.650 modifying them simultaneously.</para> 6.651 6.652 - <para>Later in the 1980s, Dick Grune used RCS as a building block 6.653 + <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block 6.654 for a set of shell scripts he initially called cmt, but then 6.655 renamed to CVS (Concurrent Versions System). The big innovation 6.656 of CVS was that it let developers work simultaneously and 6.657 @@ -681,7 +681,7 @@ 6.658 their copies independently. They had to merge their edits prior 6.659 to committing changes to the central repository.</para> 6.660 6.661 - <para>Brian Berliner took Grune's original scripts and rewrote 6.662 + <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote 6.663 them in C, releasing in 1989 the code that has since developed 6.664 into the modern version of CVS. CVS subsequently acquired the 6.665 ability to operate over a network connection, giving it a 6.666 @@ -692,14 +692,14 @@ 6.667 server is. CVS has been enormously successful; it is probably 6.668 the world's most widely used revision control system.</para> 6.669 6.670 - <para>In the early 1990s, Sun Microsystems developed an early 6.671 + <para id="x_cb">In the early 1990s, Sun Microsystems developed an early 6.672 distributed revision control system, called TeamWare. A 6.673 TeamWare workspace contains a complete copy of the project's 6.674 history. TeamWare has no notion of a central repository. (CVS 6.675 relied upon RCS for its history storage; TeamWare used 6.676 SCCS.)</para> 6.677 6.678 - <para>As the 1990s progressed, awareness grew of a number of 6.679 + <para id="x_cc">As the 1990s progressed, awareness grew of a number of 6.680 problems with CVS. It records simultaneous changes to multiple 6.681 files individually, instead of grouping them together as a 6.682 single logically atomic operation. It does not manage its file 6.683 @@ -709,7 +709,7 @@ 6.684 level</quote> of fixing these architectural problems 6.685 prohibitive.</para> 6.686 6.687 - <para>In 2001, Jim Blandy and Karl Fogel, two developers who had 6.688 + <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had 6.689 worked on CVS, started a project to replace it with a tool that 6.690 would have a better architecture and cleaner code. The result, 6.691 Subversion, does not stray from CVS's centralised client/server 6.692 @@ -718,7 +718,7 @@ 6.693 generally better tool than CVS. Since its initial release, it 6.694 has rapidly grown in popularity.</para> 6.695 6.696 - <para>More or less simultaneously, Graydon Hoare began working on 6.697 + <para id="x_ce">More or less simultaneously, Graydon Hoare began working on 6.698 an ambitious distributed revision control system that he named 6.699 Monotone. While Monotone addresses many of CVS's design flaws 6.700 and has a peer-to-peer architecture, it goes beyond earlier (and 6.701 @@ -727,7 +727,7 @@ 6.702 integral notion of <quote>trust</quote> for code from different 6.703 sources.</para> 6.704 6.705 - <para>Mercurial began life in 2005. While a few aspects of its 6.706 + <para id="x_cf">Mercurial began life in 2005. While a few aspects of its 6.707 design are influenced by Monotone, Mercurial focuses on ease of 6.708 use, high performance, and scalability to very large 6.709 projects.</para> 6.710 @@ -737,12 +737,12 @@ 6.711 <sect1> 6.712 <title>Colophon&emdash;this book is Free</title> 6.713 6.714 - <para>This book is licensed under the Open Publication License, 6.715 + <para id="x_d0">This book is licensed under the Open Publication License, 6.716 and is produced entirely using Free Software tools. It is 6.717 typeset with DocBook XML. Illustrations are drawn and rendered with 6.718 <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para> 6.719 6.720 - <para>The complete source code for this book is published as a 6.721 + <para id="x_d1">The complete source code for this book is published as a 6.722 Mercurial repository, at <ulink 6.723 url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para> 6.724
7.1 --- a/en/ch01-tour-basic.xml Thu Mar 19 20:54:12 2009 -0700 7.2 +++ b/en/ch01-tour-basic.xml Thu Mar 19 21:18:52 2009 -0700 7.3 @@ -7,21 +7,21 @@ 7.4 <sect1 id="sec:tour:install"> 7.5 <title>Installing Mercurial on your system</title> 7.6 7.7 - <para>Prebuilt binary packages of Mercurial are available for 7.8 + <para id="x_1">Prebuilt binary packages of Mercurial are available for 7.9 every popular operating system. These make it easy to start 7.10 using Mercurial on your computer immediately.</para> 7.11 7.12 <sect2> 7.13 <title>Linux</title> 7.14 7.15 - <para>Because each Linux distribution has its own packaging 7.16 + <para id="x_2">Because each Linux distribution has its own packaging 7.17 tools, policies, and rate of development, it's difficult to 7.18 give a comprehensive set of instructions on how to install 7.19 Mercurial binaries. The version of Mercurial that you will 7.20 end up with can vary depending on how active the person is who 7.21 maintains the package for your distribution.</para> 7.22 7.23 - <para>To keep things simple, I will focus on installing 7.24 + <para id="x_3">To keep things simple, I will focus on installing 7.25 Mercurial from the command line under the most popular Linux 7.26 distributions. Most of these distributions provide graphical 7.27 package managers that will let you install Mercurial with a 7.28 @@ -29,15 +29,15 @@ 7.29 <literal>mercurial</literal>.</para> 7.30 7.31 <itemizedlist> 7.32 - <listitem><para>Debian:</para> 7.33 + <listitem><para id="x_4">Debian:</para> 7.34 <programlisting>apt-get install mercurial</programlisting></listitem> 7.35 - <listitem><para>Fedora Core:</para> 7.36 + <listitem><para id="x_5">Fedora Core:</para> 7.37 <programlisting>yum install mercurial</programlisting></listitem> 7.38 - <listitem><para>Gentoo:</para> 7.39 + <listitem><para id="x_6">Gentoo:</para> 7.40 <programlisting>emerge mercurial</programlisting></listitem> 7.41 - <listitem><para>OpenSUSE:</para> 7.42 + <listitem><para id="x_7">OpenSUSE:</para> 7.43 <programlisting>yum install mercurial</programlisting></listitem> 7.44 - <listitem><para>Ubuntu: Ubuntu's Mercurial package is based on 7.45 + <listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on 7.46 Debian's. To install it, run the following 7.47 command.</para> 7.48 <programlisting>apt-get install mercurial</programlisting></listitem> 7.49 @@ -47,7 +47,7 @@ 7.50 <sect2> 7.51 <title>Solaris</title> 7.52 7.53 - <para>SunFreeWare, at <ulink 7.54 + <para id="x_9">SunFreeWare, at <ulink 7.55 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 7.56 is a good source for a large number of pre-built Solaris 7.57 packages for 32 and 64 bit Intel and Sparc architectures, 7.58 @@ -57,7 +57,7 @@ 7.59 <sect2> 7.60 <title>Mac OS X</title> 7.61 7.62 - <para>Lee Cantey publishes an installer of Mercurial for Mac OS 7.63 + <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS 7.64 X at <ulink 7.65 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 7.66 This package works on both Intel- and Power-based Macs. Before 7.67 @@ -66,7 +66,7 @@ 7.68 is easy to do; simply follow the instructions on Lee's 7.69 site.</para> 7.70 7.71 - <para>It's also possible to install Mercurial using Fink or 7.72 + <para id="x_b">It's also possible to install Mercurial using Fink or 7.73 MacPorts, two popular free package managers for Mac OS X. If 7.74 you have Fink, use <command>sudo apt-get install 7.75 mercurial-py25</command>. If MacPorts, <command>sudo port 7.76 @@ -76,14 +76,14 @@ 7.77 <sect2> 7.78 <title>Windows</title> 7.79 7.80 - <para>Lee Cantey publishes an installer of Mercurial for Windows 7.81 + <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows 7.82 at <ulink 7.83 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 7.84 This package has no external dependencies; it <quote>just 7.85 works</quote>.</para> 7.86 7.87 <note> 7.88 - <para> The Windows version of Mercurial does not 7.89 + <para id="x_d"> The Windows version of Mercurial does not 7.90 automatically convert line endings between Windows and Unix 7.91 styles. If you want to share work with Unix users, you must 7.92 do a little additional configuration work. XXX Flesh this 7.93 @@ -95,7 +95,7 @@ 7.94 <sect1> 7.95 <title>Getting started</title> 7.96 7.97 - <para>To begin, we'll use the <command role="hg-cmd">hg 7.98 + <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg 7.99 version</command> command to find out whether Mercurial is 7.100 actually installed properly. The actual version information 7.101 that it prints isn't so important; it's whether it prints 7.102 @@ -106,7 +106,7 @@ 7.103 <sect2> 7.104 <title>Built-in help</title> 7.105 7.106 - <para>Mercurial provides a built-in help system. This is 7.107 + <para id="x_f">Mercurial provides a built-in help system. This is 7.108 invaluable for those times when you find yourself stuck 7.109 trying to remember how to run a command. If you are 7.110 completely stuck, simply run <command role="hg-cmd">hg 7.111 @@ -117,7 +117,7 @@ 7.112 7.113 &interaction.tour.help; 7.114 7.115 - <para>For a more impressive level of detail (which you won't 7.116 + <para id="x_10">For a more impressive level of detail (which you won't 7.117 usually need) run <command role="hg-cmd">hg help <option 7.118 role="hg-opt-global">-v</option></command>. The <option 7.119 role="hg-opt-global">-v</option> option is short for 7.120 @@ -130,13 +130,13 @@ 7.121 <sect1> 7.122 <title>Working with a repository</title> 7.123 7.124 - <para>In Mercurial, everything happens inside a 7.125 + <para id="x_11">In Mercurial, everything happens inside a 7.126 <emphasis>repository</emphasis>. The repository for a project 7.127 contains all of the files that <quote>belong to</quote> that 7.128 project, along with a historical record of the project's 7.129 files.</para> 7.130 7.131 - <para>There's nothing particularly magical about a repository; it 7.132 + <para id="x_12">There's nothing particularly magical about a repository; it 7.133 is simply a directory tree in your filesystem that Mercurial 7.134 treats as special. You can rename or delete a repository any 7.135 time you like, using either the command line or your file 7.136 @@ -145,7 +145,7 @@ 7.137 <sect2> 7.138 <title>Making a local copy of a repository</title> 7.139 7.140 - <para><emphasis>Copying</emphasis> a repository is just a little 7.141 + <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little 7.142 bit special. While you could use a normal file copying 7.143 command to make a copy of a repository, it's best to use a 7.144 built-in command that Mercurial provides. This command is 7.145 @@ -154,23 +154,23 @@ 7.146 7.147 &interaction.tour.clone; 7.148 7.149 - <para>If our clone succeeded, we should now have a local 7.150 + <para id="x_14">If our clone succeeded, we should now have a local 7.151 directory called <filename class="directory">hello</filename>. 7.152 This directory will contain some files.</para> 7.153 7.154 &interaction.tour.ls; 7.155 7.156 - <para>These files have the same contents and history in our 7.157 + <para id="x_15">These files have the same contents and history in our 7.158 repository as they do in the repository we cloned.</para> 7.159 7.160 - <para>Every Mercurial repository is complete, self-contained, 7.161 + <para id="x_16">Every Mercurial repository is complete, self-contained, 7.162 and independent. It contains its own private copy of a 7.163 project's files and history. A cloned repository remembers 7.164 the location of the repository it was cloned from, but it does 7.165 not communicate with that repository, or any other, unless you 7.166 tell it to.</para> 7.167 7.168 - <para>What this means for now is that we're free to experiment 7.169 + <para id="x_17">What this means for now is that we're free to experiment 7.170 with our repository, safe in the knowledge that it's a private 7.171 <quote>sandbox</quote> that won't affect anyone else.</para> 7.172 7.173 @@ -178,20 +178,20 @@ 7.174 <sect2> 7.175 <title>What's in a repository?</title> 7.176 7.177 - <para>When we take a more detailed look inside a repository, we 7.178 + <para id="x_18">When we take a more detailed look inside a repository, we 7.179 can see that it contains a directory named <filename 7.180 class="directory">.hg</filename>. This is where Mercurial 7.181 keeps all of its metadata for the repository.</para> 7.182 7.183 &interaction.tour.ls-a; 7.184 7.185 - <para>The contents of the <filename 7.186 + <para id="x_19">The contents of the <filename 7.187 class="directory">.hg</filename> directory and its 7.188 subdirectories are private to Mercurial. Every other file and 7.189 directory in the repository is yours to do with as you 7.190 please.</para> 7.191 7.192 - <para>To introduce a little terminology, the <filename 7.193 + <para id="x_1a">To introduce a little terminology, the <filename 7.194 class="directory">.hg</filename> directory is the 7.195 <quote>real</quote> repository, and all of the files and 7.196 directories that coexist with it are said to live in the 7.197 @@ -208,45 +208,45 @@ 7.198 <sect1> 7.199 <title>A tour through history</title> 7.200 7.201 - <para>One of the first things we might want to do with a new, 7.202 + <para id="x_1b">One of the first things we might want to do with a new, 7.203 unfamiliar repository is understand its history. The <command 7.204 role="hg-cmd">hg log</command> command gives us a view of 7.205 history.</para> 7.206 7.207 &interaction.tour.log; 7.208 7.209 - <para>By default, this command prints a brief paragraph of output 7.210 + <para id="x_1c">By default, this command prints a brief paragraph of output 7.211 for each change to the project that was recorded. In Mercurial 7.212 terminology, we call each of these recorded events a 7.213 <emphasis>changeset</emphasis>, because it can contain a record 7.214 of changes to several files.</para> 7.215 7.216 - <para>The fields in a record of output from <command 7.217 + <para id="x_1d">The fields in a record of output from <command 7.218 role="hg-cmd">hg log</command> are as follows.</para> 7.219 <itemizedlist> 7.220 - <listitem><para><literal>changeset</literal>: This field has the 7.221 + <listitem><para id="x_1e"><literal>changeset</literal>: This field has the 7.222 format of a number, followed by a colon, followed by a 7.223 hexadecimal string. These are 7.224 <emphasis>identifiers</emphasis> for the changeset. There 7.225 are two identifiers because the number is shorter and easier 7.226 to type than the hex string.</para></listitem> 7.227 - <listitem><para><literal>user</literal>: The identity of the 7.228 + <listitem><para id="x_1f"><literal>user</literal>: The identity of the 7.229 person who created the changeset. This is a free-form 7.230 field, but it most often contains a person's name and email 7.231 address.</para></listitem> 7.232 - <listitem><para><literal>date</literal>: The date and time on 7.233 + <listitem><para id="x_20"><literal>date</literal>: The date and time on 7.234 which the changeset was created, and the timezone in which 7.235 it was created. (The date and time are local to that 7.236 timezone; they display what time and date it was for the 7.237 person who created the changeset.)</para></listitem> 7.238 - <listitem><para><literal>summary</literal>: The first line of 7.239 + <listitem><para id="x_21"><literal>summary</literal>: The first line of 7.240 the text message that the creator of the changeset entered 7.241 to describe the changeset.</para></listitem></itemizedlist> 7.242 - <para>The default output printed by <command role="hg-cmd">hg 7.243 + <para id="x_22">The default output printed by <command role="hg-cmd">hg 7.244 log</command> is purely a summary; it is missing a lot of 7.245 detail.</para> 7.246 7.247 - <para>Figure <xref linkend="fig:tour-basic:history"/> provides a 7.248 + <para id="x_23">Figure <xref linkend="fig:tour-basic:history"/> provides a 7.249 graphical representation of the history of the <filename 7.250 class="directory">hello</filename> repository, to make it a 7.251 little easier to see which direction history is 7.252 @@ -258,7 +258,7 @@ 7.253 <mediaobject> 7.254 <imageobject><imagedata fileref="tour-history"/></imageobject> 7.255 <textobject><phrase>XXX add text</phrase></textobject> 7.256 - <caption><para>Graphical history of the <filename 7.257 + <caption><para id="x_24">Graphical history of the <filename 7.258 class="directory">hello</filename> 7.259 repository</para></caption> 7.260 </mediaobject> 7.261 @@ -268,7 +268,7 @@ 7.262 <title>Changesets, revisions, and talking to other 7.263 people</title> 7.264 7.265 - <para>As English is a notoriously sloppy language, and computer 7.266 + <para id="x_25">As English is a notoriously sloppy language, and computer 7.267 science has a hallowed history of terminological confusion 7.268 (why use one term when four will do?), revision control has a 7.269 variety of words and phrases that mean the same thing. If you 7.270 @@ -278,7 +278,7 @@ 7.271 <quote>cset</quote>, and sometimes a changeset is referred to 7.272 as a <quote>revision</quote> or a <quote>rev</quote>.</para> 7.273 7.274 - <para>While it doesn't matter what <emphasis>word</emphasis> you 7.275 + <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you 7.276 use to refer to the concept of <quote>a changeset</quote>, the 7.277 <emphasis>identifier</emphasis> that you use to refer to 7.278 <quote>a <emphasis>specific</emphasis> changeset</quote> is of 7.279 @@ -287,14 +287,14 @@ 7.280 log</command> identifies a changeset using both a number and 7.281 a hexadecimal string.</para> 7.282 <itemizedlist> 7.283 - <listitem><para>The revision number is <emphasis>only valid in 7.284 + <listitem><para id="x_27">The revision number is <emphasis>only valid in 7.285 that repository</emphasis>,</para></listitem> 7.286 - <listitem><para>while the hex string is the 7.287 + <listitem><para id="x_28">while the hex string is the 7.288 <emphasis>permanent, unchanging identifier</emphasis> that 7.289 will always identify that exact changeset in 7.290 <emphasis>every</emphasis> copy of the 7.291 repository.</para></listitem></itemizedlist> 7.292 - <para>This distinction is important. If you send someone an 7.293 + <para id="x_29">This distinction is important. If you send someone an 7.294 email talking about <quote>revision 33</quote>, there's a high 7.295 likelihood that their revision 33 will <emphasis>not be the 7.296 same</emphasis> as yours. The reason for this is that a 7.297 @@ -304,7 +304,7 @@ 7.298 repositories. Three changes $a,b,c$ can easily appear in one 7.299 repository as $0,1,2$, while in another as $1,0,2$.</para> 7.300 7.301 - <para>Mercurial uses revision numbers purely as a convenient 7.302 + <para id="x_2a">Mercurial uses revision numbers purely as a convenient 7.303 shorthand. If you need to discuss a changeset with someone, 7.304 or make a record of a changeset for some other reason (for 7.305 example, in a bug report), use the hexadecimal 7.306 @@ -314,7 +314,7 @@ 7.307 <sect2> 7.308 <title>Viewing specific revisions</title> 7.309 7.310 - <para>To narrow the output of <command role="hg-cmd">hg 7.311 + <para id="x_2b">To narrow the output of <command role="hg-cmd">hg 7.312 log</command> down to a single revision, use the <option 7.313 role="hg-opt-log">-r</option> (or <option 7.314 role="hg-opt-log">--rev</option>) option. You can use 7.315 @@ -323,7 +323,7 @@ 7.316 7.317 &interaction.tour.log-r; 7.318 7.319 - <para>If you want to see the history of several revisions 7.320 + <para id="x_2c">If you want to see the history of several revisions 7.321 without having to list each one, you can use <emphasis>range 7.322 notation</emphasis>; this lets you express the idea <quote>I 7.323 want all revisions between <literal>abc</literal> and 7.324 @@ -331,7 +331,7 @@ 7.325 7.326 &interaction.tour.log.range; 7.327 7.328 - <para>Mercurial also honours the order in which you specify 7.329 + <para id="x_2d">Mercurial also honours the order in which you specify 7.330 revisions, so <command role="hg-cmd">hg log -r 2:4</command> 7.331 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r 7.332 4:2</command> prints 4, 3, and 2.</para> 7.333 @@ -340,7 +340,7 @@ 7.334 <sect2> 7.335 <title>More detailed information</title> 7.336 7.337 - <para>While the summary information printed by <command 7.338 + <para id="x_2e">While the summary information printed by <command 7.339 role="hg-cmd">hg log</command> is useful if you already know 7.340 what you're looking for, you may need to see a complete 7.341 description of the change, or a list of the files changed, if 7.342 @@ -352,7 +352,7 @@ 7.343 7.344 &interaction.tour.log-v; 7.345 7.346 - <para>If you want to see both the description and content of a 7.347 + <para id="x_2f">If you want to see both the description and content of a 7.348 change, add the <option role="hg-opt-log">-p</option> (or 7.349 <option role="hg-opt-log">--patch</option>) option. This 7.350 displays the content of a change as a <emphasis>unified 7.351 @@ -367,39 +367,39 @@ 7.352 <sect1> 7.353 <title>All about command options</title> 7.354 7.355 - <para>Let's take a brief break from exploring Mercurial commands 7.356 + <para id="x_30">Let's take a brief break from exploring Mercurial commands 7.357 to discuss a pattern in the way that they work; you may find 7.358 this useful to keep in mind as we continue our tour.</para> 7.359 7.360 - <para>Mercurial has a consistent and straightforward approach to 7.361 + <para id="x_31">Mercurial has a consistent and straightforward approach to 7.362 dealing with the options that you can pass to commands. It 7.363 follows the conventions for options that are common to modern 7.364 Linux and Unix systems.</para> 7.365 <itemizedlist> 7.366 - <listitem><para>Every option has a long name. For example, as 7.367 + <listitem><para id="x_32">Every option has a long name. For example, as 7.368 we've already seen, the <command role="hg-cmd">hg 7.369 log</command> command accepts a <option 7.370 role="hg-opt-log">--rev</option> option.</para></listitem> 7.371 - <listitem><para>Most options have short names, too. Instead of 7.372 + <listitem><para id="x_33">Most options have short names, too. Instead of 7.373 <option role="hg-opt-log">--rev</option>, we can use <option 7.374 role="hg-opt-log">-r</option>. (The reason that some 7.375 options don't have short names is that the options in 7.376 question are rarely used.)</para></listitem> 7.377 - <listitem><para>Long options start with two dashes (e.g. <option 7.378 + <listitem><para id="x_34">Long options start with two dashes (e.g. <option 7.379 role="hg-opt-log">--rev</option>), while short options 7.380 start with one (e.g. <option 7.381 role="hg-opt-log">-r</option>).</para></listitem> 7.382 - <listitem><para>Option naming and usage is consistent across 7.383 + <listitem><para id="x_35">Option naming and usage is consistent across 7.384 commands. For example, every command that lets you specify 7.385 a changeset ID or revision number accepts both <option 7.386 role="hg-opt-log">-r</option> and <option 7.387 role="hg-opt-log">--rev</option> 7.388 arguments.</para></listitem></itemizedlist> 7.389 - <para>In the examples throughout this book, I use short options 7.390 + <para id="x_36">In the examples throughout this book, I use short options 7.391 instead of long. This just reflects my own preference, so don't 7.392 read anything significant into it.</para> 7.393 7.394 - <para>Most commands that print output of some kind will print more 7.395 + <para id="x_37">Most commands that print output of some kind will print more 7.396 output when passed a <option role="hg-opt-global">-v</option> 7.397 (or <option role="hg-opt-global">--verbose</option>) option, and 7.398 less when passed <option role="hg-opt-global">-q</option> (or 7.399 @@ -409,11 +409,11 @@ 7.400 <sect1> 7.401 <title>Making and reviewing changes</title> 7.402 7.403 - <para>Now that we have a grasp of viewing history in Mercurial, 7.404 + <para id="x_38">Now that we have a grasp of viewing history in Mercurial, 7.405 let's take a look at making some changes and examining 7.406 them.</para> 7.407 7.408 - <para>The first thing we'll do is isolate our experiment in a 7.409 + <para id="x_39">The first thing we'll do is isolate our experiment in a 7.410 repository of its own. We use the <command role="hg-cmd">hg 7.411 clone</command> command, but we don't need to clone a copy of 7.412 the remote repository. Since we already have a copy of it 7.413 @@ -423,7 +423,7 @@ 7.414 7.415 &interaction.tour.reclone; 7.416 7.417 - <para>As an aside, it's often good practice to keep a 7.418 + <para id="x_3a">As an aside, it's often good practice to keep a 7.419 <quote>pristine</quote> copy of a remote repository around, 7.420 which you can then make temporary clones of to create sandboxes 7.421 for each task you want to work on. This lets you work on 7.422 @@ -432,7 +432,7 @@ 7.423 local clones are so cheap, there's almost no overhead to cloning 7.424 and destroying repositories whenever you want.</para> 7.425 7.426 - <para>In our <filename class="directory">my-hello</filename> 7.427 + <para id="x_3b">In our <filename class="directory">my-hello</filename> 7.428 repository, we have a file <filename>hello.c</filename> that 7.429 contains the classic <quote>hello, world</quote> program. Let's 7.430 use the ancient and venerable <command>sed</command> command to 7.431 @@ -445,20 +445,20 @@ 7.432 7.433 &interaction.tour.sed; 7.434 7.435 - <para>Mercurial's <command role="hg-cmd">hg status</command> 7.436 + <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> 7.437 command will tell us what Mercurial knows about the files in the 7.438 repository.</para> 7.439 7.440 &interaction.tour.status; 7.441 7.442 - <para>The <command role="hg-cmd">hg status</command> command 7.443 + <para id="x_3d">The <command role="hg-cmd">hg status</command> command 7.444 prints no output for some files, but a line starting with 7.445 <quote><literal>M</literal></quote> for 7.446 <filename>hello.c</filename>. Unless you tell it to, <command 7.447 role="hg-cmd">hg status</command> will not print any output 7.448 for files that have not been modified.</para> 7.449 7.450 - <para>The <quote><literal>M</literal></quote> indicates that 7.451 + <para id="x_3e">The <quote><literal>M</literal></quote> indicates that 7.452 Mercurial has noticed that we modified 7.453 <filename>hello.c</filename>. We didn't need to 7.454 <emphasis>inform</emphasis> Mercurial that we were going to 7.455 @@ -466,7 +466,7 @@ 7.456 file after we were done; it was able to figure this out 7.457 itself.</para> 7.458 7.459 - <para>It's a little bit helpful to know that we've modified 7.460 + <para id="x_3f">It's a little bit helpful to know that we've modified 7.461 <filename>hello.c</filename>, but we might prefer to know 7.462 exactly <emphasis>what</emphasis> changes we've made to it. To 7.463 do this, we use the <command role="hg-cmd">hg diff</command> 7.464 @@ -478,14 +478,14 @@ 7.465 <sect1> 7.466 <title>Recording changes in a new changeset</title> 7.467 7.468 - <para>We can modify files, build and test our changes, and use 7.469 + <para id="x_40">We can modify files, build and test our changes, and use 7.470 <command role="hg-cmd">hg status</command> and <command 7.471 role="hg-cmd">hg diff</command> to review our changes, until 7.472 we're satisfied with what we've done and arrive at a natural 7.473 stopping point where we want to record our work in a new 7.474 changeset.</para> 7.475 7.476 - <para>The <command role="hg-cmd">hg commit</command> command lets 7.477 + <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets 7.478 us create a new changeset; we'll usually refer to this as 7.479 <quote>making a commit</quote> or 7.480 <quote>committing</quote>.</para> 7.481 @@ -493,7 +493,7 @@ 7.482 <sect2> 7.483 <title>Setting up a username</title> 7.484 7.485 - <para>When you try to run <command role="hg-cmd">hg 7.486 + <para id="x_42">When you try to run <command role="hg-cmd">hg 7.487 commit</command> for the first time, it is not guaranteed to 7.488 succeed. Mercurial records your name and address with each 7.489 change that you commit, so that you and others will later be 7.490 @@ -502,36 +502,36 @@ 7.491 change with. It will attempt each of the following methods, 7.492 in order:</para> 7.493 <orderedlist> 7.494 - <listitem><para>If you specify a <option 7.495 + <listitem><para id="x_43">If you specify a <option 7.496 role="hg-opt-commit">-u</option> option to the <command 7.497 role="hg-cmd">hg commit</command> command on the command 7.498 line, followed by a username, this is always given the 7.499 highest precedence.</para></listitem> 7.500 - <listitem><para>If you have set the <envar>HGUSER</envar> 7.501 + <listitem><para id="x_44">If you have set the <envar>HGUSER</envar> 7.502 environment variable, this is checked 7.503 next.</para></listitem> 7.504 - <listitem><para>If you create a file in your home directory 7.505 + <listitem><para id="x_45">If you create a file in your home directory 7.506 called <filename role="special">.hgrc</filename>, with a 7.507 <envar role="rc-item-ui">username</envar> entry, that will 7.508 be used next. To see what the contents of this file 7.509 should look like, refer to section <xref 7.510 linkend="sec:tour-basic:username"/> 7.511 below.</para></listitem> 7.512 - <listitem><para>If you have set the <envar>EMAIL</envar> 7.513 + <listitem><para id="x_46">If you have set the <envar>EMAIL</envar> 7.514 environment variable, this will be used 7.515 next.</para></listitem> 7.516 - <listitem><para>Mercurial will query your system to find out 7.517 + <listitem><para id="x_47">Mercurial will query your system to find out 7.518 your local user name and host name, and construct a 7.519 username from these components. Since this often results 7.520 in a username that is not very useful, it will print a 7.521 warning if it has to do 7.522 this.</para></listitem> 7.523 </orderedlist> 7.524 - <para>If all of these mechanisms fail, Mercurial will 7.525 + <para id="x_48">If all of these mechanisms fail, Mercurial will 7.526 fail, printing an error message. In this case, it will not 7.527 let you commit until you set up a 7.528 username.</para> 7.529 - <para>You should think of the <envar>HGUSER</envar> environment 7.530 + <para id="x_49">You should think of the <envar>HGUSER</envar> environment 7.531 variable and the <option role="hg-opt-commit">-u</option> 7.532 option to the <command role="hg-cmd">hg commit</command> 7.533 command as ways to <emphasis>override</emphasis> Mercurial's 7.534 @@ -542,7 +542,7 @@ 7.535 <sect3 id="sec:tour-basic:username"> 7.536 <title>Creating a Mercurial configuration file</title> 7.537 7.538 - <para>To set a user name, use your favourite editor 7.539 + <para id="x_4a">To set a user name, use your favourite editor 7.540 to create a file called <filename 7.541 role="special">.hgrc</filename> in your home directory. 7.542 Mercurial will use this file to look up your personalised 7.543 @@ -554,7 +554,7 @@ 7.544 username = Firstname Lastname 7.545 <email.address@domain.net></programlisting> 7.546 7.547 - <para>The <quote><literal>[ui]</literal></quote> line begins a 7.548 + <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a 7.549 <emphasis>section</emphasis> of the config file, so you can 7.550 read the <quote><literal>username = ...</literal></quote> 7.551 line as meaning <quote>set the value of the 7.552 @@ -569,14 +569,14 @@ 7.553 <sect3> 7.554 <title>Choosing a user name</title> 7.555 7.556 - <para>You can use any text you like as the value of 7.557 + <para id="x_4c">You can use any text you like as the value of 7.558 the <literal>username</literal> config item, since this 7.559 information is for reading by other people, but for 7.560 interpreting by Mercurial. The convention that most 7.561 people follow is to use their name and email address, as 7.562 in the example above.</para> 7.563 <note> 7.564 - <para>Mercurial's built-in web server obfuscates 7.565 + <para id="x_4d">Mercurial's built-in web server obfuscates 7.566 email addresses, to make it more difficult for the email 7.567 harvesting tools that spammers use. This reduces the 7.568 likelihood that you'll start receiving more junk email 7.569 @@ -588,7 +588,7 @@ 7.570 <sect2> 7.571 <title>Writing a commit message</title> 7.572 7.573 - <para>When we commit a change, Mercurial drops us into 7.574 + <para id="x_4e">When we commit a change, Mercurial drops us into 7.575 a text editor, to enter a message that will describe the 7.576 modifications we've made in this changeset. This is called 7.577 the <emphasis>commit message</emphasis>. It will be a 7.578 @@ -598,14 +598,14 @@ 7.579 7.580 &interaction.tour.commit; 7.581 7.582 - <para>The editor that the <command role="hg-cmd">hg 7.583 + <para id="x_4f">The editor that the <command role="hg-cmd">hg 7.584 commit</command> command drops us into will contain an 7.585 empty line, followed by a number of lines starting with 7.586 <quote><literal>HG:</literal></quote>.</para> 7.587 7.588 <programlisting>XXX fix this XXX</programlisting> 7.589 7.590 - <para>Mercurial ignores the lines that start with 7.591 + <para id="x_50">Mercurial ignores the lines that start with 7.592 <quote><literal>HG:</literal></quote>; it uses them only to 7.593 tell us which files it's recording changes to. Modifying or 7.594 deleting these lines has no effect.</para> 7.595 @@ -613,7 +613,7 @@ 7.596 <sect2> 7.597 <title>Writing a good commit message</title> 7.598 7.599 - <para>Since <command role="hg-cmd">hg log</command> 7.600 + <para id="x_51">Since <command role="hg-cmd">hg log</command> 7.601 only prints the first line of a commit message by default, 7.602 it's best to write a commit message whose first line stands 7.603 alone. Here's a real example of a commit message that 7.604 @@ -627,13 +627,13 @@ 7.605 date: Tue Sep 26 21:37:07 2006 -0700 7.606 summary: include buildmeister/commondefs. Add exports.</programlisting> 7.607 7.608 - <para>As far as the remainder of the contents of the 7.609 + <para id="x_52">As far as the remainder of the contents of the 7.610 commit message are concerned, there are no hard-and-fast 7.611 rules. Mercurial itself doesn't interpret or care about the 7.612 contents of the commit message, though your project may have 7.613 policies that dictate a certain kind of 7.614 formatting.</para> 7.615 - <para>My personal preference is for short, but 7.616 + <para id="x_53">My personal preference is for short, but 7.617 informative, commit messages that tell me something that I 7.618 can't figure out with a quick glance at the output of 7.619 <command role="hg-cmd">hg log 7.620 @@ -642,12 +642,12 @@ 7.621 <sect2> 7.622 <title>Aborting a commit</title> 7.623 7.624 - <para>If you decide that you don't want to commit 7.625 + <para id="x_54">If you decide that you don't want to commit 7.626 while in the middle of editing a commit message, simply exit 7.627 from your editor without saving the file that it's editing. 7.628 This will cause nothing to happen to either the repository 7.629 or the working directory.</para> 7.630 - <para>If we run the <command role="hg-cmd">hg 7.631 + <para id="x_55">If we run the <command role="hg-cmd">hg 7.632 commit</command> command without any arguments, it records 7.633 all of the changes we've made, as reported by <command 7.634 role="hg-cmd">hg status</command> and <command 7.635 @@ -656,7 +656,7 @@ 7.636 <sect2> 7.637 <title>Admiring our new handiwork</title> 7.638 7.639 - <para>Once we've finished the commit, we can use the 7.640 + <para id="x_56">Once we've finished the commit, we can use the 7.641 <command role="hg-cmd">hg tip</command> command to display 7.642 the changeset we just created. This command produces output 7.643 that is identical to <command role="hg-cmd">hg 7.644 @@ -665,7 +665,7 @@ 7.645 7.646 &interaction.tour.tip; 7.647 7.648 - <para>We refer to 7.649 + <para id="x_57">We refer to 7.650 the newest revision in the repository as the tip revision, 7.651 or simply the tip.</para> 7.652 </sect2> 7.653 @@ -674,7 +674,7 @@ 7.654 <sect1> 7.655 <title>Sharing changes</title> 7.656 7.657 - <para>We mentioned earlier that repositories in 7.658 + <para id="x_58">We mentioned earlier that repositories in 7.659 Mercurial are self-contained. This means that the changeset 7.660 we just created exists only in our <filename 7.661 class="directory">my-hello</filename> repository. Let's 7.662 @@ -683,7 +683,7 @@ 7.663 7.664 <sect2 id="sec:tour:pull"> 7.665 <title>Pulling changes from another repository</title> 7.666 - <para>To get started, let's clone our original 7.667 + <para id="x_59">To get started, let's clone our original 7.668 <filename class="directory">hello</filename> repository, 7.669 which does not contain the change we just committed. We'll 7.670 call our temporary repository <filename 7.671 @@ -691,7 +691,7 @@ 7.672 7.673 &interaction.tour.clone-pull; 7.674 7.675 - <para>We'll use the <command role="hg-cmd">hg 7.676 + <para id="x_5a">We'll use the <command role="hg-cmd">hg 7.677 pull</command> command to bring changes from <filename 7.678 class="directory">my-hello</filename> into <filename 7.679 class="directory">hello-pull</filename>. However, blindly 7.680 @@ -704,21 +704,21 @@ 7.681 7.682 &interaction.tour.incoming; 7.683 7.684 - <para>(Of course, someone could 7.685 + <para id="x_5b">(Of course, someone could 7.686 cause more changesets to appear in the repository that we 7.687 ran <command role="hg-cmd">hg incoming</command> in, before 7.688 we get a chance to <command role="hg-cmd">hg pull</command> 7.689 the changes, so that we could end up pulling changes that we 7.690 didn't expect.)</para> 7.691 7.692 - <para>Bringing changes into a repository is a simple 7.693 + <para id="x_5c">Bringing changes into a repository is a simple 7.694 matter of running the <command role="hg-cmd">hg 7.695 pull</command> command, and telling it which repository to 7.696 pull from.</para> 7.697 7.698 &interaction.tour.pull; 7.699 7.700 - <para>As you can see 7.701 + <para id="x_5d">As you can see 7.702 from the before-and-after output of <command 7.703 role="hg-cmd">hg tip</command>, we have successfully 7.704 pulled changes into our repository. There remains one step 7.705 @@ -728,7 +728,7 @@ 7.706 <sect2> 7.707 <title>Updating the working directory</title> 7.708 7.709 - <para>We have so far glossed over the relationship between a 7.710 + <para id="x_5e">We have so far glossed over the relationship between a 7.711 repository and its working directory. The <command 7.712 role="hg-cmd">hg pull</command> command that we ran in 7.713 section <xref linkend="sec:tour:pull"/> brought changes 7.714 @@ -740,7 +740,7 @@ 7.715 7.716 &interaction.tour.update; 7.717 7.718 - <para>It might seem a bit strange that <command role="hg-cmd">hg 7.719 + <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg 7.720 pull</command> doesn't update the working directory 7.721 automatically. There's actually a good reason for this: you 7.722 can use <command role="hg-cmd">hg update</command> to update 7.723 @@ -751,12 +751,12 @@ 7.724 role="hg-cmd">hg pull</command> which automatically updated 7.725 the working directory to a new revision, you might not be 7.726 terribly happy.</para> 7.727 - <para>However, since pull-then-update is such a common thing to 7.728 + <para id="x_60">However, since pull-then-update is such a common thing to 7.729 do, Mercurial lets you combine the two by passing the <option 7.730 role="hg-opt-pull">-u</option> option to <command 7.731 role="hg-cmd">hg pull</command>.</para> 7.732 7.733 - <para>If you look back at the output of <command 7.734 + <para id="x_61">If you look back at the output of <command 7.735 role="hg-cmd">hg pull</command> in section <xref 7.736 linkend="sec:tour:pull"/> when we ran it without <option 7.737 role="hg-opt-pull">-u</option>, you can see that it printed 7.738 @@ -765,13 +765,13 @@ 7.739 7.740 <!-- &interaction.xxx.fixme; --> 7.741 7.742 - <para>To find out what revision the working directory is at, use 7.743 + <para id="x_62">To find out what revision the working directory is at, use 7.744 the <command role="hg-cmd">hg parents</command> 7.745 command.</para> 7.746 7.747 &interaction.tour.parents; 7.748 7.749 - <para>If you look back at figure <xref 7.750 + <para id="x_63">If you look back at figure <xref 7.751 linkend="fig:tour-basic:history"/>, 7.752 you'll see arrows connecting each changeset. The node that 7.753 the arrow leads <emphasis>from</emphasis> in each case is a 7.754 @@ -780,14 +780,14 @@ 7.755 has a parent in just the same way; this is the changeset that 7.756 the working directory currently contains.</para> 7.757 7.758 - <para>To update the working directory to a particular revision, 7.759 + <para id="x_64">To update the working directory to a particular revision, 7.760 7.761 give a revision number or changeset ID to the <command 7.762 role="hg-cmd">hg update</command> command.</para> 7.763 7.764 &interaction.tour.older; 7.765 7.766 - <para>If you omit an explicit revision, <command 7.767 + <para id="x_65">If you omit an explicit revision, <command 7.768 role="hg-cmd">hg update</command> will update to the tip 7.769 revision, as shown by the second call to <command 7.770 role="hg-cmd">hg update</command> in the example 7.771 @@ -797,7 +797,7 @@ 7.772 <sect2> 7.773 <title>Pushing changes to another repository</title> 7.774 7.775 - <para>Mercurial lets us push changes to another 7.776 + <para id="x_66">Mercurial lets us push changes to another 7.777 repository, from the repository we're currently visiting. 7.778 As with the example of <command role="hg-cmd">hg 7.779 pull</command> above, we'll create a temporary repository 7.780 @@ -805,19 +805,19 @@ 7.781 7.782 &interaction.tour.clone-push; 7.783 7.784 - <para>The <command role="hg-cmd">hg outgoing</command> command 7.785 + <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command 7.786 tells us what changes would be pushed into another 7.787 repository.</para> 7.788 7.789 &interaction.tour.outgoing; 7.790 7.791 - <para>And the 7.792 + <para id="x_68">And the 7.793 <command role="hg-cmd">hg push</command> command does the 7.794 actual push.</para> 7.795 7.796 &interaction.tour.push; 7.797 7.798 - <para>As with 7.799 + <para id="x_69">As with 7.800 <command role="hg-cmd">hg pull</command>, the <command 7.801 role="hg-cmd">hg push</command> command does not update 7.802 the working directory in the repository that it's pushing 7.803 @@ -826,7 +826,7 @@ 7.804 does not provide a <literal>-u</literal> option that updates 7.805 the other repository's working directory.)</para> 7.806 7.807 - <para>What happens if we try to pull or push changes 7.808 + <para id="x_6a">What happens if we try to pull or push changes 7.809 and the receiving repository already has those changes? 7.810 Nothing too exciting.</para> 7.811 7.812 @@ -835,7 +835,7 @@ 7.813 <sect2> 7.814 <title>Sharing changes over a network</title> 7.815 7.816 - <para>The commands we have covered in the previous few 7.817 + <para id="x_6b">The commands we have covered in the previous few 7.818 sections are not limited to working with local repositories. 7.819 Each works in exactly the same fashion over a network 7.820 connection; simply pass in a URL instead of a local 7.821 @@ -843,7 +843,7 @@ 7.822 7.823 &interaction.tour.outgoing.net; 7.824 7.825 - <para>In this example, we 7.826 + <para id="x_6c">In this example, we 7.827 can see what changes we could push to the remote repository, 7.828 but the repository is understandably not set up to let 7.829 anonymous users push to it.</para>
8.1 --- a/en/ch02-tour-merge.xml Thu Mar 19 20:54:12 2009 -0700 8.2 +++ b/en/ch02-tour-merge.xml Thu Mar 19 21:18:52 2009 -0700 8.3 @@ -4,7 +4,7 @@ 8.4 <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?> 8.5 <title>A tour of Mercurial: merging work</title> 8.6 8.7 - <para>We've now covered cloning a repository, making changes in a 8.8 + <para id="x_338">We've now covered cloning a repository, making changes in a 8.9 repository, and pulling or pushing changes from one repository 8.10 into another. Our next step is <emphasis>merging</emphasis> 8.11 changes from separate repositories.</para> 8.12 @@ -12,29 +12,29 @@ 8.13 <sect1> 8.14 <title>Merging streams of work</title> 8.15 8.16 - <para>Merging is a fundamental part of working with a distributed 8.17 + <para id="x_339">Merging is a fundamental part of working with a distributed 8.18 revision control tool.</para> 8.19 <itemizedlist> 8.20 - <listitem><para>Alice and Bob each have a personal copy of a 8.21 + <listitem><para id="x_33a">Alice and Bob each have a personal copy of a 8.22 repository for a project they're collaborating on. Alice 8.23 fixes a bug in her repository; Bob adds a new feature in 8.24 his. They want the shared repository to contain both the 8.25 bug fix and the new feature.</para> 8.26 </listitem> 8.27 - <listitem><para>I frequently work on several different tasks for 8.28 + <listitem><para id="x_33b">I frequently work on several different tasks for 8.29 a single project at once, each safely isolated in its own 8.30 repository. Working this way means that I often need to 8.31 merge one piece of my own work with another.</para> 8.32 </listitem></itemizedlist> 8.33 8.34 - <para>Because merging is such a common thing to need to do, 8.35 + <para id="x_33c">Because merging is such a common thing to need to do, 8.36 Mercurial makes it easy. Let's walk through the process. We'll 8.37 begin by cloning yet another repository (see how often they 8.38 spring up?) and making a change in it.</para> 8.39 8.40 &interaction.tour.merge.clone; 8.41 8.42 - <para>We should now have two copies of 8.43 + <para id="x_33d">We should now have two copies of 8.44 <filename>hello.c</filename> with different contents. The 8.45 histories of the two repositories have also diverged, as 8.46 illustrated in figure <xref 8.47 @@ -46,26 +46,26 @@ 8.48 <mediaobject> 8.49 <imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject> 8.50 <textobject><phrase>XXX add text</phrase></textobject> 8.51 - <caption><para>Divergent recent histories of the <filename 8.52 + <caption><para id="x_33e">Divergent recent histories of the <filename 8.53 class="directory">my-hello</filename> and <filename 8.54 class="directory">my-new-hello</filename> 8.55 repositories</para></caption> 8.56 </mediaobject> 8.57 </informalfigure> 8.58 8.59 - <para>We already know that pulling changes from our <filename 8.60 + <para id="x_33f">We already know that pulling changes from our <filename 8.61 class="directory">my-hello</filename> repository will have no 8.62 effect on the working directory.</para> 8.63 8.64 &interaction.tour.merge.pull; 8.65 8.66 - <para>However, the <command role="hg-cmd">hg pull</command> 8.67 + <para id="x_340">However, the <command role="hg-cmd">hg pull</command> 8.68 command says something about <quote>heads</quote>.</para> 8.69 8.70 <sect2> 8.71 <title>Head changesets</title> 8.72 8.73 - <para>A head is a change that has no descendants, or children, 8.74 + <para id="x_341">A head is a change that has no descendants, or children, 8.75 as they're also known. The tip revision is thus a head, 8.76 because the newest revision in a repository doesn't have any 8.77 children, but a repository can contain more than one 8.78 @@ -75,14 +75,14 @@ 8.79 <mediaobject><imageobject><imagedata 8.80 fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX 8.81 add text</phrase></textobject> 8.82 - <caption><para>Repository contents after pulling from 8.83 + <caption><para id="x_342">Repository contents after pulling from 8.84 <filename class="directory">my-hello</filename> into 8.85 <filename 8.86 class="directory">my-new-hello</filename></para></caption> 8.87 </mediaobject> 8.88 </informalfigure> 8.89 8.90 - <para>In figure <xref linkend="fig:tour-merge:pull"/>, you can 8.91 + <para id="x_343">In figure <xref linkend="fig:tour-merge:pull"/>, you can 8.92 see the effect of the pull from <filename 8.93 class="directory">my-hello</filename> into <filename 8.94 class="directory">my-new-hello</filename>. The history that 8.95 @@ -103,13 +103,13 @@ 8.96 <sect2> 8.97 <title>Performing the merge</title> 8.98 8.99 - <para>What happens if we try to use the normal <command 8.100 + <para id="x_344">What happens if we try to use the normal <command 8.101 role="hg-cmd">hg update</command> command to update to the 8.102 new tip?</para> 8.103 8.104 &interaction.tour.merge.update; 8.105 8.106 - <para>Mercurial is telling us that the <command role="hg-cmd">hg 8.107 + <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg 8.108 update</command> command won't do a merge; it won't update 8.109 the working directory when it thinks we might be wanting to do 8.110 a merge, unless we force it to do so. Instead, we use the 8.111 @@ -123,12 +123,12 @@ 8.112 <mediaobject><imageobject><imagedata 8.113 fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX 8.114 add text</phrase></textobject> 8.115 - <caption><para>Working directory and repository during 8.116 + <caption><para id="x_346">Working directory and repository during 8.117 merge, and following commit</para></caption> 8.118 </mediaobject> 8.119 </informalfigure> 8.120 8.121 - <para>This updates the working directory so that it contains 8.122 + <para id="x_347">This updates the working directory so that it contains 8.123 changes from <emphasis>both</emphasis> heads, which is 8.124 reflected in both the output of <command role="hg-cmd">hg 8.125 parents</command> and the contents of 8.126 @@ -140,21 +140,21 @@ 8.127 <sect2> 8.128 <title>Committing the results of the merge</title> 8.129 8.130 - <para>Whenever we've done a merge, <command role="hg-cmd">hg 8.131 + <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg 8.132 parents</command> will display two parents until we <command 8.133 role="hg-cmd">hg commit</command> the results of the 8.134 merge.</para> 8.135 8.136 &interaction.tour.merge.commit; 8.137 8.138 - <para>We now have a new tip revision; notice that it has 8.139 + <para id="x_349">We now have a new tip revision; notice that it has 8.140 <emphasis>both</emphasis> of our former heads as its parents. 8.141 These are the same revisions that were previously displayed by 8.142 <command role="hg-cmd">hg parents</command>.</para> 8.143 8.144 &interaction.tour.merge.tip; 8.145 8.146 - <para>In figure <xref 8.147 + <para id="x_34a">In figure <xref 8.148 linkend="fig:tour-merge:merge"/>, you can see a 8.149 representation of what happens to the working directory during 8.150 the merge, and how this affects the repository when the commit 8.151 @@ -167,7 +167,7 @@ 8.152 <sect1> 8.153 <title>Merging conflicting changes</title> 8.154 8.155 - <para>Most merges are simple affairs, but sometimes you'll find 8.156 + <para id="x_34b">Most merges are simple affairs, but sometimes you'll find 8.157 yourself merging changes where each modifies the same portions 8.158 of the same files. Unless both modifications are identical, 8.159 this results in a <emphasis>conflict</emphasis>, where you have 8.160 @@ -179,18 +179,18 @@ 8.161 <mediaobject id="fig:tour-merge:conflict"> 8.162 <imageobject><imagedata fileref="tour-merge-conflict"/></imageobject> 8.163 <textobject><phrase>XXX add text</phrase></textobject> 8.164 - <caption><para>Conflicting changes to a 8.165 + <caption><para id="x_34c">Conflicting changes to a 8.166 document</para></caption> </mediaobject> 8.167 </informalfigure> 8.168 8.169 - <para>Figure <xref linkend="fig:tour-merge:conflict"/> illustrates 8.170 + <para id="x_34d">Figure <xref linkend="fig:tour-merge:conflict"/> illustrates 8.171 an instance of two conflicting changes to a document. We 8.172 started with a single version of the file; then we made some 8.173 changes; while someone else made different changes to the same 8.174 text. Our task in resolving the conflicting changes is to 8.175 decide what the file should look like.</para> 8.176 8.177 - <para>Mercurial doesn't have a built-in facility for handling 8.178 + <para id="x_34e">Mercurial doesn't have a built-in facility for handling 8.179 conflicts. Instead, it runs an external program called 8.180 <command>hgmerge</command>. This is a shell script that is 8.181 bundled with Mercurial; you can change it to behave however you 8.182 @@ -201,7 +201,7 @@ 8.183 human guidance) or aren't present, the script tries a few 8.184 different graphical merging tools.</para> 8.185 8.186 - <para>It's also possible to get Mercurial to run another program 8.187 + <para id="x_34f">It's also possible to get Mercurial to run another program 8.188 or script instead of <command>hgmerge</command>, by setting the 8.189 <envar>HGMERGE</envar> environment variable to the name of your 8.190 preferred program.</para> 8.191 @@ -209,7 +209,7 @@ 8.192 <sect2> 8.193 <title>Using a graphical merge tool</title> 8.194 8.195 - <para>My preferred graphical merge tool is 8.196 + <para id="x_350">My preferred graphical merge tool is 8.197 <command>kdiff3</command>, which I'll use to describe the 8.198 features that are common to graphical file merging tools. You 8.199 can see a screenshot of <command>kdiff3</command> in action in 8.200 @@ -219,26 +219,26 @@ 8.201 of the file of interest to us. The tool thus splits the upper 8.202 portion of the window into three panes:</para> 8.203 <itemizedlist> 8.204 - <listitem><para>At the left is the <emphasis>base</emphasis> 8.205 + <listitem><para id="x_351">At the left is the <emphasis>base</emphasis> 8.206 version of the file, i.e. the most recent version from 8.207 which the two versions we're trying to merge are 8.208 descended.</para> 8.209 </listitem> 8.210 - <listitem><para>In the middle is <quote>our</quote> version of 8.211 + <listitem><para id="x_352">In the middle is <quote>our</quote> version of 8.212 the file, with the contents that we modified.</para> 8.213 </listitem> 8.214 - <listitem><para>On the right is <quote>their</quote> version 8.215 + <listitem><para id="x_353">On the right is <quote>their</quote> version 8.216 of the file, the one that from the changeset that we're 8.217 trying to merge with.</para> 8.218 </listitem></itemizedlist> 8.219 - <para>In the pane below these is the current 8.220 + <para id="x_354">In the pane below these is the current 8.221 <emphasis>result</emphasis> of the merge. Our task is to 8.222 replace all of the red text, which indicates unresolved 8.223 conflicts, with some sensible merger of the 8.224 <quote>ours</quote> and <quote>theirs</quote> versions of the 8.225 file.</para> 8.226 8.227 - <para>All four of these panes are <emphasis>locked 8.228 + <para id="x_355">All four of these panes are <emphasis>locked 8.229 together</emphasis>; if we scroll vertically or horizontally 8.230 in any of them, the others are updated to display the 8.231 corresponding sections of their respective files.</para> 8.232 @@ -247,18 +247,18 @@ 8.233 <mediaobject><imageobject><imagedata 8.234 fileref="kdiff3"/></imageobject><textobject><phrase>XXX 8.235 add text</phrase></textobject> 8.236 - <caption><para>Using <command>kdiff3</command> to merge 8.237 + <caption><para id="x_356">Using <command>kdiff3</command> to merge 8.238 versions of a file</para></caption> 8.239 </mediaobject> 8.240 </informalfigure> 8.241 8.242 - <para>For each conflicting portion of the file, we can choose to 8.243 + <para id="x_357">For each conflicting portion of the file, we can choose to 8.244 resolve the conflict using some combination of text from the 8.245 base version, ours, or theirs. We can also manually edit the 8.246 merged file at any time, in case we need to make further 8.247 modifications.</para> 8.248 8.249 - <para>There are <emphasis>many</emphasis> file merging tools 8.250 + <para id="x_358">There are <emphasis>many</emphasis> file merging tools 8.251 available, too many to cover here. They vary in which 8.252 platforms they are available for, and in their particular 8.253 strengths and weaknesses. Most are tuned for merging files 8.254 @@ -269,19 +269,19 @@ 8.255 <sect2> 8.256 <title>A worked example</title> 8.257 8.258 - <para>In this example, we will reproduce the file modification 8.259 + <para id="x_359">In this example, we will reproduce the file modification 8.260 history of figure <xref linkend="fig:tour-merge:conflict"/> 8.261 above. Let's begin by creating a repository with a base 8.262 version of our document.</para> 8.263 8.264 &interaction.tour-merge-conflict.wife; 8.265 8.266 - <para>We'll clone the repository and make a change to the 8.267 + <para id="x_35a">We'll clone the repository and make a change to the 8.268 file.</para> 8.269 8.270 &interaction.tour-merge-conflict.cousin; 8.271 8.272 - <para>And another clone, to simulate someone else making a 8.273 + <para id="x_35b">And another clone, to simulate someone else making a 8.274 change to the file. (This hints at the idea that it's not all 8.275 that unusual to merge with yourself when you isolate tasks in 8.276 separate repositories, and indeed to find and resolve 8.277 @@ -289,13 +289,13 @@ 8.278 8.279 &interaction.tour-merge-conflict.son; 8.280 8.281 - <para>Having created two 8.282 + <para id="x_35c">Having created two 8.283 different versions of the file, we'll set up an environment 8.284 suitable for running our merge.</para> 8.285 8.286 &interaction.tour-merge-conflict.pull; 8.287 8.288 - <para>In this example, I won't use Mercurial's normal 8.289 + <para id="x_35d">In this example, I won't use Mercurial's normal 8.290 <command>hgmerge</command> program to do the merge, because it 8.291 would drop my nice automated example-running tool into a 8.292 graphical user interface. Instead, I'll set 8.293 @@ -305,25 +305,25 @@ 8.294 example on your computer, don't bother setting 8.295 <envar>HGMERGE</envar>.</para> 8.296 8.297 - <para><emphasis role="bold">XXX FIX THIS 8.298 + <para id="x_35e"><emphasis role="bold">XXX FIX THIS 8.299 EXAMPLE.</emphasis></para> 8.300 8.301 &interaction.tour-merge-conflict.merge; 8.302 8.303 - <para>Because <command>merge</command> can't resolve the 8.304 + <para id="x_35f">Because <command>merge</command> can't resolve the 8.305 conflicting changes, it leaves <emphasis>merge 8.306 markers</emphasis> inside the file that has conflicts, 8.307 indicating which lines have conflicts, and whether they came 8.308 from our version of the file or theirs.</para> 8.309 8.310 - <para>Mercurial can tell from the way <command>merge</command> 8.311 + <para id="x_360">Mercurial can tell from the way <command>merge</command> 8.312 exits that it wasn't able to merge successfully, so it tells 8.313 us what commands we'll need to run if we want to redo the 8.314 merging operation. This could be useful if, for example, we 8.315 were running a graphical merge tool and quit because we were 8.316 confused or realised we had made a mistake.</para> 8.317 8.318 - <para>If automatic or manual merges fail, there's nothing to 8.319 + <para id="x_361">If automatic or manual merges fail, there's nothing to 8.320 prevent us from <quote>fixing up</quote> the affected files 8.321 ourselves, and committing the results of our merge:</para> 8.322 8.323 @@ -334,29 +334,29 @@ 8.324 <sect1 id="sec:tour-merge:fetch"> 8.325 <title>Simplifying the pull-merge-commit sequence</title> 8.326 8.327 - <para>The process of merging changes as outlined above is 8.328 + <para id="x_362">The process of merging changes as outlined above is 8.329 straightforward, but requires running three commands in 8.330 sequence.</para> 8.331 <programlisting>hg pull 8.332 hg merge 8.333 hg commit -m 'Merged remote changes'</programlisting> 8.334 - <para>In the case of the final commit, you also need to enter a 8.335 + <para id="x_363">In the case of the final commit, you also need to enter a 8.336 commit message, which is almost always going to be a piece of 8.337 uninteresting <quote>boilerplate</quote> text.</para> 8.338 8.339 - <para>It would be nice to reduce the number of steps needed, if 8.340 + <para id="x_364">It would be nice to reduce the number of steps needed, if 8.341 this were possible. Indeed, Mercurial is distributed with an 8.342 extension called <literal role="hg-ext">fetch</literal> that 8.343 does just this.</para> 8.344 8.345 - <para>Mercurial provides a flexible extension mechanism that lets 8.346 + <para id="x_365">Mercurial provides a flexible extension mechanism that lets 8.347 people extend its functionality, while keeping the core of 8.348 Mercurial small and easy to deal with. Some extensions add new 8.349 commands that you can use from the command line, while others 8.350 work <quote>behind the scenes,</quote> for example adding 8.351 capabilities to the server.</para> 8.352 8.353 - <para>The <literal role="hg-ext">fetch</literal> extension adds a 8.354 + <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a 8.355 new command called, not surprisingly, <command role="hg-cmd">hg 8.356 fetch</command>. This extension acts as a combination of 8.357 <command role="hg-cmd">hg pull</command>, <command 8.358 @@ -369,7 +369,7 @@ 8.359 added, it updates the working directory to the new tip 8.360 changeset.</para> 8.361 8.362 - <para>Enabling the <literal role="hg-ext">fetch</literal> 8.363 + <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal> 8.364 extension is easy. Edit your <filename 8.365 role="special">.hgrc</filename>, and either go to the <literal 8.366 role="rc-extensions">extensions</literal> section or create an 8.367 @@ -378,7 +378,7 @@ 8.368 </literal></quote>.</para> 8.369 <programlisting>[extensions] 8.370 fetch =</programlisting> 8.371 - <para>(Normally, on the right-hand side of the 8.372 + <para id="x_368">(Normally, on the right-hand side of the 8.373 <quote><literal>=</literal></quote> would appear the location of 8.374 the extension, but since the <literal 8.375 role="hg-ext">fetch</literal> extension is in the standard
9.1 --- a/en/ch03-concepts.xml Thu Mar 19 20:54:12 2009 -0700 9.2 +++ b/en/ch03-concepts.xml Thu Mar 19 21:18:52 2009 -0700 9.3 @@ -4,20 +4,20 @@ 9.4 <?dbhtml filename="behind-the-scenes.html"?> 9.5 <title>Behind the scenes</title> 9.6 9.7 - <para>Unlike many revision control systems, the concepts upon which 9.8 + <para id="x_2e8">Unlike many revision control systems, the concepts upon which 9.9 Mercurial is built are simple enough that it's easy to understand 9.10 how the software really works. Knowing this certainly isn't 9.11 necessary, but I find it useful to have a <quote>mental 9.12 model</quote> of what's going on.</para> 9.13 9.14 - <para>This understanding gives me confidence that Mercurial has been 9.15 + <para id="x_2e9">This understanding gives me confidence that Mercurial has been 9.16 carefully designed to be both <emphasis>safe</emphasis> and 9.17 <emphasis>efficient</emphasis>. And just as importantly, if it's 9.18 easy for me to retain a good idea of what the software is doing 9.19 when I perform a revision control task, I'm less likely to be 9.20 surprised by its behaviour.</para> 9.21 9.22 - <para>In this chapter, we'll initially cover the core concepts 9.23 + <para id="x_2ea">In this chapter, we'll initially cover the core concepts 9.24 behind Mercurial's design, then continue to discuss some of the 9.25 interesting details of its implementation.</para> 9.26 9.27 @@ -27,7 +27,7 @@ 9.28 <sect2> 9.29 <title>Tracking the history of a single file</title> 9.30 9.31 - <para>When Mercurial tracks modifications to a file, it stores 9.32 + <para id="x_2eb">When Mercurial tracks modifications to a file, it stores 9.33 the history of that file in a metadata object called a 9.34 <emphasis>filelog</emphasis>. Each entry in the filelog 9.35 contains enough information to reconstruct one revision of the 9.36 @@ -38,7 +38,7 @@ 9.37 an index to help Mercurial to find a revision 9.38 efficiently.</para> 9.39 9.40 - <para>A file that is large, or has a lot of history, has its 9.41 + <para id="x_2ec">A file that is large, or has a lot of history, has its 9.42 filelog stored in separate data 9.43 (<quote><literal>.d</literal></quote> suffix) and index 9.44 (<quote><literal>.i</literal></quote> suffix) files. For 9.45 @@ -53,7 +53,7 @@ 9.46 <mediaobject><imageobject><imagedata 9.47 fileref="filelog"/></imageobject><textobject><phrase>XXX 9.48 add text</phrase></textobject> 9.49 - <caption><para>Relationships between files in working 9.50 + <caption><para id="x_2ed">Relationships between files in working 9.51 directory and filelogs in 9.52 repository</para></caption></mediaobject> 9.53 </informalfigure> 9.54 @@ -62,7 +62,7 @@ 9.55 <sect2> 9.56 <title>Managing tracked files</title> 9.57 9.58 - <para>Mercurial uses a structure called a 9.59 + <para id="x_2ee">Mercurial uses a structure called a 9.60 <emphasis>manifest</emphasis> to collect together information 9.61 about the files that it tracks. Each entry in the manifest 9.62 contains information about the files present in a single 9.63 @@ -74,7 +74,7 @@ 9.64 <sect2> 9.65 <title>Recording changeset information</title> 9.66 9.67 - <para>The <emphasis>changelog</emphasis> contains information 9.68 + <para id="x_2ef">The <emphasis>changelog</emphasis> contains information 9.69 about each changeset. Each revision records who committed a 9.70 change, the changeset comment, other pieces of 9.71 changeset-related information, and the revision of the 9.72 @@ -84,14 +84,14 @@ 9.73 <sect2> 9.74 <title>Relationships between revisions</title> 9.75 9.76 - <para>Within a changelog, a manifest, or a filelog, each 9.77 + <para id="x_2f0">Within a changelog, a manifest, or a filelog, each 9.78 revision stores a pointer to its immediate parent (or to its 9.79 two parents, if it's a merge revision). As I mentioned above, 9.80 there are also relationships between revisions 9.81 <emphasis>across</emphasis> these structures, and they are 9.82 hierarchical in nature.</para> 9.83 9.84 - <para>For every changeset in a repository, there is exactly one 9.85 + <para id="x_2f1">For every changeset in a repository, there is exactly one 9.86 revision stored in the changelog. Each revision of the 9.87 changelog contains a pointer to a single revision of the 9.88 manifest. A revision of the manifest stores a pointer to a 9.89 @@ -102,12 +102,12 @@ 9.90 <informalfigure id="fig:concepts:metadata"> 9.91 <mediaobject><imageobject><imagedata 9.92 fileref="metadata"/></imageobject><textobject><phrase>XXX 9.93 - add text</phrase></textobject><caption><para>Metadata 9.94 + add text</phrase></textobject><caption><para id="x_2f2">Metadata 9.95 relationships</para></caption> 9.96 </mediaobject> 9.97 </informalfigure> 9.98 9.99 - <para>As the illustration shows, there is 9.100 + <para id="x_2f3">As the illustration shows, there is 9.101 <emphasis>not</emphasis> a <quote>one to one</quote> 9.102 relationship between revisions in the changelog, manifest, or 9.103 filelog. If the manifest hasn't changed between two 9.104 @@ -122,14 +122,14 @@ 9.105 <sect1> 9.106 <title>Safe, efficient storage</title> 9.107 9.108 - <para>The underpinnings of changelogs, manifests, and filelogs are 9.109 + <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are 9.110 provided by a single structure called the 9.111 <emphasis>revlog</emphasis>.</para> 9.112 9.113 <sect2> 9.114 <title>Efficient storage</title> 9.115 9.116 - <para>The revlog provides efficient storage of revisions using a 9.117 + <para id="x_2f5">The revlog provides efficient storage of revisions using a 9.118 <emphasis>delta</emphasis> mechanism. Instead of storing a 9.119 complete copy of a file for each revision, it stores the 9.120 changes needed to transform an older revision into the new 9.121 @@ -137,7 +137,7 @@ 9.122 typically a fraction of a percent of the size of a full copy 9.123 of a file.</para> 9.124 9.125 - <para>Some obsolete revision control systems can only work with 9.126 + <para id="x_2f6">Some obsolete revision control systems can only work with 9.127 deltas of text files. They must either store binary files as 9.128 complete snapshots or encoded into a text representation, both 9.129 of which are wasteful approaches. Mercurial can efficiently 9.130 @@ -148,13 +148,13 @@ 9.131 <sect2 id="sec:concepts:txn"> 9.132 <title>Safe operation</title> 9.133 9.134 - <para>Mercurial only ever <emphasis>appends</emphasis> data to 9.135 + <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to 9.136 the end of a revlog file. It never modifies a section of a 9.137 file after it has written it. This is both more robust and 9.138 efficient than schemes that need to modify or rewrite 9.139 data.</para> 9.140 9.141 - <para>In addition, Mercurial treats every write as part of a 9.142 + <para id="x_2f8">In addition, Mercurial treats every write as part of a 9.143 <emphasis>transaction</emphasis> that can span a number of 9.144 files. A transaction is <emphasis>atomic</emphasis>: either 9.145 the entire transaction succeeds and its effects are all 9.146 @@ -164,7 +164,7 @@ 9.147 writing it, the reader will never see a partially written 9.148 result that might confuse it.</para> 9.149 9.150 - <para>The fact that Mercurial only appends to files makes it 9.151 + <para id="x_2f9">The fact that Mercurial only appends to files makes it 9.152 easier to provide this transactional guarantee. The easier it 9.153 is to do stuff like this, the more confident you should be 9.154 that it's done correctly.</para> 9.155 @@ -173,7 +173,7 @@ 9.156 <sect2> 9.157 <title>Fast retrieval</title> 9.158 9.159 - <para>Mercurial cleverly avoids a pitfall common to all earlier 9.160 + <para id="x_2fa">Mercurial cleverly avoids a pitfall common to all earlier 9.161 revision control systems: the problem of <emphasis>inefficient 9.162 retrieval</emphasis>. Most revision control systems store 9.163 the contents of a revision as an incremental series of 9.164 @@ -187,12 +187,12 @@ 9.165 <informalfigure id="fig:concepts:snapshot"> 9.166 <mediaobject><imageobject><imagedata 9.167 fileref="snapshot"/></imageobject><textobject><phrase>XXX 9.168 - add text</phrase></textobject><caption><para>Snapshot of 9.169 + add text</phrase></textobject><caption><para id="x_2fb">Snapshot of 9.170 a revlog, with incremental 9.171 deltas</para></caption></mediaobject> 9.172 </informalfigure> 9.173 9.174 - <para>The innovation that Mercurial applies to this problem is 9.175 + <para id="x_2fc">The innovation that Mercurial applies to this problem is 9.176 simple but effective. Once the cumulative amount of delta 9.177 information stored since the last snapshot exceeds a fixed 9.178 threshold, it stores a new snapshot (compressed, of course), 9.179 @@ -201,7 +201,7 @@ 9.180 quickly. This approach works so well that it has since been 9.181 copied by several other revision control systems.</para> 9.182 9.183 - <para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates 9.184 + <para id="x_2fd">Figure <xref linkend="fig:concepts:snapshot"/> illustrates 9.185 the idea. In an entry in a revlog's index file, Mercurial 9.186 stores the range of entries from the data file that it must 9.187 read to reconstruct a particular revision.</para> 9.188 @@ -209,7 +209,7 @@ 9.189 <sect3> 9.190 <title>Aside: the influence of video compression</title> 9.191 9.192 - <para>If you're familiar with video compression or have ever 9.193 + <para id="x_2fe">If you're familiar with video compression or have ever 9.194 watched a TV feed through a digital cable or satellite 9.195 service, you may know that most video compression schemes 9.196 store each frame of video as a delta against its predecessor 9.197 @@ -218,7 +218,7 @@ 9.198 visual errors accumulate over the course of a number of 9.199 inter-frame deltas.</para> 9.200 9.201 - <para>Because it's possible for a video stream to <quote>drop 9.202 + <para id="x_2ff">Because it's possible for a video stream to <quote>drop 9.203 out</quote> occasionally due to signal glitches, and to 9.204 limit the accumulation of artefacts introduced by the lossy 9.205 compression process, video encoders periodically insert a 9.206 @@ -234,24 +234,24 @@ 9.207 <sect2> 9.208 <title>Identification and strong integrity</title> 9.209 9.210 - <para>Along with delta or snapshot information, a revlog entry 9.211 + <para id="x_300">Along with delta or snapshot information, a revlog entry 9.212 contains a cryptographic hash of the data that it represents. 9.213 This makes it difficult to forge the contents of a revision, 9.214 and easy to detect accidental corruption.</para> 9.215 9.216 - <para>Hashes provide more than a mere check against corruption; 9.217 + <para id="x_301">Hashes provide more than a mere check against corruption; 9.218 they are used as the identifiers for revisions. The changeset 9.219 identification hashes that you see as an end user are from 9.220 revisions of the changelog. Although filelogs and the 9.221 manifest also use hashes, Mercurial only uses these behind the 9.222 scenes.</para> 9.223 9.224 - <para>Mercurial verifies that hashes are correct when it 9.225 + <para id="x_302">Mercurial verifies that hashes are correct when it 9.226 retrieves file revisions and when it pulls changes from 9.227 another repository. If it encounters an integrity problem, it 9.228 will complain and stop whatever it's doing.</para> 9.229 9.230 - <para>In addition to the effect it has on retrieval efficiency, 9.231 + <para id="x_303">In addition to the effect it has on retrieval efficiency, 9.232 Mercurial's use of periodic snapshots makes it more robust 9.233 against partial data corruption. If a revlog becomes partly 9.234 corrupted due to a hardware error or system bug, it's often 9.235 @@ -265,7 +265,7 @@ 9.236 <sect1> 9.237 <title>Revision history, branching, and merging</title> 9.238 9.239 - <para>Every entry in a Mercurial revlog knows the identity of its 9.240 + <para id="x_304">Every entry in a Mercurial revlog knows the identity of its 9.241 immediate ancestor revision, usually referred to as its 9.242 <emphasis>parent</emphasis>. In fact, a revision contains room 9.243 for not one parent, but two. Mercurial uses a special hash, 9.244 @@ -273,13 +273,13 @@ 9.245 <quote>there is no parent here</quote>. This hash is simply a 9.246 string of zeroes.</para> 9.247 9.248 - <para>In figure <xref linkend="fig:concepts:revlog"/>, you can see 9.249 + <para id="x_305">In figure <xref linkend="fig:concepts:revlog"/>, you can see 9.250 an example of the conceptual structure of a revlog. Filelogs, 9.251 manifests, and changelogs all have this same structure; they 9.252 differ only in the kind of data stored in each delta or 9.253 snapshot.</para> 9.254 9.255 - <para>The first revision in a revlog (at the bottom of the image) 9.256 + <para id="x_306">The first revision in a revlog (at the bottom of the image) 9.257 has the null ID in both of its parent slots. For a 9.258 <quote>normal</quote> revision, its first parent slot contains 9.259 the ID of its parent revision, and its second contains the null 9.260 @@ -298,10 +298,10 @@ 9.261 <sect1> 9.262 <title>The working directory</title> 9.263 9.264 - <para>In the working directory, Mercurial stores a snapshot of the 9.265 + <para id="x_307">In the working directory, Mercurial stores a snapshot of the 9.266 files from the repository as of a particular changeset.</para> 9.267 9.268 - <para>The working directory <quote>knows</quote> which changeset 9.269 + <para id="x_308">The working directory <quote>knows</quote> which changeset 9.270 it contains. When you update the working directory to contain a 9.271 particular changeset, Mercurial looks up the appropriate 9.272 revision of the manifest to find out which files it was tracking 9.273 @@ -310,13 +310,13 @@ 9.274 those files, with the same contents it had when the changeset 9.275 was committed.</para> 9.276 9.277 - <para>The <emphasis>dirstate</emphasis> contains Mercurial's 9.278 + <para id="x_309">The <emphasis>dirstate</emphasis> contains Mercurial's 9.279 knowledge of the working directory. This details which 9.280 changeset the working directory is updated to, and all of the 9.281 files that Mercurial is tracking in the working 9.282 directory.</para> 9.283 9.284 - <para>Just as a revision of a revlog has room for two parents, so 9.285 + <para id="x_30a">Just as a revision of a revlog has room for two parents, so 9.286 that it can represent either a normal revision (with one parent) 9.287 or a merge of two earlier revisions, the dirstate has slots for 9.288 two parents. When you use the <command role="hg-cmd">hg 9.289 @@ -332,7 +332,7 @@ 9.290 <sect2> 9.291 <title>What happens when you commit</title> 9.292 9.293 - <para>The dirstate stores parent information for more than just 9.294 + <para id="x_30b">The dirstate stores parent information for more than just 9.295 book-keeping purposes. Mercurial uses the parents of the 9.296 dirstate as <emphasis>the parents of a new 9.297 changeset</emphasis> when you perform a commit.</para> 9.298 @@ -340,12 +340,12 @@ 9.299 <informalfigure id="fig:concepts:wdir"> 9.300 <mediaobject><imageobject><imagedata 9.301 fileref="wdir"/></imageobject><textobject><phrase>XXX 9.302 - add text</phrase></textobject><caption><para>The working 9.303 + add text</phrase></textobject><caption><para id="x_30c">The working 9.304 directory can have two 9.305 parents</para></caption></mediaobject> 9.306 </informalfigure> 9.307 9.308 - <para>Figure <xref linkend="fig:concepts:wdir"/> shows the 9.309 + <para id="x_30d">Figure <xref linkend="fig:concepts:wdir"/> shows the 9.310 normal state of the working directory, where it has a single 9.311 changeset as parent. That changeset is the 9.312 <emphasis>tip</emphasis>, the newest changeset in the 9.313 @@ -354,12 +354,12 @@ 9.314 <informalfigure id="fig:concepts:wdir-after-commit"> 9.315 <mediaobject><imageobject><imagedata 9.316 fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX 9.317 - add text</phrase></textobject><caption><para>The working 9.318 + add text</phrase></textobject><caption><para id="x_30e">The working 9.319 directory gains new parents after a 9.320 commit</para></caption></mediaobject> 9.321 </informalfigure> 9.322 9.323 - <para>It's useful to think of the working directory as 9.324 + <para id="x_30f">It's useful to think of the working directory as 9.325 <quote>the changeset I'm about to commit</quote>. Any files 9.326 that you tell Mercurial that you've added, removed, renamed, 9.327 or copied will be reflected in that changeset, as will 9.328 @@ -367,7 +367,7 @@ 9.329 the new changeset will have the parents of the working 9.330 directory as its parents.</para> 9.331 9.332 - <para>After a commit, Mercurial will update the parents of the 9.333 + <para id="x_310">After a commit, Mercurial will update the parents of the 9.334 working directory, so that the first parent is the ID of the 9.335 new changeset, and the second is the null ID. This is shown 9.336 in figure <xref linkend="fig:concepts:wdir-after-commit"/>. 9.337 @@ -380,7 +380,7 @@ 9.338 <sect2> 9.339 <title>Creating a new head</title> 9.340 9.341 - <para>It's perfectly normal to update the working directory to a 9.342 + <para id="x_311">It's perfectly normal to update the working directory to a 9.343 changeset other than the current tip. For example, you might 9.344 want to know what your project looked like last Tuesday, or 9.345 you could be looking through changesets to see which one 9.346 @@ -394,12 +394,12 @@ 9.347 <informalfigure id="fig:concepts:wdir-pre-branch"> 9.348 <mediaobject><imageobject><imagedata 9.349 fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX 9.350 - add text</phrase></textobject><caption><para>The working 9.351 + add text</phrase></textobject><caption><para id="x_312">The working 9.352 directory, updated to an older 9.353 changeset</para></caption></mediaobject> 9.354 </informalfigure> 9.355 9.356 - <para>Having updated the working directory to an older 9.357 + <para id="x_313">Having updated the working directory to an older 9.358 changeset, what happens if you make some changes, and then 9.359 commit? Mercurial behaves in the same way as I outlined 9.360 above. The parents of the working directory become the 9.361 @@ -413,13 +413,13 @@ 9.362 <informalfigure id="fig:concepts:wdir-branch"> 9.363 <mediaobject><imageobject><imagedata 9.364 fileref="wdir-branch"/></imageobject><textobject><phrase>XXX 9.365 - add text</phrase></textobject><caption><para>After a 9.366 + add text</phrase></textobject><caption><para id="x_314">After a 9.367 commit made while synced to an older 9.368 changeset</para></caption></mediaobject> 9.369 </informalfigure> 9.370 9.371 <note> 9.372 - <para> If you're new to Mercurial, you should keep in mind a 9.373 + <para id="x_315"> If you're new to Mercurial, you should keep in mind a 9.374 common <quote>error</quote>, which is to use the <command 9.375 role="hg-cmd">hg pull</command> command without any 9.376 options. By default, the <command role="hg-cmd">hg 9.377 @@ -431,7 +431,7 @@ 9.378 a new head, because your working directory isn't synced to 9.379 whatever the current tip is.</para> 9.380 9.381 - <para> I put the word <quote>error</quote> in quotes because 9.382 + <para id="x_316"> I put the word <quote>error</quote> in quotes because 9.383 all that you need to do to rectify this situation is 9.384 <command role="hg-cmd">hg merge</command>, then <command 9.385 role="hg-cmd">hg commit</command>. In other words, this 9.386 @@ -445,7 +445,7 @@ 9.387 <sect2> 9.388 <title>Merging heads</title> 9.389 9.390 - <para>When you run the <command role="hg-cmd">hg merge</command> 9.391 + <para id="x_317">When you run the <command role="hg-cmd">hg merge</command> 9.392 command, Mercurial leaves the first parent of the working 9.393 directory unchanged, and sets the second parent to the 9.394 changeset you're merging with, as shown in figure <xref 9.395 @@ -454,54 +454,54 @@ 9.396 <informalfigure id="fig:concepts:wdir-merge"> 9.397 <mediaobject><imageobject><imagedata 9.398 fileref="wdir-merge"/></imageobject><textobject><phrase>XXX 9.399 - add text</phrase></textobject><caption><para>Merging two 9.400 + add text</phrase></textobject><caption><para id="x_318">Merging two 9.401 heads</para></caption></mediaobject> 9.402 </informalfigure> 9.403 9.404 - <para>Mercurial also has to modify the working directory, to 9.405 + <para id="x_319">Mercurial also has to modify the working directory, to 9.406 merge the files managed in the two changesets. Simplified a 9.407 little, the merging process goes like this, for every file in 9.408 the manifests of both changesets.</para> 9.409 <itemizedlist> 9.410 - <listitem><para>If neither changeset has modified a file, do 9.411 + <listitem><para id="x_31a">If neither changeset has modified a file, do 9.412 nothing with that file.</para> 9.413 </listitem> 9.414 - <listitem><para>If one changeset has modified a file, and the 9.415 + <listitem><para id="x_31b">If one changeset has modified a file, and the 9.416 other hasn't, create the modified copy of the file in the 9.417 working directory.</para> 9.418 </listitem> 9.419 - <listitem><para>If one changeset has removed a file, and the 9.420 + <listitem><para id="x_31c">If one changeset has removed a file, and the 9.421 other hasn't (or has also deleted it), delete the file 9.422 from the working directory.</para> 9.423 </listitem> 9.424 - <listitem><para>If one changeset has removed a file, but the 9.425 + <listitem><para id="x_31d">If one changeset has removed a file, but the 9.426 other has modified the file, ask the user what to do: keep 9.427 the modified file, or remove it?</para> 9.428 </listitem> 9.429 - <listitem><para>If both changesets have modified a file, 9.430 + <listitem><para id="x_31e">If both changesets have modified a file, 9.431 invoke an external merge program to choose the new 9.432 contents for the merged file. This may require input from 9.433 the user.</para> 9.434 </listitem> 9.435 - <listitem><para>If one changeset has modified a file, and the 9.436 + <listitem><para id="x_31f">If one changeset has modified a file, and the 9.437 other has renamed or copied the file, make sure that the 9.438 changes follow the new name of the file.</para> 9.439 </listitem></itemizedlist> 9.440 - <para>There are more details&emdash;merging has plenty of corner 9.441 + <para id="x_320">There are more details&emdash;merging has plenty of corner 9.442 cases&emdash;but these are the most common choices that are 9.443 involved in a merge. As you can see, most cases are 9.444 completely automatic, and indeed most merges finish 9.445 automatically, without requiring your input to resolve any 9.446 conflicts.</para> 9.447 9.448 - <para>When you're thinking about what happens when you commit 9.449 + <para id="x_321">When you're thinking about what happens when you commit 9.450 after a merge, once again the working directory is <quote>the 9.451 changeset I'm about to commit</quote>. After the <command 9.452 role="hg-cmd">hg merge</command> command completes, the 9.453 working directory has two parents; these will become the 9.454 parents of the new changeset.</para> 9.455 9.456 - <para>Mercurial lets you perform multiple merges, but you must 9.457 + <para id="x_322">Mercurial lets you perform multiple merges, but you must 9.458 commit the results of each individual merge as you go. This 9.459 is necessary because Mercurial only tracks two parents for 9.460 both revisions and the working directory. While it would be 9.461 @@ -514,7 +514,7 @@ 9.462 <sect1> 9.463 <title>Other interesting design features</title> 9.464 9.465 - <para>In the sections above, I've tried to highlight some of the 9.466 + <para id="x_323">In the sections above, I've tried to highlight some of the 9.467 most important aspects of Mercurial's design, to illustrate that 9.468 it pays careful attention to reliability and performance. 9.469 However, the attention to detail doesn't stop there. There are 9.470 @@ -527,13 +527,13 @@ 9.471 <sect2> 9.472 <title>Clever compression</title> 9.473 9.474 - <para>When appropriate, Mercurial will store both snapshots and 9.475 + <para id="x_324">When appropriate, Mercurial will store both snapshots and 9.476 deltas in compressed form. It does this by always 9.477 <emphasis>trying to</emphasis> compress a snapshot or delta, 9.478 but only storing the compressed version if it's smaller than 9.479 the uncompressed version.</para> 9.480 9.481 - <para>This means that Mercurial does <quote>the right 9.482 + <para id="x_325">This means that Mercurial does <quote>the right 9.483 thing</quote> when storing a file whose native form is 9.484 compressed, such as a <literal>zip</literal> archive or a JPEG 9.485 image. When these types of files are compressed a second 9.486 @@ -541,7 +541,7 @@ 9.487 once-compressed form, and so Mercurial will store the plain 9.488 <literal>zip</literal> or JPEG.</para> 9.489 9.490 - <para>Deltas between revisions of a compressed file are usually 9.491 + <para id="x_326">Deltas between revisions of a compressed file are usually 9.492 larger than snapshots of the file, and Mercurial again does 9.493 <quote>the right thing</quote> in these cases. It finds that 9.494 such a delta exceeds the threshold at which it should store a 9.495 @@ -552,7 +552,7 @@ 9.496 <sect3> 9.497 <title>Network recompression</title> 9.498 9.499 - <para>When storing revisions on disk, Mercurial uses the 9.500 + <para id="x_327">When storing revisions on disk, Mercurial uses the 9.501 <quote>deflate</quote> compression algorithm (the same one 9.502 used by the popular <literal>zip</literal> archive format), 9.503 which balances good speed with a respectable compression 9.504 @@ -560,7 +560,7 @@ 9.505 network connection, Mercurial uncompresses the compressed 9.506 revision data.</para> 9.507 9.508 - <para>If the connection is over HTTP, Mercurial recompresses 9.509 + <para id="x_328">If the connection is over HTTP, Mercurial recompresses 9.510 the entire stream of data using a compression algorithm that 9.511 gives a better compression ratio (the Burrows-Wheeler 9.512 algorithm from the widely used <literal>bzip2</literal> 9.513 @@ -570,7 +570,7 @@ 9.514 transferred, yielding better network performance over almost 9.515 all kinds of network.</para> 9.516 9.517 - <para>(If the connection is over <command>ssh</command>, 9.518 + <para id="x_329">(If the connection is over <command>ssh</command>, 9.519 Mercurial <emphasis>doesn't</emphasis> recompress the 9.520 stream, because <command>ssh</command> can already do this 9.521 itself.)</para> 9.522 @@ -580,7 +580,7 @@ 9.523 <sect2> 9.524 <title>Read/write ordering and atomicity</title> 9.525 9.526 - <para>Appending to files isn't the whole story when it comes to 9.527 + <para id="x_32a">Appending to files isn't the whole story when it comes to 9.528 guaranteeing that a reader won't see a partial write. If you 9.529 recall figure <xref linkend="fig:concepts:metadata"/>, 9.530 revisions in the 9.531 @@ -588,12 +588,12 @@ 9.532 the manifest point to revisions in filelogs. This hierarchy 9.533 is deliberate.</para> 9.534 9.535 - <para>A writer starts a transaction by writing filelog and 9.536 + <para id="x_32b">A writer starts a transaction by writing filelog and 9.537 manifest data, and doesn't write any changelog data until 9.538 those are finished. A reader starts by reading changelog 9.539 data, then manifest data, followed by filelog data.</para> 9.540 9.541 - <para>Since the writer has always finished writing filelog and 9.542 + <para id="x_32c">Since the writer has always finished writing filelog and 9.543 manifest data before it writes to the changelog, a reader will 9.544 never read a pointer to a partially written manifest revision 9.545 from the changelog, and it will never read a pointer to a 9.546 @@ -603,7 +603,7 @@ 9.547 <sect2> 9.548 <title>Concurrent access</title> 9.549 9.550 - <para>The read/write ordering and atomicity guarantees mean that 9.551 + <para id="x_32d">The read/write ordering and atomicity guarantees mean that 9.552 Mercurial never needs to <emphasis>lock</emphasis> a 9.553 repository when it's reading data, even if the repository is 9.554 being written to while the read is occurring. This has a big 9.555 @@ -612,7 +612,7 @@ 9.556 safely all at once, no matter whether it's being written to or 9.557 not.</para> 9.558 9.559 - <para>The lockless nature of reading means that if you're 9.560 + <para id="x_32e">The lockless nature of reading means that if you're 9.561 sharing a repository on a multi-user system, you don't need to 9.562 grant other local users permission to 9.563 <emphasis>write</emphasis> to your repository in order for 9.564 @@ -625,7 +625,7 @@ 9.565 which of course makes for all kinds of nasty and annoying 9.566 security and administrative problems.)</para> 9.567 9.568 - <para>Mercurial uses locks to ensure that only one process can 9.569 + <para id="x_32f">Mercurial uses locks to ensure that only one process can 9.570 write to a repository at a time (the locking mechanism is safe 9.571 even over filesystems that are notoriously hostile to locking, 9.572 such as NFS). If a repository is locked, a writer will wait 9.573 @@ -639,7 +639,7 @@ 9.574 <sect3> 9.575 <title>Safe dirstate access</title> 9.576 9.577 - <para>As with revision data, Mercurial doesn't take a lock to 9.578 + <para id="x_330">As with revision data, Mercurial doesn't take a lock to 9.579 read the dirstate file; it does acquire a lock to write it. 9.580 To avoid the possibility of reading a partially written copy 9.581 of the dirstate file, Mercurial writes to a file with a 9.582 @@ -654,17 +654,17 @@ 9.583 <sect2> 9.584 <title>Avoiding seeks</title> 9.585 9.586 - <para>Critical to Mercurial's performance is the avoidance of 9.587 + <para id="x_331">Critical to Mercurial's performance is the avoidance of 9.588 seeks of the disk head, since any seek is far more expensive 9.589 than even a comparatively large read operation.</para> 9.590 9.591 - <para>This is why, for example, the dirstate is stored in a 9.592 + <para id="x_332">This is why, for example, the dirstate is stored in a 9.593 single file. If there were a dirstate file per directory that 9.594 Mercurial tracked, the disk would seek once per directory. 9.595 Instead, Mercurial reads the entire single dirstate file in 9.596 one step.</para> 9.597 9.598 - <para>Mercurial also uses a <quote>copy on write</quote> scheme 9.599 + <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme 9.600 when cloning a repository on local storage. Instead of 9.601 copying every revlog file from the old repository into the new 9.602 repository, it makes a <quote>hard link</quote>, which is a 9.603 @@ -675,7 +675,7 @@ 9.604 one repository is using the file, so Mercurial makes a new 9.605 copy of the file that is private to this repository.</para> 9.606 9.607 - <para>A few revision control developers have pointed out that 9.608 + <para id="x_334">A few revision control developers have pointed out that 9.609 this idea of making a complete private copy of a file is not 9.610 very efficient in its use of storage. While this is true, 9.611 storage is cheap, and this method gives the highest 9.612 @@ -689,21 +689,21 @@ 9.613 <sect2> 9.614 <title>Other contents of the dirstate</title> 9.615 9.616 - <para>Because Mercurial doesn't force you to tell it when you're 9.617 + <para id="x_335">Because Mercurial doesn't force you to tell it when you're 9.618 modifying a file, it uses the dirstate to store some extra 9.619 information so it can determine efficiently whether you have 9.620 modified a file. For each file in the working directory, it 9.621 stores the time that it last modified the file itself, and the 9.622 size of the file at that time.</para> 9.623 9.624 - <para>When you explicitly <command role="hg-cmd">hg 9.625 + <para id="x_336">When you explicitly <command role="hg-cmd">hg 9.626 add</command>, <command role="hg-cmd">hg remove</command>, 9.627 <command role="hg-cmd">hg rename</command> or <command 9.628 role="hg-cmd">hg copy</command> files, Mercurial updates the 9.629 dirstate so that it knows what to do with those files when you 9.630 commit.</para> 9.631 9.632 - <para>When Mercurial is checking the states of files in the 9.633 + <para id="x_337">When Mercurial is checking the states of files in the 9.634 working directory, it first checks a file's modification time. 9.635 If that has not changed, the file must not have been modified. 9.636 If the file's size has changed, the file must have been
10.1 --- a/en/ch04-daily.xml Thu Mar 19 20:54:12 2009 -0700 10.2 +++ b/en/ch04-daily.xml Thu Mar 19 21:18:52 2009 -0700 10.3 @@ -7,14 +7,14 @@ 10.4 <sect1> 10.5 <title>Telling Mercurial which files to track</title> 10.6 10.7 - <para>Mercurial does not work with files in your repository unless 10.8 + <para id="x_1a3">Mercurial does not work with files in your repository unless 10.9 you tell it to manage them. The <command role="hg-cmd">hg 10.10 status</command> command will tell you which files Mercurial 10.11 doesn't know about; it uses a 10.12 <quote><literal>?</literal></quote> to display such 10.13 files.</para> 10.14 10.15 - <para>To tell Mercurial to track a file, use the <command 10.16 + <para id="x_1a4">To tell Mercurial to track a file, use the <command 10.17 role="hg-cmd">hg add</command> command. Once you have added a 10.18 file, the entry in the output of <command role="hg-cmd">hg 10.19 status</command> for that file changes from 10.20 @@ -23,7 +23,7 @@ 10.21 10.22 &interaction.daily.files.add; 10.23 10.24 - <para>After you run a <command role="hg-cmd">hg commit</command>, 10.25 + <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>, 10.26 the files that you added before the commit will no longer be 10.27 listed in the output of <command role="hg-cmd">hg 10.28 status</command>. The reason for this is that <command 10.29 @@ -35,7 +35,7 @@ 10.30 is tracking, but that have not changed. (You can still get this 10.31 information; we'll return to this later.)</para> 10.32 10.33 - <para>Once you add a file, Mercurial doesn't do anything with it 10.34 + <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it 10.35 immediately. Instead, it will take a snapshot of the file's 10.36 state the next time you perform a commit. It will then continue 10.37 to track the changes you make to the file every time you commit, 10.38 @@ -44,24 +44,24 @@ 10.39 <sect2> 10.40 <title>Explicit versus implicit file naming</title> 10.41 10.42 - <para>A useful behaviour that Mercurial has is that if you pass 10.43 + <para id="x_1a7">A useful behaviour that Mercurial has is that if you pass 10.44 the name of a directory to a command, every Mercurial command 10.45 will treat this as <quote>I want to operate on every file in 10.46 this directory and its subdirectories</quote>.</para> 10.47 10.48 &interaction.daily.files.add-dir; 10.49 10.50 - <para>Notice in this example that Mercurial printed the names of 10.51 + <para id="x_1a8">Notice in this example that Mercurial printed the names of 10.52 the files it added, whereas it didn't do so when we added the 10.53 file named <filename>a</filename> in the earlier 10.54 example.</para> 10.55 10.56 - <para>What's going on is that in the former case, we explicitly 10.57 + <para id="x_1a9">What's going on is that in the former case, we explicitly 10.58 named the file to add on the command line, so the assumption 10.59 that Mercurial makes in such cases is that you know what you 10.60 were doing, and it doesn't print any output.</para> 10.61 10.62 - <para>However, when we <emphasis>imply</emphasis> the names of 10.63 + <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of 10.64 files by giving the name of a directory, Mercurial takes the 10.65 extra step of printing the name of each file that it does 10.66 something with. This makes it more clear what is happening, 10.67 @@ -72,7 +72,7 @@ 10.68 <sect2> 10.69 <title>Aside: Mercurial tracks files, not directories</title> 10.70 10.71 - <para>Mercurial does not track directory information. Instead, 10.72 + <para id="x_1ab">Mercurial does not track directory information. Instead, 10.73 it tracks the path to a file. Before creating a file, it 10.74 first creates any missing directory components of the path. 10.75 After it deletes a file, it then deletes any empty directories 10.76 @@ -81,14 +81,14 @@ 10.77 consequence: it is not possible to represent a completely 10.78 empty directory in Mercurial.</para> 10.79 10.80 - <para>Empty directories are rarely useful, and there are 10.81 + <para id="x_1ac">Empty directories are rarely useful, and there are 10.82 unintrusive workarounds that you can use to achieve an 10.83 appropriate effect. The developers of Mercurial thus felt 10.84 that the complexity that would be required to manage empty 10.85 directories was not worth the limited benefit this feature 10.86 would bring.</para> 10.87 10.88 - <para>If you need an empty directory in your repository, there 10.89 + <para id="x_1ad">If you need an empty directory in your repository, there 10.90 are a few ways to achieve this. One is to create a directory, 10.91 then <command role="hg-cmd">hg add</command> a 10.92 <quote>hidden</quote> file to that directory. On Unix-like 10.93 @@ -99,7 +99,7 @@ 10.94 10.95 &interaction.daily.files.hidden; 10.96 10.97 - <para>Another way to tackle a need for an empty directory is to 10.98 + <para id="x_1ae">Another way to tackle a need for an empty directory is to 10.99 simply create one in your automated build scripts before they 10.100 will need it.</para> 10.101 10.102 @@ -108,7 +108,7 @@ 10.103 <sect1> 10.104 <title>How to stop tracking a file</title> 10.105 10.106 - <para>Once you decide that a file no longer belongs in your 10.107 + <para id="x_1af">Once you decide that a file no longer belongs in your 10.108 repository, use the <command role="hg-cmd">hg remove</command> 10.109 command; this deletes the file, and tells Mercurial to stop 10.110 tracking it. A removed file is represented in the output of 10.111 @@ -117,7 +117,7 @@ 10.112 10.113 &interaction.daily.files.remove; 10.114 10.115 - <para>After you <command role="hg-cmd">hg remove</command> a file, 10.116 + <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file, 10.117 Mercurial will no longer track changes to that file, even if you 10.118 recreate a file with the same name in your working directory. 10.119 If you do recreate a file with the same name and want Mercurial 10.120 @@ -128,19 +128,19 @@ 10.121 <sect2> 10.122 <title>Removing a file does not affect its history</title> 10.123 10.124 - <para>It is important to understand that removing a file has 10.125 + <para id="x_1b1">It is important to understand that removing a file has 10.126 only two effects.</para> 10.127 <itemizedlist> 10.128 - <listitem><para>It removes the current version of the file 10.129 + <listitem><para id="x_1b2">It removes the current version of the file 10.130 from the working directory.</para> 10.131 </listitem> 10.132 - <listitem><para>It stops Mercurial from tracking changes to 10.133 + <listitem><para id="x_1b3">It stops Mercurial from tracking changes to 10.134 the file, from the time of the next commit.</para> 10.135 </listitem></itemizedlist> 10.136 - <para>Removing a file <emphasis>does not</emphasis> in any way 10.137 + <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way 10.138 alter the <emphasis>history</emphasis> of the file.</para> 10.139 10.140 - <para>If you update the working directory to a changeset in 10.141 + <para id="x_1b5">If you update the working directory to a changeset in 10.142 which a file that you have removed was still tracked, it will 10.143 reappear in the working directory, with the contents it had 10.144 when you committed that changeset. If you then update the 10.145 @@ -152,7 +152,7 @@ 10.146 <sect2> 10.147 <title>Missing files</title> 10.148 10.149 - <para>Mercurial considers a file that you have deleted, but not 10.150 + <para id="x_1b6">Mercurial considers a file that you have deleted, but not 10.151 used <command role="hg-cmd">hg remove</command> to delete, to 10.152 be <emphasis>missing</emphasis>. A missing file is 10.153 represented with <quote><literal>!</literal></quote> in the 10.154 @@ -162,7 +162,7 @@ 10.155 10.156 &interaction.daily.files.missing; 10.157 10.158 - <para>If your repository contains a file that <command 10.159 + <para id="x_1b7">If your repository contains a file that <command 10.160 role="hg-cmd">hg status</command> reports as missing, and 10.161 you want the file to stay gone, you can run <command 10.162 role="hg-cmd">hg remove <option 10.163 @@ -172,7 +172,7 @@ 10.164 10.165 &interaction.daily.files.remove-after; 10.166 10.167 - <para>On the other hand, if you deleted the missing file by 10.168 + <para id="x_1b8">On the other hand, if you deleted the missing file by 10.169 accident, give <command role="hg-cmd">hg revert</command> the 10.170 name of the file to recover. It will reappear, in unmodified 10.171 form.</para> 10.172 @@ -184,7 +184,7 @@ 10.173 <title>Aside: why tell Mercurial explicitly to remove a 10.174 file?</title> 10.175 10.176 - <para>You might wonder why Mercurial requires you to explicitly 10.177 + <para id="x_1b9">You might wonder why Mercurial requires you to explicitly 10.178 tell it that you are deleting a file. Early during the 10.179 development of Mercurial, it let you delete a file however you 10.180 pleased; Mercurial would notice the absence of the file 10.181 @@ -198,13 +198,13 @@ 10.182 <title>Useful shorthand&emdash;adding and removing files in one 10.183 step</title> 10.184 10.185 - <para>Mercurial offers a combination command, <command 10.186 + <para id="x_1ba">Mercurial offers a combination command, <command 10.187 role="hg-cmd">hg addremove</command>, that adds untracked 10.188 files and marks missing files as removed.</para> 10.189 10.190 &interaction.daily.files.addremove; 10.191 10.192 - <para>The <command role="hg-cmd">hg commit</command> command 10.193 + <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command 10.194 also provides a <option role="hg-opt-commit">-A</option> 10.195 option that performs this same add-and-remove, immediately 10.196 followed by a commit.</para> 10.197 @@ -216,7 +216,7 @@ 10.198 <sect1> 10.199 <title>Copying files</title> 10.200 10.201 - <para>Mercurial provides a <command role="hg-cmd">hg 10.202 + <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg 10.203 copy</command> command that lets you make a new copy of a 10.204 file. When you copy a file using this command, Mercurial makes 10.205 a record of the fact that the new file is a copy of the original 10.206 @@ -226,32 +226,32 @@ 10.207 <sect2> 10.208 <title>The results of copying during a merge</title> 10.209 10.210 - <para>What happens during a merge is that changes 10.211 + <para id="x_1bd">What happens during a merge is that changes 10.212 <quote>follow</quote> a copy. To best illustrate what this 10.213 means, let's create an example. We'll start with the usual 10.214 tiny repository that contains a single file.</para> 10.215 10.216 &interaction.daily.copy.init; 10.217 10.218 - <para>We need to do some work in 10.219 + <para id="x_1be">We need to do some work in 10.220 parallel, so that we'll have something to merge. So let's 10.221 clone our repository.</para> 10.222 10.223 &interaction.daily.copy.clone; 10.224 10.225 - <para>Back in our initial repository, let's use the <command 10.226 + <para id="x_1bf">Back in our initial repository, let's use the <command 10.227 role="hg-cmd">hg copy</command> command to make a copy of 10.228 the first file we created.</para> 10.229 10.230 &interaction.daily.copy.copy; 10.231 10.232 - <para>If we look at the output of the <command role="hg-cmd">hg 10.233 + <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg 10.234 status</command> command afterwards, the copied file looks 10.235 just like a normal added file.</para> 10.236 10.237 &interaction.daily.copy.status; 10.238 10.239 - <para>But if we pass the <option 10.240 + <para id="x_1c1">But if we pass the <option 10.241 role="hg-opt-status">-C</option> option to <command 10.242 role="hg-cmd">hg status</command>, it prints another line of 10.243 output: this is the file that our newly-added file was copied 10.244 @@ -259,13 +259,13 @@ 10.245 10.246 &interaction.daily.copy.status-copy; 10.247 10.248 - <para>Now, back in the repository we cloned, let's make a change 10.249 + <para id="x_1c2">Now, back in the repository we cloned, let's make a change 10.250 in parallel. We'll add a line of content to the original file 10.251 that we created.</para> 10.252 10.253 &interaction.daily.copy.other; 10.254 10.255 - <para>Now we have a modified <filename>file</filename> in this 10.256 + <para id="x_1c3">Now we have a modified <filename>file</filename> in this 10.257 repository. When we pull the changes from the first 10.258 repository, and merge the two heads, Mercurial will propagate 10.259 the changes that we made locally to <filename>file</filename> 10.260 @@ -277,41 +277,41 @@ 10.261 <sect2 id="sec:daily:why-copy"> 10.262 <title>Why should changes follow copies?</title> 10.263 10.264 - <para>This behaviour, of changes to a file propagating out to 10.265 + <para id="x_1c4">This behaviour, of changes to a file propagating out to 10.266 copies of the file, might seem esoteric, but in most cases 10.267 it's highly desirable.</para> 10.268 10.269 - <para>First of all, remember that this propagation 10.270 + <para id="x_1c5">First of all, remember that this propagation 10.271 <emphasis>only</emphasis> happens when you merge. So if you 10.272 <command role="hg-cmd">hg copy</command> a file, and 10.273 subsequently modify the original file during the normal course 10.274 of your work, nothing will happen.</para> 10.275 10.276 - <para>The second thing to know is that modifications will only 10.277 + <para id="x_1c6">The second thing to know is that modifications will only 10.278 propagate across a copy as long as the repository that you're 10.279 pulling changes from <emphasis>doesn't know</emphasis> about 10.280 the copy.</para> 10.281 10.282 - <para>The reason that Mercurial does this is as follows. Let's 10.283 + <para id="x_1c7">The reason that Mercurial does this is as follows. Let's 10.284 say I make an important bug fix in a source file, and commit 10.285 my changes. Meanwhile, you've decided to <command 10.286 role="hg-cmd">hg copy</command> the file in your repository, 10.287 without knowing about the bug or having seen the fix, and you 10.288 have started hacking on your copy of the file.</para> 10.289 10.290 - <para>If you pulled and merged my changes, and Mercurial 10.291 + <para id="x_1c8">If you pulled and merged my changes, and Mercurial 10.292 <emphasis>didn't</emphasis> propagate changes across copies, 10.293 your source file would now contain the bug, and unless you 10.294 remembered to propagate the bug fix by hand, the bug would 10.295 <emphasis>remain</emphasis> in your copy of the file.</para> 10.296 10.297 - <para>By automatically propagating the change that fixed the bug 10.298 + <para id="x_1c9">By automatically propagating the change that fixed the bug 10.299 from the original file to the copy, Mercurial prevents this 10.300 class of problem. To my knowledge, Mercurial is the 10.301 <emphasis>only</emphasis> revision control system that 10.302 propagates changes across copies like this.</para> 10.303 10.304 - <para>Once your change history has a record that the copy and 10.305 + <para id="x_1ca">Once your change history has a record that the copy and 10.306 subsequent merge occurred, there's usually no further need to 10.307 propagate changes from the original file to the copied file, 10.308 and that's why Mercurial only propagates changes across copies 10.309 @@ -322,7 +322,7 @@ 10.310 <title>How to make changes <emphasis>not</emphasis> follow a 10.311 copy</title> 10.312 10.313 - <para>If, for some reason, you decide that this business of 10.314 + <para id="x_1cb">If, for some reason, you decide that this business of 10.315 automatically propagating changes across copies is not for 10.316 you, simply use your system's normal file copy command (on 10.317 Unix-like systems, that's <command>cp</command>) to make a 10.318 @@ -338,7 +338,7 @@ 10.319 <title>Behaviour of the <command role="hg-cmd">hg copy</command> 10.320 command</title> 10.321 10.322 - <para>When you use the <command role="hg-cmd">hg copy</command> 10.323 + <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command> 10.324 command, Mercurial makes a copy of each source file as it 10.325 currently stands in the working directory. This means that if 10.326 you make some modifications to a file, then <command 10.327 @@ -348,7 +348,7 @@ 10.328 behaviour a little counterintuitive, which is why I mention it 10.329 here.)</para> 10.330 10.331 - <para>The <command role="hg-cmd">hg copy</command> command acts 10.332 + <para id="x_1cd">The <command role="hg-cmd">hg copy</command> command acts 10.333 similarly to the Unix <command>cp</command> command (you can 10.334 use the <command role="hg-cmd">hg cp</command> alias if you 10.335 prefer). The last argument is the 10.336 @@ -359,23 +359,23 @@ 10.337 10.338 &interaction.daily.copy.simple; 10.339 10.340 - <para>If the destination is a directory, Mercurial copies its 10.341 + <para id="x_1ce">If the destination is a directory, Mercurial copies its 10.342 sources into that directory.</para> 10.343 10.344 &interaction.daily.copy.dir-dest; 10.345 10.346 - <para>Copying a directory is 10.347 + <para id="x_1cf">Copying a directory is 10.348 recursive, and preserves the directory structure of the 10.349 source.</para> 10.350 10.351 &interaction.daily.copy.dir-src; 10.352 10.353 - <para>If the source and destination are both directories, the 10.354 + <para id="x_1d0">If the source and destination are both directories, the 10.355 source tree is recreated in the destination directory.</para> 10.356 10.357 &interaction.daily.copy.dir-src-dest; 10.358 10.359 - <para>As with the <command role="hg-cmd">hg rename</command> 10.360 + <para id="x_1d1">As with the <command role="hg-cmd">hg rename</command> 10.361 command, if you copy a file manually and then want Mercurial 10.362 to know that you've copied the file, simply use the <option 10.363 role="hg-opt-copy">--after</option> option to <command 10.364 @@ -388,7 +388,7 @@ 10.365 <sect1> 10.366 <title>Renaming files</title> 10.367 10.368 - <para>It's rather more common to need to rename a file than to 10.369 + <para id="x_1d2">It's rather more common to need to rename a file than to 10.370 make a copy of it. The reason I discussed the <command 10.371 role="hg-cmd">hg copy</command> command before talking about 10.372 renaming files is that Mercurial treats a rename in essentially 10.373 @@ -396,19 +396,19 @@ 10.374 when you copy a file tells you what to expect when you rename a 10.375 file.</para> 10.376 10.377 - <para>When you use the <command role="hg-cmd">hg rename</command> 10.378 + <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command> 10.379 command, Mercurial makes a copy of each source file, then 10.380 deletes it and marks the file as removed.</para> 10.381 10.382 &interaction.daily.rename.rename; 10.383 10.384 - <para>The <command role="hg-cmd">hg status</command> command shows 10.385 + <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows 10.386 the newly copied file as added, and the copied-from file as 10.387 removed.</para> 10.388 10.389 &interaction.daily.rename.status; 10.390 10.391 - <para>As with the results of a <command role="hg-cmd">hg 10.392 + <para id="x_1d5">As with the results of a <command role="hg-cmd">hg 10.393 copy</command>, we must use the <option 10.394 role="hg-opt-status">-C</option> option to <command 10.395 role="hg-cmd">hg status</command> to see that the added file 10.396 @@ -417,7 +417,7 @@ 10.397 10.398 &interaction.daily.rename.status-copy; 10.399 10.400 - <para>As with <command role="hg-cmd">hg remove</command> and 10.401 + <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and 10.402 <command role="hg-cmd">hg copy</command>, you can tell Mercurial 10.403 about a rename after the fact using the <option 10.404 role="hg-opt-rename">--after</option> option. In most other 10.405 @@ -429,18 +429,18 @@ 10.406 <sect2> 10.407 <title>Renaming files and merging changes</title> 10.408 10.409 - <para>Since Mercurial's rename is implemented as 10.410 + <para id="x_1d7">Since Mercurial's rename is implemented as 10.411 copy-and-remove, the same propagation of changes happens when 10.412 you merge after a rename as after a copy.</para> 10.413 10.414 - <para>If I modify a file, and you rename it to a new name, and 10.415 + <para id="x_1d8">If I modify a file, and you rename it to a new name, and 10.416 then we merge our respective changes, my modifications to the 10.417 file under its original name will be propagated into the file 10.418 under its new name. (This is something you might expect to 10.419 <quote>simply work,</quote> but not all revision control 10.420 systems actually do this.)</para> 10.421 10.422 - <para>Whereas having changes follow a copy is a feature where 10.423 + <para id="x_1d9">Whereas having changes follow a copy is a feature where 10.424 you can perhaps nod and say <quote>yes, that might be 10.425 useful,</quote> it should be clear that having them follow a 10.426 rename is definitely important. Without this facility, it 10.427 @@ -451,34 +451,34 @@ 10.428 <sect2> 10.429 <title>Divergent renames and merging</title> 10.430 10.431 - <para>The case of diverging names occurs when two developers 10.432 + <para id="x_1da">The case of diverging names occurs when two developers 10.433 start with a file&emdash;let's call it 10.434 <filename>foo</filename>&emdash;in their respective 10.435 repositories.</para> 10.436 10.437 &interaction.rename.divergent.clone; 10.438 10.439 - <para>Anne renames the file to <filename>bar</filename>.</para> 10.440 + <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para> 10.441 10.442 &interaction.rename.divergent.rename.anne; 10.443 10.444 - <para>Meanwhile, Bob renames it to 10.445 + <para id="x_1dc">Meanwhile, Bob renames it to 10.446 <filename>quux</filename>.</para> 10.447 10.448 &interaction.rename.divergent.rename.bob; 10.449 10.450 - <para>I like to think of this as a conflict because each 10.451 + <para id="x_1dd">I like to think of this as a conflict because each 10.452 developer has expressed different intentions about what the 10.453 file ought to be named.</para> 10.454 10.455 - <para>What do you think should happen when they merge their 10.456 + <para id="x_1de">What do you think should happen when they merge their 10.457 work? Mercurial's actual behaviour is that it always preserves 10.458 <emphasis>both</emphasis> names when it merges changesets that 10.459 contain divergent renames.</para> 10.460 10.461 &interaction.rename.divergent.merge; 10.462 10.463 - <para>Notice that Mercurial does warn about the divergent 10.464 + <para id="x_1df">Notice that Mercurial does warn about the divergent 10.465 renames, but it leaves it up to you to do something about the 10.466 divergence after the merge.</para> 10.467 10.468 @@ -486,7 +486,7 @@ 10.469 <sect2> 10.470 <title>Convergent renames and merging</title> 10.471 10.472 - <para>Another kind of rename conflict occurs when two people 10.473 + <para id="x_1e0">Another kind of rename conflict occurs when two people 10.474 choose to rename different <emphasis>source</emphasis> files 10.475 to the same <emphasis>destination</emphasis>. In this case, 10.476 Mercurial runs its normal merge machinery, and lets you guide 10.477 @@ -496,7 +496,7 @@ 10.478 <sect2> 10.479 <title>Other name-related corner cases</title> 10.480 10.481 - <para>Mercurial has a longstanding bug in which it fails to 10.482 + <para id="x_1e1">Mercurial has a longstanding bug in which it fails to 10.483 handle a merge where one side has a file with a given name, 10.484 while another has a directory with the same name. This is 10.485 documented as <ulink role="hg-bug" 10.486 @@ -510,10 +510,10 @@ 10.487 <sect1> 10.488 <title>Recovering from mistakes</title> 10.489 10.490 - <para>Mercurial has some useful commands that will help you to 10.491 + <para id="x_1e2">Mercurial has some useful commands that will help you to 10.492 recover from some common mistakes.</para> 10.493 10.494 - <para>The <command role="hg-cmd">hg revert</command> command lets 10.495 + <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets 10.496 you undo changes that you have made to your working directory. 10.497 For example, if you <command role="hg-cmd">hg add</command> a 10.498 file by accident, just run <command role="hg-cmd">hg 10.499 @@ -523,13 +523,13 @@ 10.500 <command role="hg-cmd">hg revert</command> to get rid of 10.501 erroneous changes to a file.</para> 10.502 10.503 - <para>It's useful to remember that the <command role="hg-cmd">hg 10.504 + <para id="x_1e4">It's useful to remember that the <command role="hg-cmd">hg 10.505 revert</command> command is useful for changes that you have 10.506 not yet committed. Once you've committed a change, if you 10.507 decide it was a mistake, you can still do something about it, 10.508 though your options may be more limited.</para> 10.509 10.510 - <para>For more information about the <command role="hg-cmd">hg 10.511 + <para id="x_1e5">For more information about the <command role="hg-cmd">hg 10.512 revert</command> command, and details about how to deal with 10.513 changes you have already committed, see chapter <xref 10.514 linkend="chap:undo"/>.</para>
11.1 --- a/en/ch05-collab.xml Thu Mar 19 20:54:12 2009 -0700 11.2 +++ b/en/ch05-collab.xml Thu Mar 19 21:18:52 2009 -0700 11.3 @@ -4,7 +4,7 @@ 11.4 <?dbhtml filename="collaborating-with-other-people.html"?> 11.5 <title>Collaborating with other people</title> 11.6 11.7 - <para>As a completely decentralised tool, Mercurial doesn't impose 11.8 + <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 11.9 any policy on how people ought to work with each other. However, 11.10 if you're new to distributed revision control, it helps to have 11.11 some tools and examples in mind when you're thinking about 11.12 @@ -13,15 +13,15 @@ 11.13 <sect1> 11.14 <title>Mercurial's web interface</title> 11.15 11.16 - <para>Mercurial has a powerful web interface that provides several 11.17 + <para id="x_44b">Mercurial has a powerful web interface that provides several 11.18 useful capabilities.</para> 11.19 11.20 - <para>For interactive use, the web interface lets you browse a 11.21 + <para id="x_44c">For interactive use, the web interface lets you browse a 11.22 single repository or a collection of repositories. You can view 11.23 the history of a repository, examine each change (comments and 11.24 diffs), and view the contents of each directory and file.</para> 11.25 11.26 - <para>Also for human consumption, the web interface provides an 11.27 + <para id="x_44d">Also for human consumption, the web interface provides an 11.28 RSS feed of the changes in a repository. This lets you 11.29 <quote>subscribe</quote> to a repository using your favourite 11.30 feed reader, and be automatically notified of activity in that 11.31 @@ -31,18 +31,18 @@ 11.32 configuration on the part of whoever is serving the 11.33 repository.</para> 11.34 11.35 - <para>The web interface also lets remote users clone a repository, 11.36 + <para id="x_44e">The web interface also lets remote users clone a repository, 11.37 pull changes from it, and (when the server is configured to 11.38 permit it) push changes back to it. Mercurial's HTTP tunneling 11.39 protocol aggressively compresses data, so that it works 11.40 efficiently even over low-bandwidth network connections.</para> 11.41 11.42 - <para>The easiest way to get started with the web interface is to 11.43 + <para id="x_44f">The easiest way to get started with the web interface is to 11.44 use your web browser to visit an existing repository, such as 11.45 the master Mercurial repository at <ulink 11.46 url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para> 11.47 11.48 - <para>If you're interested in providing a web interface to your 11.49 + <para id="x_450">If you're interested in providing a web interface to your 11.50 own repositories, Mercurial provides two ways to do this. The 11.51 first is using the <command role="hg-cmd">hg serve</command> 11.52 command, which is best suited to short-term 11.53 @@ -59,7 +59,7 @@ 11.54 <sect1> 11.55 <title>Collaboration models</title> 11.56 11.57 - <para>With a suitably flexible tool, making decisions about 11.58 + <para id="x_451">With a suitably flexible tool, making decisions about 11.59 workflow is much more of a social engineering challenge than a 11.60 technical one. Mercurial imposes few limitations on how you can 11.61 structure the flow of work in a project, so it's up to you and 11.62 @@ -69,13 +69,13 @@ 11.63 <sect2> 11.64 <title>Factors to keep in mind</title> 11.65 11.66 - <para>The most important aspect of any model that you must keep 11.67 + <para id="x_452">The most important aspect of any model that you must keep 11.68 in mind is how well it matches the needs and capabilities of 11.69 the people who will be using it. This might seem 11.70 self-evident; even so, you still can't afford to forget it for 11.71 a moment.</para> 11.72 11.73 - <para>I once put together a workflow model that seemed to make 11.74 + <para id="x_453">I once put together a workflow model that seemed to make 11.75 perfect sense to me, but that caused a considerable amount of 11.76 consternation and strife within my development team. In spite 11.77 of my attempts to explain why we needed a complex set of 11.78 @@ -85,7 +85,7 @@ 11.79 operating under, or face the consequences of those constraints 11.80 in the details of the model that I was advocating.</para> 11.81 11.82 - <para>Don't sweep foreseeable social or technical problems under 11.83 + <para id="x_454">Don't sweep foreseeable social or technical problems under 11.84 the rug. Whatever scheme you put into effect, you should plan 11.85 for mistakes and problem scenarios. Consider adding automated 11.86 machinery to prevent, or quickly recover from, trouble that 11.87 @@ -101,12 +101,12 @@ 11.88 <sect2> 11.89 <title>Informal anarchy</title> 11.90 11.91 - <para>I wouldn't suggest an <quote>anything goes</quote> 11.92 + <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 11.93 approach as something sustainable, but it's a model that's 11.94 easy to grasp, and it works perfectly well in a few unusual 11.95 situations.</para> 11.96 11.97 - <para>As one example, many projects have a loose-knit group of 11.98 + <para id="x_456">As one example, many projects have a loose-knit group of 11.99 collaborators who rarely physically meet each other. Some 11.100 groups like to overcome the isolation of working at a distance 11.101 by organising occasional <quote>sprints</quote>. In a sprint, 11.102 @@ -115,7 +115,7 @@ 11.103 place) and spend several days more or less locked in there, 11.104 hacking intensely on a handful of projects.</para> 11.105 11.106 - <para>A sprint is the perfect place to use the <command 11.107 + <para id="x_457">A sprint is the perfect place to use the <command 11.108 role="hg-cmd">hg serve</command> command, since <command 11.109 role="hg-cmd">hg serve</command> does not require any fancy 11.110 server infrastructure. You can get started with <command 11.111 @@ -129,7 +129,7 @@ 11.112 they can pull a bugfix from you and verify it; or they can 11.113 clone a branch containing a new feature and try it out.</para> 11.114 11.115 - <para>The charm, and the problem, with doing things in an ad hoc 11.116 + <para id="x_458">The charm, and the problem, with doing things in an ad hoc 11.117 fashion like this is that only people who know about your 11.118 changes, and where they are, can see them. Such an informal 11.119 approach simply doesn't scale beyond a handful people, because 11.120 @@ -140,18 +140,18 @@ 11.121 <sect2> 11.122 <title>A single central repository</title> 11.123 11.124 - <para>For smaller projects migrating from a centralised revision 11.125 + <para id="x_459">For smaller projects migrating from a centralised revision 11.126 control tool, perhaps the easiest way to get started is to 11.127 have changes flow through a single shared central repository. 11.128 This is also the most common <quote>building block</quote> for 11.129 more ambitious workflow schemes.</para> 11.130 11.131 - <para>Contributors start by cloning a copy of this repository. 11.132 + <para id="x_45a">Contributors start by cloning a copy of this repository. 11.133 They can pull changes from it whenever they need to, and some 11.134 (perhaps all) developers have permission to push a change back 11.135 when they're ready for other people to see it.</para> 11.136 11.137 - <para>Under this model, it can still often make sense for people 11.138 + <para id="x_45b">Under this model, it can still often make sense for people 11.139 to pull changes directly from each other, without going 11.140 through the central repository. Consider a case in which I 11.141 have a tentative bug fix, but I am worried that if I were to 11.142 @@ -162,7 +162,7 @@ 11.143 lets us put off publishing the potentially unsafe change until 11.144 it has had a little testing.</para> 11.145 11.146 - <para>In this kind of scenario, people usually use the 11.147 + <para id="x_45c">In this kind of scenario, people usually use the 11.148 <command>ssh</command> protocol to securely push changes to 11.149 the central repository, as documented in section <xref 11.150 linkend="sec:collab:ssh"/>. It's also 11.151 @@ -177,7 +177,7 @@ 11.152 <sect2> 11.153 <title>Working with multiple branches</title> 11.154 11.155 - <para>Projects of any significant size naturally tend to make 11.156 + <para id="x_45d">Projects of any significant size naturally tend to make 11.157 progress on several fronts simultaneously. In the case of 11.158 software, it's common for a project to go through periodic 11.159 official releases. A release might then go into 11.160 @@ -190,7 +190,7 @@ 11.161 different directions in which development is 11.162 proceeding.</para> 11.163 11.164 - <para>Mercurial is particularly well suited to managing a number 11.165 + <para id="x_45e">Mercurial is particularly well suited to managing a number 11.166 of simultaneous, but not identical, branches. Each 11.167 <quote>development direction</quote> can live in its own 11.168 central repository, and you can merge changes from one to 11.169 @@ -199,27 +199,27 @@ 11.170 branch will never affect a stable branch unless someone 11.171 explicitly merges those changes in.</para> 11.172 11.173 - <para>Here's an example of how this can work in practice. Let's 11.174 + <para id="x_45f">Here's an example of how this can work in practice. Let's 11.175 say you have one <quote>main branch</quote> on a central 11.176 server.</para> 11.177 11.178 &interaction.branching.init; 11.179 11.180 - <para>People clone it, make changes locally, test them, and push 11.181 + <para id="x_460">People clone it, make changes locally, test them, and push 11.182 them back.</para> 11.183 11.184 - <para>Once the main branch reaches a release milestone, you can 11.185 + <para id="x_461">Once the main branch reaches a release milestone, you can 11.186 use the <command role="hg-cmd">hg tag</command> command to 11.187 give a permanent name to the milestone revision.</para> 11.188 11.189 &interaction.branching.tag; 11.190 11.191 - <para>Let's say some ongoing 11.192 + <para id="x_462">Let's say some ongoing 11.193 development occurs on the main branch.</para> 11.194 11.195 &interaction.branching.main; 11.196 11.197 - <para>Using the tag that was recorded at the milestone, people 11.198 + <para id="x_463">Using the tag that was recorded at the milestone, people 11.199 who clone that repository at any time in the future can use 11.200 <command role="hg-cmd">hg update</command> to get a copy of 11.201 the working directory exactly as it was when that tagged 11.202 @@ -227,26 +227,26 @@ 11.203 11.204 &interaction.branching.update; 11.205 11.206 - <para>In addition, immediately after the main branch is tagged, 11.207 + <para id="x_464">In addition, immediately after the main branch is tagged, 11.208 someone can then clone the main branch on the server to a new 11.209 <quote>stable</quote> branch, also on the server.</para> 11.210 11.211 &interaction.branching.clone; 11.212 11.213 - <para>Someone who needs to make a change to the stable branch 11.214 + <para id="x_465">Someone who needs to make a change to the stable branch 11.215 can then clone <emphasis>that</emphasis> repository, make 11.216 their changes, commit, and push their changes back there.</para> 11.217 11.218 &interaction.branching.stable; 11.219 11.220 - <para>Because Mercurial repositories are independent, and 11.221 + <para id="x_466">Because Mercurial repositories are independent, and 11.222 Mercurial doesn't move changes around automatically, the 11.223 stable and main branches are <emphasis>isolated</emphasis> 11.224 from each other. The changes that you made on the main branch 11.225 don't <quote>leak</quote> to the stable branch, and vice 11.226 versa.</para> 11.227 11.228 - <para>You'll often want all of your bugfixes on the stable 11.229 + <para id="x_467">You'll often want all of your bugfixes on the stable 11.230 branch to show up on the main branch, too. Rather than 11.231 rewrite a bugfix on the main branch, you can simply pull and 11.232 merge changes from the stable to the main branch, and 11.233 @@ -254,7 +254,7 @@ 11.234 11.235 &interaction.branching.merge; 11.236 11.237 - <para>The main branch will still contain changes that are not on 11.238 + <para id="x_468">The main branch will still contain changes that are not on 11.239 the stable branch, but it will also contain all of the 11.240 bugfixes from the stable branch. The stable branch remains 11.241 unaffected by these changes.</para> 11.242 @@ -263,7 +263,7 @@ 11.243 <sect2> 11.244 <title>Feature branches</title> 11.245 11.246 - <para>For larger projects, an effective way to manage change is 11.247 + <para id="x_469">For larger projects, an effective way to manage change is 11.248 to break up a team into smaller groups. Each group has a 11.249 shared branch of its own, cloned from a single 11.250 <quote>master</quote> branch used by the entire project. 11.251 @@ -273,11 +273,11 @@ 11.252 <informalfigure id="fig:collab:feature-branches"> 11.253 <mediaobject><imageobject><imagedata 11.254 fileref="feature-branches"/></imageobject><textobject><phrase>XXX 11.255 - add text</phrase></textobject><caption><para>Feature 11.256 + add text</phrase></textobject><caption><para id="x_46a">Feature 11.257 branches</para></caption></mediaobject> 11.258 </informalfigure> 11.259 11.260 - <para>When a particular feature is deemed to be in suitable 11.261 + <para id="x_46b">When a particular feature is deemed to be in suitable 11.262 shape, someone on that feature team pulls and merges from the 11.263 master branch into the feature branch, then pushes back up to 11.264 the master branch.</para> 11.265 @@ -286,12 +286,12 @@ 11.266 <sect2> 11.267 <title>The release train</title> 11.268 11.269 - <para>Some projects are organised on a <quote>train</quote> 11.270 + <para id="x_46c">Some projects are organised on a <quote>train</quote> 11.271 basis: a release is scheduled to happen every few months, and 11.272 whatever features are ready when the <quote>train</quote> is 11.273 ready to leave are allowed in.</para> 11.274 11.275 - <para>This model resembles working with feature branches. The 11.276 + <para id="x_46d">This model resembles working with feature branches. The 11.277 difference is that when a feature branch misses a train, 11.278 someone on the feature team pulls and merges the changes that 11.279 went out on that train release into the feature branch, and 11.280 @@ -302,7 +302,7 @@ 11.281 <sect2> 11.282 <title>The Linux kernel model</title> 11.283 11.284 - <para>The development of the Linux kernel has a shallow 11.285 + <para id="x_46e">The development of the Linux kernel has a shallow 11.286 hierarchical structure, surrounded by a cloud of apparent 11.287 chaos. Because most Linux developers use 11.288 <command>git</command>, a distributed revision control tool 11.289 @@ -310,14 +310,14 @@ 11.290 describe the way work flows in that environment; if you like 11.291 the ideas, the approach translates well across tools.</para> 11.292 11.293 - <para>At the center of the community sits Linus Torvalds, the 11.294 + <para id="x_46f">At the center of the community sits Linus Torvalds, the 11.295 creator of Linux. He publishes a single source repository 11.296 that is considered the <quote>authoritative</quote> current 11.297 tree by the entire developer community. Anyone can clone 11.298 Linus's tree, but he is very choosy about whose trees he pulls 11.299 from.</para> 11.300 11.301 - <para>Linus has a number of <quote>trusted lieutenants</quote>. 11.302 + <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 11.303 As a general rule, he pulls whatever changes they publish, in 11.304 most cases without even reviewing those changes. Some of 11.305 those lieutenants are generally agreed to be 11.306 @@ -329,7 +329,7 @@ 11.307 If the maintainer reviews their changes and agrees to take 11.308 them, they'll pass them along to Linus in due course.</para> 11.309 11.310 - <para>Individual lieutenants have their own approaches to 11.311 + <para id="x_471">Individual lieutenants have their own approaches to 11.312 reviewing, accepting, and publishing changes; and for deciding 11.313 when to feed them to Linus. In addition, there are several 11.314 well known branches that people use for different purposes. 11.315 @@ -340,14 +340,14 @@ 11.316 that they are about to feed upstream; and so on. Others just 11.317 publish a single tree.</para> 11.318 11.319 - <para>This model has two notable features. The first is that 11.320 + <para id="x_472">This model has two notable features. The first is that 11.321 it's <quote>pull only</quote>. You have to ask, convince, or 11.322 beg another developer to take a change from you, because there 11.323 are almost no trees to which more than one person can push, 11.324 and there's no way to push changes into a tree that someone 11.325 else controls.</para> 11.326 11.327 - <para>The second is that it's based on reputation and acclaim. 11.328 + <para id="x_473">The second is that it's based on reputation and acclaim. 11.329 If you're an unknown, Linus will probably ignore changes from 11.330 you without even responding. But a subsystem maintainer will 11.331 probably review them, and will likely take them if they pass 11.332 @@ -358,14 +358,14 @@ 11.333 Linus hasn't yet accepted, people with similar interests may 11.334 pull your changes regularly to keep up with your work.</para> 11.335 11.336 - <para>Reputation and acclaim don't necessarily cross subsystem 11.337 + <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 11.338 or <quote>people</quote> boundaries. If you're a respected 11.339 but specialised storage hacker, and you try to fix a 11.340 networking bug, that change will receive a level of scrutiny 11.341 from a network maintainer comparable to a change from a 11.342 complete stranger.</para> 11.343 11.344 - <para>To people who come from more orderly project backgrounds, 11.345 + <para id="x_475">To people who come from more orderly project backgrounds, 11.346 the comparatively chaotic Linux kernel development process 11.347 often seems completely insane. It's subject to the whims of 11.348 individuals; people make sweeping changes whenever they deem 11.349 @@ -377,13 +377,13 @@ 11.350 <sect2> 11.351 <title>Pull-only versus shared-push collaboration</title> 11.352 11.353 - <para>A perpetual source of heat in the open source community is 11.354 + <para id="x_476">A perpetual source of heat in the open source community is 11.355 whether a development model in which people only ever pull 11.356 changes from others is <quote>better than</quote> one in which 11.357 multiple people can push changes to a shared 11.358 repository.</para> 11.359 11.360 - <para>Typically, the backers of the shared-push model use tools 11.361 + <para id="x_477">Typically, the backers of the shared-push model use tools 11.362 that actively enforce this approach. If you're using a 11.363 centralised revision control tool such as Subversion, there's 11.364 no way to make a choice over which model you'll use: the tool 11.365 @@ -391,7 +391,7 @@ 11.366 you'll have to roll your own approach on top (such as applying 11.367 a patch by hand).</para> 11.368 11.369 - <para>A good distributed revision control tool, such as 11.370 + <para id="x_478">A good distributed revision control tool, such as 11.371 Mercurial, will support both models. You and your 11.372 collaborators can then structure how you work together based 11.373 on your own needs and preferences, not on what contortions 11.374 @@ -401,7 +401,7 @@ 11.375 <sect2> 11.376 <title>Where collaboration meets branch management</title> 11.377 11.378 - <para>Once you and your team set up some shared repositories and 11.379 + <para id="x_479">Once you and your team set up some shared repositories and 11.380 start propagating changes back and forth between local and 11.381 shared repos, you begin to face a related, but slightly 11.382 different challenge: that of managing the multiple directions 11.383 @@ -415,7 +415,7 @@ 11.384 <sect1> 11.385 <title>The technical side of sharing</title> 11.386 11.387 - <para>The remainder of this chapter is devoted to the question of 11.388 + <para id="x_47a">The remainder of this chapter is devoted to the question of 11.389 serving data to your collaborators.</para> 11.390 11.391 </sect1> 11.392 @@ -423,12 +423,12 @@ 11.393 <title>Informal sharing with <command role="hg-cmd">hg 11.394 serve</command></title> 11.395 11.396 - <para>Mercurial's <command role="hg-cmd">hg serve</command> 11.397 + <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 11.398 command is wonderfully suited to small, tight-knit, and 11.399 fast-paced group environments. It also provides a great way to 11.400 get a feel for using Mercurial commands over a network.</para> 11.401 11.402 - <para>Run <command role="hg-cmd">hg serve</command> inside a 11.403 + <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 11.404 repository, and in under a second it will bring up a specialised 11.405 HTTP server; this will accept connections from any client, and 11.406 serve up data for that repository until you terminate it. 11.407 @@ -439,24 +439,24 @@ 11.408 on a laptop is likely to look something like 11.409 <literal>http://my-laptop.local:8000/</literal>.</para> 11.410 11.411 - <para>The <command role="hg-cmd">hg serve</command> command is 11.412 + <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 11.413 <emphasis>not</emphasis> a general-purpose web server. It can do 11.414 only two things:</para> 11.415 <itemizedlist> 11.416 - <listitem><para>Allow people to browse the history of the 11.417 + <listitem><para id="x_47e">Allow people to browse the history of the 11.418 repository it's serving, from their normal web 11.419 browsers.</para> 11.420 </listitem> 11.421 - <listitem><para>Speak Mercurial's wire protocol, so that people 11.422 + <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 11.423 can <command role="hg-cmd">hg clone</command> or <command 11.424 role="hg-cmd">hg pull</command> changes from that 11.425 repository.</para> 11.426 </listitem></itemizedlist> 11.427 - <para>In particular, <command role="hg-cmd">hg serve</command> 11.428 + <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 11.429 won't allow remote users to <emphasis>modify</emphasis> your 11.430 repository. It's intended for read-only use.</para> 11.431 11.432 - <para>If you're getting started with Mercurial, there's nothing to 11.433 + <para id="x_481">If you're getting started with Mercurial, there's nothing to 11.434 prevent you from using <command role="hg-cmd">hg serve</command> 11.435 to serve up a repository on your own computer, then use commands 11.436 like <command role="hg-cmd">hg clone</command>, <command 11.437 @@ -468,13 +468,13 @@ 11.438 <sect2> 11.439 <title>A few things to keep in mind</title> 11.440 11.441 - <para>Because it provides unauthenticated read access to all 11.442 + <para id="x_482">Because it provides unauthenticated read access to all 11.443 clients, you should only use <command role="hg-cmd">hg 11.444 serve</command> in an environment where you either don't 11.445 care, or have complete control over, who can access your 11.446 network and pull data from your repository.</para> 11.447 11.448 - <para>The <command role="hg-cmd">hg serve</command> command 11.449 + <para id="x_483">The <command role="hg-cmd">hg serve</command> command 11.450 knows nothing about any firewall software you might have 11.451 installed on your system or network. It cannot detect or 11.452 control your firewall software. If other people are unable to 11.453 @@ -483,13 +483,13 @@ 11.454 (<emphasis>after</emphasis> you make sure that they're using 11.455 the correct URL) is check your firewall configuration.</para> 11.456 11.457 - <para>By default, <command role="hg-cmd">hg serve</command> 11.458 + <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 11.459 listens for incoming connections on port 8000. If another 11.460 process is already listening on the port you want to use, you 11.461 can specify a different port to listen on using the <option 11.462 role="hg-opt-serve">-p</option> option.</para> 11.463 11.464 - <para>Normally, when <command role="hg-cmd">hg serve</command> 11.465 + <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 11.466 starts, it prints no output, which can be a bit unnerving. If 11.467 you'd like to confirm that it is indeed running correctly, and 11.468 find out what URL you should send to your collaborators, start 11.469 @@ -501,56 +501,56 @@ 11.470 <sect1 id="sec:collab:ssh"> 11.471 <title>Using the Secure Shell (ssh) protocol</title> 11.472 11.473 - <para>You can pull and push changes securely over a network 11.474 + <para id="x_486">You can pull and push changes securely over a network 11.475 connection using the Secure Shell (<literal>ssh</literal>) 11.476 protocol. To use this successfully, you may have to do a little 11.477 bit of configuration on the client or server sides.</para> 11.478 11.479 - <para>If you're not familiar with ssh, it's a network protocol 11.480 + <para id="x_487">If you're not familiar with ssh, it's a network protocol 11.481 that lets you securely communicate with another computer. To 11.482 use it with Mercurial, you'll be setting up one or more user 11.483 accounts on a server so that remote users can log in and execute 11.484 commands.</para> 11.485 11.486 - <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll 11.487 + <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 11.488 probably find some of the material that follows to be elementary 11.489 in nature.)</para> 11.490 11.491 <sect2> 11.492 <title>How to read and write ssh URLs</title> 11.493 11.494 - <para>An ssh URL tends to look like this:</para> 11.495 + <para id="x_489">An ssh URL tends to look like this:</para> 11.496 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 11.497 <orderedlist> 11.498 - <listitem><para>The <quote><literal>ssh://</literal></quote> 11.499 + <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 11.500 part tells Mercurial to use the ssh protocol.</para> 11.501 </listitem> 11.502 - <listitem><para>The <quote><literal>bos@</literal></quote> 11.503 + <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 11.504 component indicates what username to log into the server 11.505 as. You can leave this out if the remote username is the 11.506 same as your local username.</para> 11.507 </listitem> 11.508 - <listitem><para>The 11.509 + <listitem><para id="x_48c">The 11.510 <quote><literal>hg.serpentine.com</literal></quote> gives 11.511 the hostname of the server to log into.</para> 11.512 </listitem> 11.513 - <listitem><para>The <quote>:22</quote> identifies the port 11.514 + <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 11.515 number to connect to the server on. The default port is 11.516 22, so you only need to specify a colon and port number if 11.517 you're <emphasis>not</emphasis> using port 22.</para> 11.518 </listitem> 11.519 - <listitem><para>The remainder of the URL is the local path to 11.520 + <listitem><para id="x_48e">The remainder of the URL is the local path to 11.521 the repository on the server.</para> 11.522 </listitem></orderedlist> 11.523 11.524 - <para>There's plenty of scope for confusion with the path 11.525 + <para id="x_48f">There's plenty of scope for confusion with the path 11.526 component of ssh URLs, as there is no standard way for tools 11.527 to interpret it. Some programs behave differently than others 11.528 when dealing with these paths. This isn't an ideal situation, 11.529 but it's unlikely to change. Please read the following 11.530 paragraphs carefully.</para> 11.531 11.532 - <para>Mercurial treats the path to a repository on the server as 11.533 + <para id="x_490">Mercurial treats the path to a repository on the server as 11.534 relative to the remote user's home directory. For example, if 11.535 user <literal>foo</literal> on the server has a home directory 11.536 of <filename class="directory">/home/foo</filename>, then an 11.537 @@ -559,13 +559,13 @@ 11.538 refers to the directory <filename 11.539 class="directory">/home/foo/bar</filename>.</para> 11.540 11.541 - <para>If you want to specify a path relative to another user's 11.542 + <para id="x_491">If you want to specify a path relative to another user's 11.543 home directory, you can use a path that starts with a tilde 11.544 character followed by the user's name (let's call them 11.545 <literal>otheruser</literal>), like this.</para> 11.546 <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 11.547 11.548 - <para>And if you really want to specify an 11.549 + <para id="x_492">And if you really want to specify an 11.550 <emphasis>absolute</emphasis> path on the server, begin the 11.551 path component with two slashes, as in this example.</para> 11.552 <programlisting>ssh://server//absolute/path</programlisting> 11.553 @@ -574,7 +574,7 @@ 11.554 <sect2> 11.555 <title>Finding an ssh client for your system</title> 11.556 11.557 - <para>Almost every Unix-like system comes with OpenSSH 11.558 + <para id="x_493">Almost every Unix-like system comes with OpenSSH 11.559 preinstalled. If you're using such a system, run 11.560 <literal>which ssh</literal> to find out if the 11.561 <command>ssh</command> command is installed (it's usually in 11.562 @@ -582,17 +582,17 @@ 11.563 unlikely event that it isn't present, take a look at your 11.564 system documentation to figure out how to install it.</para> 11.565 11.566 - <para>On Windows, you'll first need to download a suitable ssh 11.567 + <para id="x_494">On Windows, you'll first need to download a suitable ssh 11.568 client. There are two alternatives.</para> 11.569 <itemizedlist> 11.570 - <listitem><para>Simon Tatham's excellent PuTTY package 11.571 + <listitem><para id="x_495">Simon Tatham's excellent PuTTY package 11.572 <citation>web:putty</citation> provides a complete suite 11.573 of ssh client commands.</para> 11.574 </listitem> 11.575 - <listitem><para>If you have a high tolerance for pain, you can 11.576 + <listitem><para id="x_496">If you have a high tolerance for pain, you can 11.577 use the Cygwin port of OpenSSH.</para> 11.578 </listitem></itemizedlist> 11.579 - <para>In either case, you'll need to edit your <filename 11.580 + <para id="x_497">In either case, you'll need to edit your <filename 11.581 role="special">hg.ini</filename> file to 11.582 tell Mercurial where to find the actual client command. For 11.583 example, if you're using PuTTY, you'll need to use the 11.584 @@ -602,7 +602,7 @@ 11.585 ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting> 11.586 11.587 <note> 11.588 - <para> The path to <command>plink</command> shouldn't contain 11.589 + <para id="x_498"> The path to <command>plink</command> shouldn't contain 11.590 any whitespace characters, or Mercurial may not be able to 11.591 run it correctly (so putting it in <filename 11.592 class="directory">C:\Program Files</filename> is probably 11.593 @@ -613,7 +613,7 @@ 11.594 <sect2> 11.595 <title>Generating a key pair</title> 11.596 11.597 - <para>To avoid the need to repetitively type a password every 11.598 + <para id="x_499">To avoid the need to repetitively type a password every 11.599 time you need to use your ssh client, I recommend generating a 11.600 key pair. On a Unix-like system, the 11.601 <command>ssh-keygen</command> command will do the trick. On 11.602 @@ -621,13 +621,13 @@ 11.603 <command>puttygen</command> command is what you'll 11.604 need.</para> 11.605 11.606 - <para>When you generate a key pair, it's usually 11.607 + <para id="x_49a">When you generate a key pair, it's usually 11.608 <emphasis>highly</emphasis> advisable to protect it with a 11.609 passphrase. (The only time that you might not want to do this 11.610 is when you're using the ssh protocol for automated tasks on a 11.611 secure network.)</para> 11.612 11.613 - <para>Simply generating a key pair isn't enough, however. 11.614 + <para id="x_49b">Simply generating a key pair isn't enough, however. 11.615 You'll need to add the public key to the set of authorised 11.616 keys for whatever user you're logging in remotely as. For 11.617 servers using OpenSSH (the vast majority), this will mean 11.618 @@ -636,7 +636,7 @@ 11.619 role="special" class="directory">.ssh</filename> 11.620 directory.</para> 11.621 11.622 - <para>On a Unix-like system, your public key will have a 11.623 + <para id="x_49c">On a Unix-like system, your public key will have a 11.624 <filename>.pub</filename> extension. If you're using 11.625 <command>puttygen</command> on Windows, you can save the 11.626 public key to a file of your choosing, or paste it from the 11.627 @@ -647,7 +647,7 @@ 11.628 <sect2> 11.629 <title>Using an authentication agent</title> 11.630 11.631 - <para>An authentication agent is a daemon that stores 11.632 + <para id="x_49d">An authentication agent is a daemon that stores 11.633 passphrases in memory (so it will forget passphrases if you 11.634 log out and log back in again). An ssh client will notice if 11.635 it's running, and query it for a passphrase. If there's no 11.636 @@ -656,14 +656,14 @@ 11.637 every time Mercurial tries to communicate with a server on 11.638 your behalf (e.g. whenever you pull or push changes).</para> 11.639 11.640 - <para>The downside of storing passphrases in an agent is that 11.641 + <para id="x_49e">The downside of storing passphrases in an agent is that 11.642 it's possible for a well-prepared attacker to recover the 11.643 plain text of your passphrases, in some cases even if your 11.644 system has been power-cycled. You should make your own 11.645 judgment as to whether this is an acceptable risk. It 11.646 certainly saves a lot of repeated typing.</para> 11.647 11.648 - <para>On Unix-like systems, the agent is called 11.649 + <para id="x_49f">On Unix-like systems, the agent is called 11.650 <command>ssh-agent</command>, and it's often run automatically 11.651 for you when you log in. You'll need to use the 11.652 <command>ssh-add</command> command to add passphrases to the 11.653 @@ -676,7 +676,7 @@ 11.654 <sect2> 11.655 <title>Configuring the server side properly</title> 11.656 11.657 - <para>Because ssh can be fiddly to set up if you're new to it, 11.658 + <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 11.659 there's a variety of things that can go wrong. Add Mercurial 11.660 on top, and there's plenty more scope for head-scratching. 11.661 Most of these potential problems occur on the server side, not 11.662 @@ -684,7 +684,7 @@ 11.663 configuration working, it will usually continue to work 11.664 indefinitely.</para> 11.665 11.666 - <para>Before you try using Mercurial to talk to an ssh server, 11.667 + <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 11.668 it's best to make sure that you can use the normal 11.669 <command>ssh</command> or <command>putty</command> command to 11.670 talk to the server first. If you run into problems with using 11.671 @@ -695,29 +695,29 @@ 11.672 <emphasis>before</emphasis> you worry about whether there's a 11.673 problem with Mercurial.</para> 11.674 11.675 - <para>The first thing to be sure of on the server side is that 11.676 + <para id="x_4a2">The first thing to be sure of on the server side is that 11.677 you can actually log in from another machine at all. If you 11.678 can't use <command>ssh</command> or <command>putty</command> 11.679 to log in, the error message you get may give you a few hints 11.680 as to what's wrong. The most common problems are as 11.681 follows.</para> 11.682 <itemizedlist> 11.683 - <listitem><para>If you get a <quote>connection refused</quote> 11.684 + <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 11.685 error, either there isn't an SSH daemon running on the 11.686 server at all, or it's inaccessible due to firewall 11.687 configuration.</para> 11.688 </listitem> 11.689 - <listitem><para>If you get a <quote>no route to host</quote> 11.690 + <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 11.691 error, you either have an incorrect address for the server 11.692 or a seriously locked down firewall that won't admit its 11.693 existence at all.</para> 11.694 </listitem> 11.695 - <listitem><para>If you get a <quote>permission denied</quote> 11.696 + <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 11.697 error, you may have mistyped the username on the server, 11.698 or you could have mistyped your key's passphrase or the 11.699 remote user's password.</para> 11.700 </listitem></itemizedlist> 11.701 - <para>In summary, if you're having trouble talking to the 11.702 + <para id="x_4a6">In summary, if you're having trouble talking to the 11.703 server's ssh daemon, first make sure that one is running at 11.704 all. On many systems it will be installed, but disabled, by 11.705 default. Once you're done with this step, you should then 11.706 @@ -727,23 +727,23 @@ 11.707 for misconfiguration until you've checked these two 11.708 first.</para> 11.709 11.710 - <para>If you're using an authentication agent on the client side 11.711 + <para id="x_4a7">If you're using an authentication agent on the client side 11.712 to store passphrases for your keys, you ought to be able to 11.713 log into the server without being prompted for a passphrase or 11.714 a password. If you're prompted for a passphrase, there are a 11.715 few possible culprits.</para> 11.716 <itemizedlist> 11.717 - <listitem><para>You might have forgotten to use 11.718 + <listitem><para id="x_4a8">You might have forgotten to use 11.719 <command>ssh-add</command> or <command>pageant</command> 11.720 to store the passphrase.</para> 11.721 </listitem> 11.722 - <listitem><para>You might have stored the passphrase for the 11.723 + <listitem><para id="x_4a9">You might have stored the passphrase for the 11.724 wrong key.</para> 11.725 </listitem></itemizedlist> 11.726 - <para>If you're being prompted for the remote user's password, 11.727 + <para id="x_4aa">If you're being prompted for the remote user's password, 11.728 there are another few possible problems to check.</para> 11.729 <itemizedlist> 11.730 - <listitem><para>Either the user's home directory or their 11.731 + <listitem><para id="x_4ab">Either the user's home directory or their 11.732 <filename role="special" class="directory">.ssh</filename> 11.733 directory might have excessively liberal permissions. As 11.734 a result, the ssh daemon will not trust or read their 11.735 @@ -752,19 +752,19 @@ 11.736 role="special" class="directory">.ssh</filename> 11.737 directory will often cause this symptom.</para> 11.738 </listitem> 11.739 - <listitem><para>The user's <filename 11.740 + <listitem><para id="x_4ac">The user's <filename 11.741 role="special">authorized_keys</filename> file may have 11.742 a problem. If anyone other than the user owns or can write 11.743 to that file, the ssh daemon will not trust or read 11.744 it.</para> 11.745 </listitem></itemizedlist> 11.746 11.747 - <para>In the ideal world, you should be able to run the 11.748 + <para id="x_4ad">In the ideal world, you should be able to run the 11.749 following command successfully, and it should print exactly 11.750 one line of output, the current date and time.</para> 11.751 <programlisting>ssh myserver date</programlisting> 11.752 11.753 - <para>If, on your server, you have login scripts that print 11.754 + <para id="x_4ae">If, on your server, you have login scripts that print 11.755 banners or other junk even when running non-interactive 11.756 commands like this, you should fix them before you continue, 11.757 so that they only print output if they're run interactively. 11.758 @@ -778,43 +778,43 @@ 11.759 shell is to check the return code from the command 11.760 <literal>tty -s</literal>.)</para> 11.761 11.762 - <para>Once you've verified that plain old ssh is working with 11.763 + <para id="x_4af">Once you've verified that plain old ssh is working with 11.764 your server, the next step is to ensure that Mercurial runs on 11.765 the server. The following command should run 11.766 successfully:</para> 11.767 11.768 <programlisting>ssh myserver hg version</programlisting> 11.769 11.770 - <para>If you see an error message instead of normal <command 11.771 + <para id="x_4b0">If you see an error message instead of normal <command 11.772 role="hg-cmd">hg version</command> output, this is usually 11.773 because you haven't installed Mercurial to <filename 11.774 class="directory">/usr/bin</filename>. Don't worry if this 11.775 is the case; you don't need to do that. But you should check 11.776 for a few possible problems.</para> 11.777 <itemizedlist> 11.778 - <listitem><para>Is Mercurial really installed on the server at 11.779 + <listitem><para id="x_4b1">Is Mercurial really installed on the server at 11.780 all? I know this sounds trivial, but it's worth 11.781 checking!</para> 11.782 </listitem> 11.783 - <listitem><para>Maybe your shell's search path (usually set 11.784 + <listitem><para id="x_4b2">Maybe your shell's search path (usually set 11.785 via the <envar>PATH</envar> environment variable) is 11.786 simply misconfigured.</para> 11.787 </listitem> 11.788 - <listitem><para>Perhaps your <envar>PATH</envar> environment 11.789 + <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 11.790 variable is only being set to point to the location of the 11.791 <command>hg</command> executable if the login session is 11.792 interactive. This can happen if you're setting the path 11.793 in the wrong shell login script. See your shell's 11.794 documentation for details.</para> 11.795 </listitem> 11.796 - <listitem><para>The <envar>PYTHONPATH</envar> environment 11.797 + <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 11.798 variable may need to contain the path to the Mercurial 11.799 Python modules. It might not be set at all; it could be 11.800 incorrect; or it may be set only if the login is 11.801 interactive.</para> 11.802 </listitem></itemizedlist> 11.803 11.804 - <para>If you can run <command role="hg-cmd">hg version</command> 11.805 + <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 11.806 over an ssh connection, well done! You've got the server and 11.807 client sorted out. You should now be able to use Mercurial to 11.808 access repositories hosted by that username on that server. 11.809 @@ -826,19 +826,19 @@ 11.810 <sect2> 11.811 <title>Using compression with ssh</title> 11.812 11.813 - <para>Mercurial does not compress data when it uses the ssh 11.814 + <para id="x_4b6">Mercurial does not compress data when it uses the ssh 11.815 protocol, because the ssh protocol can transparently compress 11.816 data. However, the default behaviour of ssh clients is 11.817 <emphasis>not</emphasis> to request compression.</para> 11.818 11.819 - <para>Over any network other than a fast LAN (even a wireless 11.820 + <para id="x_4b7">Over any network other than a fast LAN (even a wireless 11.821 network), using compression is likely to significantly speed 11.822 up Mercurial's network operations. For example, over a WAN, 11.823 someone measured compression as reducing the amount of time 11.824 required to clone a particularly large repository from 51 11.825 minutes to 17 minutes.</para> 11.826 11.827 - <para>Both <command>ssh</command> and <command>plink</command> 11.828 + <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 11.829 accept a <option role="cmd-opt-ssh">-C</option> option which 11.830 turns on compression. You can easily edit your <filename 11.831 role="special">~/.hgrc</filename> to enable compression for 11.832 @@ -846,7 +846,7 @@ 11.833 <programlisting>[ui] 11.834 ssh = ssh -C</programlisting> 11.835 11.836 - <para>If you use <command>ssh</command>, you can configure it to 11.837 + <para id="x_4b9">If you use <command>ssh</command>, you can configure it to 11.838 always use compression when talking to your server. To do 11.839 this, edit your <filename 11.840 role="special">.ssh/config</filename> file (which may not 11.841 @@ -854,7 +854,7 @@ 11.842 <programlisting>Host hg 11.843 Compression yes 11.844 HostName hg.example.com</programlisting> 11.845 - <para>This defines an alias, <literal>hg</literal>. When you 11.846 + <para id="x_4ba">This defines an alias, <literal>hg</literal>. When you 11.847 use it on the <command>ssh</command> command line or in a 11.848 Mercurial <literal>ssh</literal>-protocol URL, it will cause 11.849 <command>ssh</command> to connect to 11.850 @@ -867,17 +867,17 @@ 11.851 <sect1 id="sec:collab:cgi"> 11.852 <title>Serving over HTTP using CGI</title> 11.853 11.854 - <para>Depending on how ambitious you are, configuring Mercurial's 11.855 + <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 11.856 CGI interface can take anything from a few moments to several 11.857 hours.</para> 11.858 11.859 - <para>We'll begin with the simplest of examples, and work our way 11.860 + <para id="x_4bc">We'll begin with the simplest of examples, and work our way 11.861 towards a more complex configuration. Even for the most basic 11.862 case, you're almost certainly going to need to read and modify 11.863 your web server's configuration.</para> 11.864 11.865 <note> 11.866 - <para> Configuring a web server is a complex, fiddly, and 11.867 + <para id="x_4bd"> Configuring a web server is a complex, fiddly, and 11.868 highly system-dependent activity. I can't possibly give you 11.869 instructions that will cover anything like all of the cases 11.870 you will encounter. Please use your discretion and judgment in 11.871 @@ -889,25 +889,25 @@ 11.872 <sect2> 11.873 <title>Web server configuration checklist</title> 11.874 11.875 - <para>Before you continue, do take a few moments to check a few 11.876 + <para id="x_4be">Before you continue, do take a few moments to check a few 11.877 aspects of your system's setup.</para> 11.878 11.879 <orderedlist> 11.880 - <listitem><para>Do you have a web server installed at all? 11.881 + <listitem><para id="x_4bf">Do you have a web server installed at all? 11.882 Mac OS X ships with Apache, but many other systems may not 11.883 have a web server installed.</para> 11.884 </listitem> 11.885 - <listitem><para>If you have a web server installed, is it 11.886 + <listitem><para id="x_4c0">If you have a web server installed, is it 11.887 actually running? On most systems, even if one is 11.888 present, it will be disabled by default.</para> 11.889 </listitem> 11.890 - <listitem><para>Is your server configured to allow you to run 11.891 + <listitem><para id="x_4c1">Is your server configured to allow you to run 11.892 CGI programs in the directory where you plan to do so? 11.893 Most servers default to explicitly disabling the ability 11.894 to run CGI programs.</para> 11.895 </listitem></orderedlist> 11.896 11.897 - <para>If you don't have a web server installed, and don't have 11.898 + <para id="x_4c2">If you don't have a web server installed, and don't have 11.899 substantial experience configuring Apache, you should consider 11.900 using the <literal>lighttpd</literal> web server instead of 11.901 Apache. Apache has a well-deserved reputation for baroque and 11.902 @@ -922,7 +922,7 @@ 11.903 <sect2> 11.904 <title>Basic CGI configuration</title> 11.905 11.906 - <para>On Unix-like systems, it's common for users to have a 11.907 + <para id="x_4c3">On Unix-like systems, it's common for users to have a 11.908 subdirectory named something like <filename 11.909 class="directory">public_html</filename> in their home 11.910 directory, from which they can serve up web pages. A file 11.911 @@ -930,19 +930,19 @@ 11.912 accessible at a URL of the form 11.913 <literal>http://www.example.com/username/foo</literal>.</para> 11.914 11.915 - <para>To get started, find the <filename 11.916 + <para id="x_4c4">To get started, find the <filename 11.917 role="special">hgweb.cgi</filename> script that should be 11.918 present in your Mercurial installation. If you can't quickly 11.919 find a local copy on your system, simply download one from the 11.920 master Mercurial repository at <ulink 11.921 url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.</para> 11.922 11.923 - <para>You'll need to copy this script into your <filename 11.924 + <para id="x_4c5">You'll need to copy this script into your <filename 11.925 class="directory">public_html</filename> directory, and 11.926 ensure that it's executable.</para> 11.927 <programlisting>cp .../hgweb.cgi ~/public_html 11.928 chmod 755 ~/public_html/hgweb.cgi</programlisting> 11.929 - <para>The <literal>755</literal> argument to 11.930 + <para id="x_4c6">The <literal>755</literal> argument to 11.931 <command>chmod</command> is a little more general than just 11.932 making the script executable: it ensures that the script is 11.933 executable by anyone, and that <quote>group</quote> and 11.934 @@ -959,7 +959,7 @@ 11.935 <title>What could <emphasis>possibly</emphasis> go 11.936 wrong?</title> 11.937 11.938 - <para>Once you've copied the CGI script into place, go into a 11.939 + <para id="x_4c7">Once you've copied the CGI script into place, go into a 11.940 web browser, and try to open the URL <ulink 11.941 url="http://myhostname/ 11.942 myuser/hgweb.cgi">http://myhostname/ 11.943 @@ -973,7 +973,7 @@ 11.944 fresh installation of Apache, and a user account that I 11.945 created specially to perform this exercise.</para> 11.946 11.947 - <para>Your web server may have per-user directories disabled. 11.948 + <para id="x_4c8">Your web server may have per-user directories disabled. 11.949 If you're using Apache, search your config file for a 11.950 <literal>UserDir</literal> directive. If there's none 11.951 present, per-user directories will be disabled. If one 11.952 @@ -984,7 +984,7 @@ 11.953 directory, for example <filename 11.954 class="directory">public_html</filename>.</para> 11.955 11.956 - <para>Your file access permissions may be too restrictive. 11.957 + <para id="x_4c9">Your file access permissions may be too restrictive. 11.958 The web server must be able to traverse your home directory 11.959 and directories under your <filename 11.960 class="directory">public_html</filename> directory, and 11.961 @@ -994,34 +994,34 @@ 11.962 find ~/public_html -type d -print0 | xargs -0r chmod 755 11.963 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 11.964 11.965 - <para>The other possibility with permissions is that you might 11.966 + <para id="x_4ca">The other possibility with permissions is that you might 11.967 get a completely empty window when you try to load the 11.968 script. In this case, it's likely that your access 11.969 permissions are <emphasis>too permissive</emphasis>. Apache's 11.970 <literal>suexec</literal> subsystem won't execute a script 11.971 that's group- or world-writable, for example.</para> 11.972 11.973 - <para>Your web server may be configured to disallow execution 11.974 + <para id="x_4cb">Your web server may be configured to disallow execution 11.975 of CGI programs in your per-user web directory. Here's 11.976 Apache's default per-user configuration from my Fedora 11.977 system.</para> 11.978 11.979 &ch06-apache-config.lst; 11.980 11.981 - <para>If you find a similar-looking 11.982 + <para id="x_4cc">If you find a similar-looking 11.983 <literal>Directory</literal> group in your Apache 11.984 configuration, the directive to look at inside it is 11.985 <literal>Options</literal>. Add <literal>ExecCGI</literal> 11.986 to the end of this list if it's missing, and restart the web 11.987 server.</para> 11.988 11.989 - <para>If you find that Apache serves you the text of the CGI 11.990 + <para id="x_4cd">If you find that Apache serves you the text of the CGI 11.991 script instead of executing it, you may need to either 11.992 uncomment (if already present) or add a directive like 11.993 this.</para> 11.994 <programlisting>AddHandler cgi-script .cgi</programlisting> 11.995 11.996 - <para>The next possibility is that you might be served with a 11.997 + <para id="x_4ce">The next possibility is that you might be served with a 11.998 colourful Python backtrace claiming that it can't import a 11.999 <literal>mercurial</literal>-related module. This is 11.1000 actually progress! The server is now capable of executing 11.1001 @@ -1035,7 +1035,7 @@ 11.1002 directions inside it to correctly set your 11.1003 <envar>PYTHONPATH</envar> environment variable.</para> 11.1004 11.1005 - <para>Finally, you are <emphasis>certain</emphasis> to by 11.1006 + <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to by 11.1007 served with another colourful Python backtrace: this one 11.1008 will complain that it can't find <filename 11.1009 class="directory">/path/to/repository</filename>. Edit 11.1010 @@ -1045,7 +1045,7 @@ 11.1011 with the complete path to the repository you want to serve 11.1012 up.</para> 11.1013 11.1014 - <para>At this point, when you try to reload the page, you 11.1015 + <para id="x_4d0">At this point, when you try to reload the page, you 11.1016 should be presented with a nice HTML view of your 11.1017 repository's history. Whew!</para> 11.1018 11.1019 @@ -1053,7 +1053,7 @@ 11.1020 <sect3> 11.1021 <title>Configuring lighttpd</title> 11.1022 11.1023 - <para>To be exhaustive in my experiments, I tried configuring 11.1024 + <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 11.1025 the increasingly popular <literal>lighttpd</literal> web 11.1026 server to serve the same repository as I described with 11.1027 Apache above. I had already overcome all of the problems I 11.1028 @@ -1063,7 +1063,7 @@ 11.1029 role="special">hgweb.cgi</filename> script was properly 11.1030 edited.</para> 11.1031 11.1032 - <para>Once I had Apache running, getting 11.1033 + <para id="x_4d2">Once I had Apache running, getting 11.1034 <literal>lighttpd</literal> to serve the repository was a 11.1035 snap (in other words, even if you're trying to use 11.1036 <literal>lighttpd</literal>, you should read the Apache 11.1037 @@ -1075,7 +1075,7 @@ 11.1038 end of the config file, to configure these modules.</para> 11.1039 <programlisting>userdir.path = "public_html" 11.1040 cgi.assign = (".cgi" => "" )</programlisting> 11.1041 - <para>With this done, <literal>lighttpd</literal> ran 11.1042 + <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 11.1043 immediately for me. If I had configured 11.1044 <literal>lighttpd</literal> before Apache, I'd almost 11.1045 certainly have run into many of the same system-level 11.1046 @@ -1090,7 +1090,7 @@ 11.1047 <sect2> 11.1048 <title>Sharing multiple repositories with one CGI script</title> 11.1049 11.1050 - <para>The <filename role="special">hgweb.cgi</filename> script 11.1051 + <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 11.1052 only lets you publish a single repository, which is an 11.1053 annoying restriction. If you want to publish more than one 11.1054 without wracking yourself with multiple copies of the same 11.1055 @@ -1098,7 +1098,7 @@ 11.1056 the <filename role="special">hgwebdir.cgi</filename> 11.1057 script.</para> 11.1058 11.1059 - <para>The procedure to configure <filename 11.1060 + <para id="x_4d5">The procedure to configure <filename 11.1061 role="special">hgwebdir.cgi</filename> is only a little more 11.1062 involved than for <filename 11.1063 role="special">hgweb.cgi</filename>. First, you must obtain 11.1064 @@ -1106,12 +1106,12 @@ 11.1065 download a copy from the master Mercurial repository at <ulink 11.1066 url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para> 11.1067 11.1068 - <para>You'll need to copy this script into your <filename 11.1069 + <para id="x_4d6">You'll need to copy this script into your <filename 11.1070 class="directory">public_html</filename> directory, and 11.1071 ensure that it's executable.</para> 11.1072 <programlisting>cp .../hgwebdir.cgi ~/public_html 11.1073 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 11.1074 - <para>With basic configuration out of the way, try to visit 11.1075 + <para id="x_4d7">With basic configuration out of the way, try to visit 11.1076 <ulink url="http://myhostname/ 11.1077 myuser/hgwebdir.cgi">http://myhostname/ 11.1078 myuser/hgwebdir.cgi</ulink> in your browser. It should 11.1079 @@ -1120,7 +1120,7 @@ 11.1080 potential problems in section <xref 11.1081 linkend="sec:collab:wtf"/>.</para> 11.1082 11.1083 - <para>The <filename role="special">hgwebdir.cgi</filename> 11.1084 + <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 11.1085 script relies on an external configuration file. By default, 11.1086 it searches for a file named <filename 11.1087 role="special">hgweb.config</filename> in the same directory 11.1088 @@ -1130,7 +1130,7 @@ 11.1089 <literal>ConfigParser</literal> 11.1090 <citation>web:configparser</citation> module.</para> 11.1091 11.1092 - <para>The easiest way to configure <filename 11.1093 + <para id="x_4d9">The easiest way to configure <filename 11.1094 role="special">hgwebdir.cgi</filename> is with a section 11.1095 named <literal>collections</literal>. This will automatically 11.1096 publish <emphasis>every</emphasis> repository under the 11.1097 @@ -1138,7 +1138,7 @@ 11.1098 this:</para> 11.1099 <programlisting>[collections] 11.1100 /my/root = /my/root</programlisting> 11.1101 - <para>Mercurial interprets this by looking at the directory name 11.1102 + <para id="x_4da">Mercurial interprets this by looking at the directory name 11.1103 on the <emphasis>right</emphasis> hand side of the 11.1104 <quote><literal>=</literal></quote> sign; finding repositories 11.1105 in that directory hierarchy; and using the text on the 11.1106 @@ -1147,7 +1147,7 @@ 11.1107 remaining component of a path after this stripping has 11.1108 occurred is called a <quote>virtual path</quote>.</para> 11.1109 11.1110 - <para>Given the example above, if we have a repository whose 11.1111 + <para id="x_4db">Given the example above, if we have a repository whose 11.1112 local path is <filename 11.1113 class="directory">/my/root/this/repo</filename>, the CGI 11.1114 script will strip the leading <filename 11.1115 @@ -1161,7 +1161,7 @@ 11.1116 myuser/hgwebdir.cgi/this/repo">http://myhostname/ 11.1117 myuser/hgwebdir.cgi/this/repo</ulink>.</para> 11.1118 11.1119 - <para>If we replace <filename 11.1120 + <para id="x_4dc">If we replace <filename 11.1121 class="directory">/my/root</filename> on the left hand side 11.1122 of this example with <filename 11.1123 class="directory">/my</filename>, then <filename 11.1124 @@ -1171,13 +1171,13 @@ 11.1125 class="directory">root/this/repo</filename> instead of 11.1126 <filename class="directory">this/repo</filename>.</para> 11.1127 11.1128 - <para>The <filename role="special">hgwebdir.cgi</filename> 11.1129 + <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 11.1130 script will recursively search each directory listed in the 11.1131 <literal>collections</literal> section of its configuration 11.1132 file, but it will <literal>not</literal> recurse into the 11.1133 repositories it finds.</para> 11.1134 11.1135 - <para>The <literal>collections</literal> mechanism makes it easy 11.1136 + <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 11.1137 to publish many repositories in a <quote>fire and 11.1138 forget</quote> manner. You only need to set up the CGI 11.1139 script and configuration file one time. Afterwards, you can 11.1140 @@ -1190,7 +1190,7 @@ 11.1141 <title>Explicitly specifying which repositories to 11.1142 publish</title> 11.1143 11.1144 - <para>In addition to the <literal>collections</literal> 11.1145 + <para id="x_4df">In addition to the <literal>collections</literal> 11.1146 mechanism, the <filename 11.1147 role="special">hgwebdir.cgi</filename> script allows you 11.1148 to publish a specific list of repositories. To do so, 11.1149 @@ -1199,20 +1199,20 @@ 11.1150 <programlisting>[paths] 11.1151 repo1 = /my/path/to/some/repo 11.1152 repo2 = /some/path/to/another</programlisting> 11.1153 - <para>In this case, the virtual path (the component that will 11.1154 + <para id="x_4e0">In this case, the virtual path (the component that will 11.1155 appear in a URL) is on the left hand side of each 11.1156 definition, while the path to the repository is on the 11.1157 right. Notice that there does not need to be any 11.1158 relationship between the virtual path you choose and the 11.1159 location of a repository in your filesystem.</para> 11.1160 11.1161 - <para>If you wish, you can use both the 11.1162 + <para id="x_4e1">If you wish, you can use both the 11.1163 <literal>collections</literal> and <literal>paths</literal> 11.1164 mechanisms simultaneously in a single configuration 11.1165 file.</para> 11.1166 11.1167 <note> 11.1168 - <para> If multiple repositories have the same virtual path, 11.1169 + <para id="x_4e2"> If multiple repositories have the same virtual path, 11.1170 <filename role="special">hgwebdir.cgi</filename> will not 11.1171 report an error. Instead, it will behave 11.1172 unpredictably.</para> 11.1173 @@ -1223,12 +1223,12 @@ 11.1174 <sect2> 11.1175 <title>Downloading source archives</title> 11.1176 11.1177 - <para>Mercurial's web interface lets users download an archive 11.1178 + <para id="x_4e3">Mercurial's web interface lets users download an archive 11.1179 of any revision. This archive will contain a snapshot of the 11.1180 working directory as of that revision, but it will not contain 11.1181 a copy of the repository data.</para> 11.1182 11.1183 - <para>By default, this feature is not enabled. To enable it, 11.1184 + <para id="x_4e4">By default, this feature is not enabled. To enable it, 11.1185 you'll need to add an <envar 11.1186 role="rc-item-web">allow_archive</envar> item to the 11.1187 <literal role="rc-web">web</literal> section of your <filename 11.1188 @@ -1238,7 +1238,7 @@ 11.1189 <sect2> 11.1190 <title>Web configuration options</title> 11.1191 11.1192 - <para>Mercurial's web interfaces (the <command role="hg-cmd">hg 11.1193 + <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 11.1194 serve</command> command, and the <filename 11.1195 role="special">hgweb.cgi</filename> and <filename 11.1196 role="special">hgwebdir.cgi</filename> scripts) have a 11.1197 @@ -1246,7 +1246,7 @@ 11.1198 belong in a section named <literal 11.1199 role="rc-web">web</literal>.</para> 11.1200 <itemizedlist> 11.1201 - <listitem><para><envar 11.1202 + <listitem><para id="x_4e6"><envar 11.1203 role="rc-item-web">allow_archive</envar>: Determines 11.1204 which (if any) archive download mechanisms Mercurial 11.1205 supports. If you enable this feature, users of the web 11.1206 @@ -1255,30 +1255,30 @@ 11.1207 archive feature, this item must take the form of a 11.1208 sequence of words drawn from the list below.</para> 11.1209 <itemizedlist> 11.1210 - <listitem><para><literal>bz2</literal>: A 11.1211 + <listitem><para id="x_4e7"><literal>bz2</literal>: A 11.1212 <command>tar</command> archive, compressed using 11.1213 <literal>bzip2</literal> compression. This has the 11.1214 best compression ratio, but uses the most CPU time on 11.1215 the server.</para> 11.1216 </listitem> 11.1217 - <listitem><para><literal>gz</literal>: A 11.1218 + <listitem><para id="x_4e8"><literal>gz</literal>: A 11.1219 <command>tar</command> archive, compressed using 11.1220 <literal>gzip</literal> compression.</para> 11.1221 </listitem> 11.1222 - <listitem><para><literal>zip</literal>: A 11.1223 + <listitem><para id="x_4e9"><literal>zip</literal>: A 11.1224 <command>zip</command> archive, compressed using LZW 11.1225 compression. This format has the worst compression 11.1226 ratio, but is widely used in the Windows world.</para> 11.1227 </listitem> 11.1228 </itemizedlist> 11.1229 - <para> If you provide an empty list, or don't have an 11.1230 + <para id="x_4ea"> If you provide an empty list, or don't have an 11.1231 <envar role="rc-item-web">allow_archive</envar> entry at 11.1232 all, this feature will be disabled. Here is an example of 11.1233 how to enable all three supported formats.</para> 11.1234 <programlisting>[web] 11.1235 allow_archive = bz2 gz zip</programlisting> 11.1236 </listitem> 11.1237 - <listitem><para><envar role="rc-item-web">allowpull</envar>: 11.1238 + <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 11.1239 Boolean. Determines whether the web interface allows 11.1240 remote users to <command role="hg-cmd">hg pull</command> 11.1241 and <command role="hg-cmd">hg clone</command> this 11.1242 @@ -1287,7 +1287,7 @@ 11.1243 <quote>human-oriented</quote> portion of the web interface 11.1244 is available.</para> 11.1245 </listitem> 11.1246 - <listitem><para><envar role="rc-item-web">contact</envar>: 11.1247 + <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 11.1248 String. A free-form (but preferably brief) string 11.1249 identifying the person or group in charge of the 11.1250 repository. This often contains the name and email 11.1251 @@ -1298,21 +1298,21 @@ 11.1252 role="special">~/.hgrc</filename> if every repository 11.1253 has a single maintainer.</para> 11.1254 </listitem> 11.1255 - <listitem><para><envar role="rc-item-web">maxchanges</envar>: 11.1256 + <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 11.1257 Integer. The default maximum number of changesets to 11.1258 display in a single page of output.</para> 11.1259 </listitem> 11.1260 - <listitem><para><envar role="rc-item-web">maxfiles</envar>: 11.1261 + <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 11.1262 Integer. The default maximum number of modified files to 11.1263 display in a single page of output.</para> 11.1264 </listitem> 11.1265 - <listitem><para><envar role="rc-item-web">stripes</envar>: 11.1266 + <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 11.1267 Integer. If the web interface displays alternating 11.1268 <quote>stripes</quote> to make it easier to visually align 11.1269 rows when you are looking at a table, this number controls 11.1270 the number of rows in each stripe.</para> 11.1271 </listitem> 11.1272 - <listitem><para><envar role="rc-item-web">style</envar>: 11.1273 + <listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>: 11.1274 Controls the template Mercurial uses to display the web 11.1275 interface. Mercurial ships with two web templates, named 11.1276 <literal>default</literal> and <literal>gitweb</literal> 11.1277 @@ -1324,12 +1324,12 @@ 11.1278 <programlisting>[web] 11.1279 style = gitweb</programlisting> 11.1280 </listitem> 11.1281 - <listitem><para><envar role="rc-item-web">templates</envar>: 11.1282 + <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 11.1283 Path. The directory in which to search for template 11.1284 files. By default, Mercurial searches in the directory in 11.1285 which it was installed.</para> 11.1286 </listitem></itemizedlist> 11.1287 - <para>If you are using <filename 11.1288 + <para id="x_4f2">If you are using <filename 11.1289 role="special">hgwebdir.cgi</filename>, you can place a few 11.1290 configuration items in a <literal role="rc-web">web</literal> 11.1291 section of the <filename 11.1292 @@ -1342,17 +1342,17 @@ 11.1293 <sect3> 11.1294 <title>Options specific to an individual repository</title> 11.1295 11.1296 - <para>A few <literal role="rc-web">web</literal> configuration 11.1297 + <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 11.1298 items ought to be placed in a repository's local <filename 11.1299 role="special">.hg/hgrc</filename>, rather than a user's 11.1300 or global <filename role="special">~/.hgrc</filename>.</para> 11.1301 <itemizedlist> 11.1302 - <listitem><para><envar 11.1303 + <listitem><para id="x_4f4"><envar 11.1304 role="rc-item-web">description</envar>: String. A 11.1305 free-form (but preferably brief) string that describes 11.1306 the contents or purpose of the repository.</para> 11.1307 </listitem> 11.1308 - <listitem><para><envar role="rc-item-web">name</envar>: 11.1309 + <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 11.1310 String. The name to use for the repository in the web 11.1311 interface. This overrides the default name, which is 11.1312 the last component of the repository's path.</para> 11.1313 @@ -1363,13 +1363,13 @@ 11.1314 <title>Options specific to the <command role="hg-cmd">hg 11.1315 serve</command> command</title> 11.1316 11.1317 - <para>Some of the items in the <literal 11.1318 + <para id="x_4f6">Some of the items in the <literal 11.1319 role="rc-web">web</literal> section of a <filename 11.1320 role="special">~/.hgrc</filename> file are only for use 11.1321 with the <command role="hg-cmd">hg serve</command> 11.1322 command.</para> 11.1323 <itemizedlist> 11.1324 - <listitem><para><envar role="rc-item-web">accesslog</envar>: 11.1325 + <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 11.1326 Path. The name of a file into which to write an access 11.1327 log. By default, the <command role="hg-cmd">hg 11.1328 serve</command> command writes this information to 11.1329 @@ -1377,22 +1377,22 @@ 11.1330 in the standard <quote>combined</quote> file format used 11.1331 by almost all web servers.</para> 11.1332 </listitem> 11.1333 - <listitem><para><envar role="rc-item-web">address</envar>: 11.1334 + <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 11.1335 String. The local address on which the server should 11.1336 listen for incoming connections. By default, the server 11.1337 listens on all addresses.</para> 11.1338 </listitem> 11.1339 - <listitem><para><envar role="rc-item-web">errorlog</envar>: 11.1340 + <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 11.1341 Path. The name of a file into which to write an error 11.1342 log. By default, the <command role="hg-cmd">hg 11.1343 serve</command> command writes this information to 11.1344 standard error, not to a file.</para> 11.1345 </listitem> 11.1346 - <listitem><para><envar role="rc-item-web">ipv6</envar>: 11.1347 + <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 11.1348 Boolean. Whether to use the IPv6 protocol. By default, 11.1349 IPv6 is not used.</para> 11.1350 </listitem> 11.1351 - <listitem><para><envar role="rc-item-web">port</envar>: 11.1352 + <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 11.1353 Integer. The TCP port number on which the server should 11.1354 listen. The default port number used is 8000.</para> 11.1355 </listitem></itemizedlist> 11.1356 @@ -1403,14 +1403,14 @@ 11.1357 role="special">~/.hgrc</filename> file to add <literal 11.1358 role="rc-web">web</literal> items to</title> 11.1359 11.1360 - <para>It is important to remember that a web server like 11.1361 + <para id="x_4fc">It is important to remember that a web server like 11.1362 Apache or <literal>lighttpd</literal> will run under a user 11.1363 ID that is different to yours. CGI scripts run by your 11.1364 server, such as <filename 11.1365 role="special">hgweb.cgi</filename>, will usually also run 11.1366 under that user ID.</para> 11.1367 11.1368 - <para>If you add <literal role="rc-web">web</literal> items to 11.1369 + <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 11.1370 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 11.1371 <filename role="special">~/.hgrc</filename> file. Those 11.1372 settings will thus only affect the behaviour of the <command
12.1 --- a/en/ch06-filenames.xml Thu Mar 19 20:54:12 2009 -0700 12.2 +++ b/en/ch06-filenames.xml Thu Mar 19 21:18:52 2009 -0700 12.3 @@ -4,22 +4,22 @@ 12.4 <?dbhtml filename="file-names-and-pattern-matching.html"?> 12.5 <title>File names and pattern matching</title> 12.6 12.7 - <para>Mercurial provides mechanisms that let you work with file 12.8 + <para id="x_543">Mercurial provides mechanisms that let you work with file 12.9 names in a consistent and expressive way.</para> 12.10 12.11 <sect1> 12.12 <title>Simple file naming</title> 12.13 12.14 - <para>Mercurial uses a unified piece of machinery <quote>under the 12.15 + <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the 12.16 hood</quote> to handle file names. Every command behaves 12.17 uniformly with respect to file names. The way in which commands 12.18 work with file names is as follows.</para> 12.19 12.20 - <para>If you explicitly name real files on the command line, 12.21 + <para id="x_545">If you explicitly name real files on the command line, 12.22 Mercurial works with exactly those files, as you would expect. 12.23 &interaction.filenames.files;</para> 12.24 12.25 - <para>When you provide a directory name, Mercurial will interpret 12.26 + <para id="x_546">When you provide a directory name, Mercurial will interpret 12.27 this as <quote>operate on every file in this directory and its 12.28 subdirectories</quote>. Mercurial traverses the files and 12.29 subdirectories in a directory in alphabetical order. When it 12.30 @@ -32,18 +32,18 @@ 12.31 <sect1> 12.32 <title>Running commands without any file names</title> 12.33 12.34 - <para>Mercurial's commands that work with file names have useful 12.35 + <para id="x_547">Mercurial's commands that work with file names have useful 12.36 default behaviours when you invoke them without providing any 12.37 file names or patterns. What kind of behaviour you should 12.38 expect depends on what the command does. Here are a few rules 12.39 of thumb you can use to predict what a command is likely to do 12.40 if you don't give it any names to work with.</para> 12.41 <itemizedlist> 12.42 - <listitem><para>Most commands will operate on the entire working 12.43 + <listitem><para id="x_548">Most commands will operate on the entire working 12.44 directory. This is what the <command role="hg-cmd">hg 12.45 add</command> command does, for example.</para> 12.46 </listitem> 12.47 - <listitem><para>If the command has effects that are difficult or 12.48 + <listitem><para id="x_549">If the command has effects that are difficult or 12.49 impossible to reverse, it will force you to explicitly 12.50 provide at least one name or pattern (see below). This 12.51 protects you from accidentally deleting files by running 12.52 @@ -51,7 +51,7 @@ 12.53 arguments, for example.</para> 12.54 </listitem></itemizedlist> 12.55 12.56 - <para>It's easy to work around these default behaviours if they 12.57 + <para id="x_54a">It's easy to work around these default behaviours if they 12.58 don't suit you. If a command normally operates on the whole 12.59 working directory, you can invoke it on just the current 12.60 directory and its subdirectories by giving it the name 12.61 @@ -59,7 +59,7 @@ 12.62 12.63 &interaction.filenames.wdir-subdir; 12.64 12.65 - <para>Along the same lines, some commands normally print file 12.66 + <para id="x_54b">Along the same lines, some commands normally print file 12.67 names relative to the root of the repository, even if you're 12.68 invoking them from a subdirectory. Such a command will print 12.69 file names relative to your subdirectory if you give it explicit 12.70 @@ -75,21 +75,21 @@ 12.71 <sect1> 12.72 <title>Telling you what's going on</title> 12.73 12.74 - <para>The <command role="hg-cmd">hg add</command> example in the 12.75 + <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the 12.76 preceding section illustrates something else that's helpful 12.77 about Mercurial commands. If a command operates on a file that 12.78 you didn't name explicitly on the command line, it will usually 12.79 print the name of the file, so that you will not be surprised 12.80 what's going on.</para> 12.81 12.82 - <para>The principle here is of <emphasis>least 12.83 + <para id="x_54d">The principle here is of <emphasis>least 12.84 surprise</emphasis>. If you've exactly named a file on the 12.85 command line, there's no point in repeating it back at you. If 12.86 Mercurial is acting on a file <emphasis>implicitly</emphasis>, 12.87 because you provided no names, or a directory, or a pattern (see 12.88 below), it's safest to tell you what it's doing.</para> 12.89 12.90 - <para>For commands that behave this way, you can silence them 12.91 + <para id="x_54e">For commands that behave this way, you can silence them 12.92 using the <option role="hg-opt-global">-q</option> option. You 12.93 can also get them to print the name of every file, even those 12.94 you've named explicitly, using the <option 12.95 @@ -99,39 +99,39 @@ 12.96 <sect1> 12.97 <title>Using patterns to identify files</title> 12.98 12.99 - <para>In addition to working with file and directory names, 12.100 + <para id="x_54f">In addition to working with file and directory names, 12.101 Mercurial lets you use <emphasis>patterns</emphasis> to identify 12.102 files. Mercurial's pattern handling is expressive.</para> 12.103 12.104 - <para>On Unix-like systems (Linux, MacOS, etc.), the job of 12.105 + <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of 12.106 matching file names to patterns normally falls to the shell. On 12.107 these systems, you must explicitly tell Mercurial that a name is 12.108 a pattern. On Windows, the shell does not expand patterns, so 12.109 Mercurial will automatically identify names that are patterns, 12.110 and expand them for you.</para> 12.111 12.112 - <para>To provide a pattern in place of a regular name on the 12.113 + <para id="x_551">To provide a pattern in place of a regular name on the 12.114 command line, the mechanism is simple:</para> 12.115 <programlisting>syntax:patternbody</programlisting> 12.116 - <para>That is, a pattern is identified by a short text string that 12.117 + <para id="x_552">That is, a pattern is identified by a short text string that 12.118 says what kind of pattern this is, followed by a colon, followed 12.119 by the actual pattern.</para> 12.120 12.121 - <para>Mercurial supports two kinds of pattern syntax. The most 12.122 + <para id="x_553">Mercurial supports two kinds of pattern syntax. The most 12.123 frequently used is called <literal>glob</literal>; this is the 12.124 same kind of pattern matching used by the Unix shell, and should 12.125 be familiar to Windows command prompt users, too.</para> 12.126 12.127 - <para>When Mercurial does automatic pattern matching on Windows, 12.128 + <para id="x_554">When Mercurial does automatic pattern matching on Windows, 12.129 it uses <literal>glob</literal> syntax. You can thus omit the 12.130 <quote><literal>glob:</literal></quote> prefix on Windows, but 12.131 it's safe to use it, too.</para> 12.132 12.133 - <para>The <literal>re</literal> syntax is more powerful; it lets 12.134 + <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets 12.135 you specify patterns using regular expressions, also known as 12.136 regexps.</para> 12.137 12.138 - <para>By the way, in the examples that follow, notice that I'm 12.139 + <para id="x_556">By the way, in the examples that follow, notice that I'm 12.140 careful to wrap all of my patterns in quote characters, so that 12.141 they won't get expanded by the shell before Mercurial sees 12.142 them.</para> 12.143 @@ -139,27 +139,27 @@ 12.144 <sect2> 12.145 <title>Shell-style <literal>glob</literal> patterns</title> 12.146 12.147 - <para>This is an overview of the kinds of patterns you can use 12.148 + <para id="x_557">This is an overview of the kinds of patterns you can use 12.149 when you're matching on glob patterns.</para> 12.150 12.151 - <para>The <quote><literal>*</literal></quote> character matches 12.152 + <para id="x_558">The <quote><literal>*</literal></quote> character matches 12.153 any string, within a single directory.</para> 12.154 12.155 &interaction.filenames.glob.star; 12.156 12.157 - <para>The <quote><literal>**</literal></quote> pattern matches 12.158 + <para id="x_559">The <quote><literal>**</literal></quote> pattern matches 12.159 any string, and crosses directory boundaries. It's not a 12.160 standard Unix glob token, but it's accepted by several popular 12.161 Unix shells, and is very useful.</para> 12.162 12.163 &interaction.filenames.glob.starstar; 12.164 12.165 - <para>The <quote><literal>?</literal></quote> pattern matches 12.166 + <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches 12.167 any single character.</para> 12.168 12.169 &interaction.filenames.glob.question; 12.170 12.171 - <para>The <quote><literal>[</literal></quote> character begins a 12.172 + <para id="x_55b">The <quote><literal>[</literal></quote> character begins a 12.173 <emphasis>character class</emphasis>. This matches any single 12.174 character within the class. The class ends with a 12.175 <quote><literal>]</literal></quote> character. A class may 12.176 @@ -169,13 +169,13 @@ 12.177 12.178 &interaction.filenames.glob.range; 12.179 12.180 - <para>If the first character after the 12.181 + <para id="x_55c">If the first character after the 12.182 <quote><literal>[</literal></quote> in a character class is a 12.183 <quote><literal>!</literal></quote>, it 12.184 <emphasis>negates</emphasis> the class, making it match any 12.185 single character not in the class.</para> 12.186 12.187 - <para>A <quote><literal>{</literal></quote> begins a group of 12.188 + <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of 12.189 subpatterns, where the whole group matches if any subpattern 12.190 in the group matches. The <quote><literal>,</literal></quote> 12.191 character separates subpatterns, and 12.192 @@ -186,7 +186,7 @@ 12.193 <sect3> 12.194 <title>Watch out!</title> 12.195 12.196 - <para>Don't forget that if you want to match a pattern in any 12.197 + <para id="x_55e">Don't forget that if you want to match a pattern in any 12.198 directory, you should not be using the 12.199 <quote><literal>*</literal></quote> match-any token, as this 12.200 will only match within one directory. Instead, use the 12.201 @@ -201,27 +201,27 @@ 12.202 <title>Regular expression matching with <literal>re</literal> 12.203 patterns</title> 12.204 12.205 - <para>Mercurial accepts the same regular expression syntax as 12.206 + <para id="x_55f">Mercurial accepts the same regular expression syntax as 12.207 the Python programming language (it uses Python's regexp 12.208 engine internally). This is based on the Perl language's 12.209 regexp syntax, which is the most popular dialect in use (it's 12.210 also used in Java, for example).</para> 12.211 12.212 - <para>I won't discuss Mercurial's regexp dialect in any detail 12.213 + <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail 12.214 here, as regexps are not often used. Perl-style regexps are 12.215 in any case already exhaustively documented on a multitude of 12.216 web sites, and in many books. Instead, I will focus here on a 12.217 few things you should know if you find yourself needing to use 12.218 regexps with Mercurial.</para> 12.219 12.220 - <para>A regexp is matched against an entire file name, relative 12.221 + <para id="x_561">A regexp is matched against an entire file name, relative 12.222 to the root of the repository. In other words, even if you're 12.223 already in subbdirectory <filename 12.224 class="directory">foo</filename>, if you want to match files 12.225 under this directory, your pattern must start with 12.226 <quote><literal>foo/</literal></quote>.</para> 12.227 12.228 - <para>One thing to note, if you're familiar with Perl-style 12.229 + <para id="x_562">One thing to note, if you're familiar with Perl-style 12.230 regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 12.231 That is, a regexp starts matching against the beginning of a 12.232 string; it doesn't look for a match anywhere within the 12.233 @@ -233,35 +233,35 @@ 12.234 <sect1> 12.235 <title>Filtering files</title> 12.236 12.237 - <para>Not only does Mercurial give you a variety of ways to 12.238 + <para id="x_563">Not only does Mercurial give you a variety of ways to 12.239 specify files; it lets you further winnow those files using 12.240 <emphasis>filters</emphasis>. Commands that work with file 12.241 names accept two filtering options.</para> 12.242 <itemizedlist> 12.243 - <listitem><para><option role="hg-opt-global">-I</option>, or 12.244 + <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or 12.245 <option role="hg-opt-global">--include</option>, lets you 12.246 specify a pattern that file names must match in order to be 12.247 processed.</para> 12.248 </listitem> 12.249 - <listitem><para><option role="hg-opt-global">-X</option>, or 12.250 + <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or 12.251 <option role="hg-opt-global">--exclude</option>, gives you a 12.252 way to <emphasis>avoid</emphasis> processing files, if they 12.253 match this pattern.</para> 12.254 </listitem></itemizedlist> 12.255 - <para>You can provide multiple <option 12.256 + <para id="x_566">You can provide multiple <option 12.257 role="hg-opt-global">-I</option> and <option 12.258 role="hg-opt-global">-X</option> options on the command line, 12.259 and intermix them as you please. Mercurial interprets the 12.260 patterns you provide using glob syntax by default (but you can 12.261 use regexps if you need to).</para> 12.262 12.263 - <para>You can read a <option role="hg-opt-global">-I</option> 12.264 + <para id="x_567">You can read a <option role="hg-opt-global">-I</option> 12.265 filter as <quote>process only the files that match this 12.266 filter</quote>.</para> 12.267 12.268 &interaction.filenames.filter.include; 12.269 12.270 - <para>The <option role="hg-opt-global">-X</option> filter is best 12.271 + <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best 12.272 read as <quote>process only the files that don't match this 12.273 pattern</quote>.</para> 12.274 12.275 @@ -271,13 +271,13 @@ 12.276 <sect1> 12.277 <title>Ignoring unwanted files and directories</title> 12.278 12.279 - <para>XXX.</para> 12.280 + <para id="x_569">XXX.</para> 12.281 12.282 </sect1> 12.283 <sect1 id="sec:names:case"> 12.284 <title>Case sensitivity</title> 12.285 12.286 - <para>If you're working in a mixed development environment that 12.287 + <para id="x_56a">If you're working in a mixed development environment that 12.288 contains both Linux (or other Unix) systems and Macs or Windows 12.289 systems, you should keep in the back of your mind the knowledge 12.290 that they treat the case (<quote>N</quote> versus 12.291 @@ -286,17 +286,17 @@ 12.292 does, but it could surprise you if you don't know about 12.293 it.</para> 12.294 12.295 - <para>Operating systems and filesystems differ in the way they 12.296 + <para id="x_56b">Operating systems and filesystems differ in the way they 12.297 handle the <emphasis>case</emphasis> of characters in file and 12.298 directory names. There are three common ways to handle case in 12.299 names.</para> 12.300 <itemizedlist> 12.301 - <listitem><para>Completely case insensitive. Uppercase and 12.302 + <listitem><para id="x_56c">Completely case insensitive. Uppercase and 12.303 lowercase versions of a letter are treated as identical, 12.304 both when creating a file and during subsequent accesses. 12.305 This is common on older DOS-based systems.</para> 12.306 </listitem> 12.307 - <listitem><para>Case preserving, but insensitive. When a file 12.308 + <listitem><para id="x_56d">Case preserving, but insensitive. When a file 12.309 or directory is created, the case of its name is stored, and 12.310 can be retrieved and displayed by the operating system. 12.311 When an existing file is being looked up, its case is 12.312 @@ -307,13 +307,13 @@ 12.313 interchangeable is also referred to as <emphasis>case 12.314 folding</emphasis>.</para> 12.315 </listitem> 12.316 - <listitem><para>Case sensitive. The case of a name is 12.317 + <listitem><para id="x_56e">Case sensitive. The case of a name is 12.318 significant at all times. The names <filename>foo</filename> 12.319 and {FoO} identify different files. This is the way Linux 12.320 and Unix systems normally work.</para> 12.321 </listitem></itemizedlist> 12.322 12.323 - <para>On Unix-like systems, it is possible to have any or all of 12.324 + <para id="x_56f">On Unix-like systems, it is possible to have any or all of 12.325 the above ways of handling case in action at once. For example, 12.326 if you use a USB thumb drive formatted with a FAT32 filesystem 12.327 on a Linux system, Linux will handle names on that filesystem in 12.328 @@ -322,7 +322,7 @@ 12.329 <sect2> 12.330 <title>Safe, portable repository storage</title> 12.331 12.332 - <para>Mercurial's repository storage mechanism is <emphasis>case 12.333 + <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case 12.334 safe</emphasis>. It translates file names so that they can 12.335 be safely stored on both case sensitive and case insensitive 12.336 filesystems. This means that you can use normal file copying 12.337 @@ -335,13 +335,13 @@ 12.338 <sect2> 12.339 <title>Detecting case conflicts</title> 12.340 12.341 - <para>When operating in the working directory, Mercurial honours 12.342 + <para id="x_571">When operating in the working directory, Mercurial honours 12.343 the naming policy of the filesystem where the working 12.344 directory is located. If the filesystem is case preserving, 12.345 but insensitive, Mercurial will treat names that differ only 12.346 in case as the same.</para> 12.347 12.348 - <para>An important aspect of this approach is that it is 12.349 + <para id="x_572">An important aspect of this approach is that it is 12.350 possible to commit a changeset on a case sensitive (typically 12.351 Linux or Unix) filesystem that will cause trouble for users on 12.352 case insensitive (usually Windows and MacOS) users. If a 12.353 @@ -352,7 +352,7 @@ 12.354 Linux users, they will be correctly represented as separate 12.355 files.</para> 12.356 12.357 - <para>If a Windows or Mac user pulls this change, they will not 12.358 + <para id="x_573">If a Windows or Mac user pulls this change, they will not 12.359 initially have a problem, because Mercurial's repository 12.360 storage mechanism is case safe. However, once they try to 12.361 <command role="hg-cmd">hg update</command> the working 12.362 @@ -366,14 +366,14 @@ 12.363 <sect2> 12.364 <title>Fixing a case conflict</title> 12.365 12.366 - <para>If you are using Windows or a Mac in a mixed environment 12.367 + <para id="x_574">If you are using Windows or a Mac in a mixed environment 12.368 where some of your collaborators are using Linux or Unix, and 12.369 Mercurial reports a case folding conflict when you try to 12.370 <command role="hg-cmd">hg update</command> or <command 12.371 role="hg-cmd">hg merge</command>, the procedure to fix the 12.372 problem is simple.</para> 12.373 12.374 - <para>Just find a nearby Linux or Unix box, clone the problem 12.375 + <para id="x_575">Just find a nearby Linux or Unix box, clone the problem 12.376 repository onto it, and use Mercurial's <command 12.377 role="hg-cmd">hg rename</command> command to change the 12.378 names of any offending files or directories so that they will 12.379 @@ -383,14 +383,14 @@ 12.380 MacOS system, and <command role="hg-cmd">hg update</command> 12.381 to the revision with the non-conflicting names.</para> 12.382 12.383 - <para>The changeset with case-conflicting names will remain in 12.384 + <para id="x_576">The changeset with case-conflicting names will remain in 12.385 your project's history, and you still won't be able to 12.386 <command role="hg-cmd">hg update</command> your working 12.387 directory to that changeset on a Windows or MacOS system, but 12.388 you can continue development unimpeded.</para> 12.389 12.390 <note> 12.391 - <para> Prior to version 0.9.3, Mercurial did not use a case 12.392 + <para id="x_577"> Prior to version 0.9.3, Mercurial did not use a case 12.393 safe repository storage mechanism, and did not detect case 12.394 folding conflicts. If you are using an older version of 12.395 Mercurial on Windows or MacOS, I strongly recommend that you
13.1 --- a/en/ch07-branch.xml Thu Mar 19 20:54:12 2009 -0700 13.2 +++ b/en/ch07-branch.xml Thu Mar 19 21:18:52 2009 -0700 13.3 @@ -4,18 +4,18 @@ 13.4 <?dbhtml filename="managing-releases-and-branchy-development.html"?> 13.5 <title>Managing releases and branchy development</title> 13.6 13.7 - <para>Mercurial provides several mechanisms for you to manage a 13.8 + <para id="x_369">Mercurial provides several mechanisms for you to manage a 13.9 project that is making progress on multiple fronts at once. To 13.10 understand these mechanisms, let's first take a brief look at a 13.11 fairly normal software project structure.</para> 13.12 13.13 - <para>Many software projects issue periodic <quote>major</quote> 13.14 + <para id="x_36a">Many software projects issue periodic <quote>major</quote> 13.15 releases that contain substantial new features. In parallel, they 13.16 may issue <quote>minor</quote> releases. These are usually 13.17 identical to the major releases off which they're based, but with 13.18 a few bugs fixed.</para> 13.19 13.20 - <para>In this chapter, we'll start by talking about how to keep 13.21 + <para id="x_36b">In this chapter, we'll start by talking about how to keep 13.22 records of project milestones such as releases. We'll then 13.23 continue on to talk about the flow of work between different 13.24 phases of a project, and how Mercurial can help you to isolate and 13.25 @@ -24,20 +24,20 @@ 13.26 <sect1> 13.27 <title>Giving a persistent name to a revision</title> 13.28 13.29 - <para>Once you decide that you'd like to call a particular 13.30 + <para id="x_36c">Once you decide that you'd like to call a particular 13.31 revision a <quote>release</quote>, it's a good idea to record 13.32 the identity of that revision. This will let you reproduce that 13.33 release at a later date, for whatever purpose you might need at 13.34 the time (reproducing a bug, porting to a new platform, etc). 13.35 &interaction.tag.init;</para> 13.36 13.37 - <para>Mercurial lets you give a permanent name to any revision 13.38 + <para id="x_36d">Mercurial lets you give a permanent name to any revision 13.39 using the <command role="hg-cmd">hg tag</command> command. Not 13.40 surprisingly, these names are called <quote>tags</quote>.</para> 13.41 13.42 &interaction.tag.tag; 13.43 13.44 - <para>A tag is nothing more than a <quote>symbolic name</quote> 13.45 + <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote> 13.46 for a revision. Tags exist purely for your convenience, so that 13.47 you have a handy permanent way to refer to a revision; Mercurial 13.48 doesn't interpret the tag names you use in any way. Neither 13.49 @@ -46,17 +46,17 @@ 13.50 parsed unambiguously. A tag name cannot contain any of the 13.51 following characters:</para> 13.52 <itemizedlist> 13.53 - <listitem><para>Colon (ASCII 58, 13.54 + <listitem><para id="x_36f">Colon (ASCII 58, 13.55 <quote><literal>:</literal></quote>)</para> 13.56 </listitem> 13.57 - <listitem><para>Carriage return (ASCII 13, 13.58 + <listitem><para id="x_370">Carriage return (ASCII 13, 13.59 <quote><literal>\r</literal></quote>)</para> 13.60 </listitem> 13.61 - <listitem><para>Newline (ASCII 10, 13.62 + <listitem><para id="x_371">Newline (ASCII 10, 13.63 <quote><literal>\n</literal></quote>)</para> 13.64 </listitem></itemizedlist> 13.65 13.66 - <para>You can use the <command role="hg-cmd">hg tags</command> 13.67 + <para id="x_372">You can use the <command role="hg-cmd">hg tags</command> 13.68 command to display the tags present in your repository. In the 13.69 output, each tagged revision is identified first by its name, 13.70 then by revision number, and finally by the unique hash of the 13.71 @@ -64,33 +64,33 @@ 13.72 13.73 &interaction.tag.tags; 13.74 13.75 - <para>Notice that <literal>tip</literal> is listed in the output 13.76 + <para id="x_373">Notice that <literal>tip</literal> is listed in the output 13.77 of <command role="hg-cmd">hg tags</command>. The 13.78 <literal>tip</literal> tag is a special <quote>floating</quote> 13.79 tag, which always identifies the newest revision in the 13.80 repository.</para> 13.81 13.82 - <para>In the output of the <command role="hg-cmd">hg 13.83 + <para id="x_374">In the output of the <command role="hg-cmd">hg 13.84 tags</command> command, tags are listed in reverse order, by 13.85 revision number. This usually means that recent tags are listed 13.86 before older tags. It also means that <literal>tip</literal> is 13.87 always going to be the first tag listed in the output of 13.88 <command role="hg-cmd">hg tags</command>.</para> 13.89 13.90 - <para>When you run <command role="hg-cmd">hg log</command>, if it 13.91 + <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it 13.92 displays a revision that has tags associated with it, it will 13.93 print those tags.</para> 13.94 13.95 &interaction.tag.log; 13.96 13.97 - <para>Any time you need to provide a revision ID to a Mercurial 13.98 + <para id="x_376">Any time you need to provide a revision ID to a Mercurial 13.99 command, the command will accept a tag name in its place. 13.100 Internally, Mercurial will translate your tag name into the 13.101 corresponding revision ID, then use that.</para> 13.102 13.103 &interaction.tag.log.v1.0; 13.104 13.105 - <para>There's no limit on the number of tags you can have in a 13.106 + <para id="x_377">There's no limit on the number of tags you can have in a 13.107 repository, or on the number of tags that a single revision can 13.108 have. As a practical matter, it's not a great idea to have 13.109 <quote>too many</quote> (a number which will vary from project 13.110 @@ -98,7 +98,7 @@ 13.111 find revisions. If you have lots of tags, the ease of using 13.112 them to identify revisions diminishes rapidly.</para> 13.113 13.114 - <para>For example, if your project has milestones as frequent as 13.115 + <para id="x_378">For example, if your project has milestones as frequent as 13.116 every few days, it's perfectly reasonable to tag each one of 13.117 those. But if you have a continuous build system that makes 13.118 sure every revision can be built cleanly, you'd be introducing a 13.119 @@ -106,12 +106,12 @@ 13.120 could tag failed builds (on the assumption that they're rare!), 13.121 or simply not use tags to track buildability.</para> 13.122 13.123 - <para>If you want to remove a tag that you no longer want, use 13.124 + <para id="x_379">If you want to remove a tag that you no longer want, use 13.125 <command role="hg-cmd">hg tag --remove</command>.</para> 13.126 13.127 &interaction.tag.remove; 13.128 13.129 - <para>You can also modify a tag at any time, so that it identifies 13.130 + <para id="x_37a">You can also modify a tag at any time, so that it identifies 13.131 a different revision, by simply issuing a new <command 13.132 role="hg-cmd">hg tag</command> command. You'll have to use the 13.133 <option role="hg-opt-tag">-f</option> option to tell Mercurial 13.134 @@ -120,13 +120,13 @@ 13.135 13.136 &interaction.tag.replace; 13.137 13.138 - <para>There will still be a permanent record of the previous 13.139 + <para id="x_37b">There will still be a permanent record of the previous 13.140 identity of the tag, but Mercurial will no longer use it. 13.141 There's thus no penalty to tagging the wrong revision; all you 13.142 have to do is turn around and tag the correct revision once you 13.143 discover your error.</para> 13.144 13.145 - <para>Mercurial stores tags in a normal revision-controlled file 13.146 + <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 13.147 in your repository. If you've created any tags, you'll find 13.148 them in a file named <filename 13.149 role="special">.hgtags</filename>. When you run the <command 13.150 @@ -141,14 +141,14 @@ 13.151 <sect2> 13.152 <title>Handling tag conflicts during a merge</title> 13.153 13.154 - <para>You won't often need to care about the <filename 13.155 + <para id="x_37d">You won't often need to care about the <filename 13.156 role="special">.hgtags</filename> file, but it sometimes 13.157 makes its presence known during a merge. The format of the 13.158 file is simple: it consists of a series of lines. Each line 13.159 starts with a changeset hash, followed by a space, followed by 13.160 the name of a tag.</para> 13.161 13.162 - <para>If you're resolving a conflict in the <filename 13.163 + <para id="x_37e">If you're resolving a conflict in the <filename 13.164 role="special">.hgtags</filename> file during a merge, 13.165 there's one twist to modifying the <filename 13.166 role="special">.hgtags</filename> file: when Mercurial is 13.167 @@ -158,7 +158,7 @@ 13.168 reads the <emphasis>most recently committed</emphasis> 13.169 revision of the file.</para> 13.170 13.171 - <para>An unfortunate consequence of this design is that you 13.172 + <para id="x_37f">An unfortunate consequence of this design is that you 13.173 can't actually verify that your merged <filename 13.174 role="special">.hgtags</filename> file is correct until 13.175 <emphasis>after</emphasis> you've committed a change. So if 13.176 @@ -175,7 +175,7 @@ 13.177 <sect2> 13.178 <title>Tags and cloning</title> 13.179 13.180 - <para>You may have noticed that the <command role="hg-cmd">hg 13.181 + <para id="x_380">You may have noticed that the <command role="hg-cmd">hg 13.182 clone</command> command has a <option 13.183 role="hg-opt-clone">-r</option> option that lets you clone 13.184 an exact copy of the repository as of a particular changeset. 13.185 @@ -183,7 +183,7 @@ 13.186 after the revision you specified. This has an interaction 13.187 with tags that can surprise the unwary.</para> 13.188 13.189 - <para>Recall that a tag is stored as a revision to the <filename 13.190 + <para id="x_381">Recall that a tag is stored as a revision to the <filename 13.191 role="special">.hgtags</filename> file, so that when you 13.192 create a tag, the changeset in which it's recorded necessarily 13.193 refers to an older changeset. When you run <command 13.194 @@ -200,7 +200,7 @@ 13.195 <sect2> 13.196 <title>When permanent tags are too much</title> 13.197 13.198 - <para>Since Mercurial's tags are revision controlled and carried 13.199 + <para id="x_382">Since Mercurial's tags are revision controlled and carried 13.200 around with a project's history, everyone you work with will 13.201 see the tags you create. But giving names to revisions has 13.202 uses beyond simply noting that revision 13.203 @@ -210,7 +210,7 @@ 13.204 like <quote>Anne saw the symptoms with this 13.205 revision</quote>.</para> 13.206 13.207 - <para>For cases like this, what you might want to use are 13.208 + <para id="x_383">For cases like this, what you might want to use are 13.209 <emphasis>local</emphasis> tags. You can create a local tag 13.210 with the <option role="hg-opt-tag">-l</option> option to the 13.211 <command role="hg-cmd">hg tag</command> command. This will 13.212 @@ -227,27 +227,27 @@ 13.213 <sect1> 13.214 <title>The flow of changes&emdash;big picture vs. little</title> 13.215 13.216 - <para>To return to the outline I sketched at the beginning of a 13.217 + <para id="x_384">To return to the outline I sketched at the beginning of a 13.218 chapter, let's think about a project that has multiple 13.219 concurrent pieces of work under development at once.</para> 13.220 13.221 - <para>There might be a push for a new <quote>main</quote> release; 13.222 + <para id="x_385">There might be a push for a new <quote>main</quote> release; 13.223 a new minor bugfix release to the last main release; and an 13.224 unexpected <quote>hot fix</quote> to an old release that is now 13.225 in maintenance mode.</para> 13.226 13.227 - <para>The usual way people refer to these different concurrent 13.228 + <para id="x_386">The usual way people refer to these different concurrent 13.229 directions of development is as <quote>branches</quote>. 13.230 However, we've already seen numerous times that Mercurial treats 13.231 <emphasis>all of history</emphasis> as a series of branches and 13.232 merges. Really, what we have here is two ideas that are 13.233 peripherally related, but which happen to share a name.</para> 13.234 <itemizedlist> 13.235 - <listitem><para><quote>Big picture</quote> branches represent 13.236 + <listitem><para id="x_387"><quote>Big picture</quote> branches represent 13.237 the sweep of a project's evolution; people give them names, 13.238 and talk about them in conversation.</para> 13.239 </listitem> 13.240 - <listitem><para><quote>Little picture</quote> branches are 13.241 + <listitem><para id="x_388"><quote>Little picture</quote> branches are 13.242 artefacts of the day-to-day activity of developing and 13.243 merging changes. They expose the narrative of how the code 13.244 was developed.</para> 13.245 @@ -257,7 +257,7 @@ 13.246 <sect1> 13.247 <title>Managing big-picture branches in repositories</title> 13.248 13.249 - <para>The easiest way to isolate a <quote>big picture</quote> 13.250 + <para id="x_389">The easiest way to isolate a <quote>big picture</quote> 13.251 branch in Mercurial is in a dedicated repository. If you have 13.252 an existing shared repository&emdash;let's call it 13.253 <literal>myproject</literal>&emdash;that reaches a 13.254 @@ -267,20 +267,20 @@ 13.255 13.256 &interaction.branch-repo.tag; 13.257 13.258 - <para>You can then clone a new shared 13.259 + <para id="x_38a">You can then clone a new shared 13.260 <literal>myproject-1.0.1</literal> repository as of that 13.261 tag.</para> 13.262 13.263 &interaction.branch-repo.clone; 13.264 13.265 - <para>Afterwards, if someone needs to work on a bug fix that ought 13.266 + <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought 13.267 to go into an upcoming 1.0.1 minor release, they clone the 13.268 <literal>myproject-1.0.1</literal> repository, make their 13.269 changes, and push them back.</para> 13.270 13.271 &interaction.branch-repo.bugfix; 13.272 13.273 - <para>Meanwhile, development for 13.274 + <para id="x_38c">Meanwhile, development for 13.275 the next major release can continue, isolated and unabated, in 13.276 the <literal>myproject</literal> repository.</para> 13.277 13.278 @@ -290,7 +290,7 @@ 13.279 <sect1> 13.280 <title>Don't repeat yourself: merging across branches</title> 13.281 13.282 - <para>In many cases, if you have a bug to fix on a maintenance 13.283 + <para id="x_38d">In many cases, if you have a bug to fix on a maintenance 13.284 branch, the chances are good that the bug exists on your 13.285 project's main branch (and possibly other maintenance branches, 13.286 too). It's a rare developer who wants to fix the same bug 13.287 @@ -298,13 +298,13 @@ 13.288 help you to manage these bugfixes without duplicating your 13.289 work.</para> 13.290 13.291 - <para>In the simplest instance, all you need to do is pull changes 13.292 + <para id="x_38e">In the simplest instance, all you need to do is pull changes 13.293 from your maintenance branch into your local clone of the target 13.294 branch.</para> 13.295 13.296 &interaction.branch-repo.pull; 13.297 13.298 - <para>You'll then need to merge the heads of the two branches, and 13.299 + <para id="x_38f">You'll then need to merge the heads of the two branches, and 13.300 push back to the main branch.</para> 13.301 13.302 &interaction.branch-repo.merge; 13.303 @@ -313,14 +313,14 @@ 13.304 <sect1> 13.305 <title>Naming branches within one repository</title> 13.306 13.307 - <para>In most instances, isolating branches in repositories is the 13.308 + <para id="x_390">In most instances, isolating branches in repositories is the 13.309 right approach. Its simplicity makes it easy to understand; and 13.310 so it's hard to make mistakes. There's a one-to-one 13.311 relationship between branches you're working in and directories 13.312 on your system. This lets you use normal (non-Mercurial-aware) 13.313 tools to work on files within a branch/repository.</para> 13.314 13.315 - <para>If you're more in the <quote>power user</quote> category 13.316 + <para id="x_391">If you're more in the <quote>power user</quote> category 13.317 (<emphasis>and</emphasis> your collaborators are too), there is 13.318 an alternative way of handling branches that you can consider. 13.319 I've already mentioned the human-level distinction between 13.320 @@ -331,58 +331,58 @@ 13.321 it can <emphasis>also</emphasis> work with multiple <quote>big 13.322 picture</quote> branches.</para> 13.323 13.324 - <para>The key to working this way is that Mercurial lets you 13.325 + <para id="x_392">The key to working this way is that Mercurial lets you 13.326 assign a persistent <emphasis>name</emphasis> to a branch. 13.327 There always exists a branch named <literal>default</literal>. 13.328 Even before you start naming branches yourself, you can find 13.329 traces of the <literal>default</literal> branch if you look for 13.330 them.</para> 13.331 13.332 - <para>As an example, when you run the <command role="hg-cmd">hg 13.333 + <para id="x_393">As an example, when you run the <command role="hg-cmd">hg 13.334 commit</command> command, and it pops up your editor so that 13.335 you can enter a commit message, look for a line that contains 13.336 the text <quote><literal>HG: branch default</literal></quote> at 13.337 the bottom. This is telling you that your commit will occur on 13.338 the branch named <literal>default</literal>.</para> 13.339 13.340 - <para>To start working with named branches, use the <command 13.341 + <para id="x_394">To start working with named branches, use the <command 13.342 role="hg-cmd">hg branches</command> command. This command 13.343 lists the named branches already present in your repository, 13.344 telling you which changeset is the tip of each.</para> 13.345 13.346 &interaction.branch-named.branches; 13.347 13.348 - <para>Since you haven't created any named branches yet, the only 13.349 + <para id="x_395">Since you haven't created any named branches yet, the only 13.350 one that exists is <literal>default</literal>.</para> 13.351 13.352 - <para>To find out what the <quote>current</quote> branch is, run 13.353 + <para id="x_396">To find out what the <quote>current</quote> branch is, run 13.354 the <command role="hg-cmd">hg branch</command> command, giving 13.355 it no arguments. This tells you what branch the parent of the 13.356 current changeset is on.</para> 13.357 13.358 &interaction.branch-named.branch; 13.359 13.360 - <para>To create a new branch, run the <command role="hg-cmd">hg 13.361 + <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg 13.362 branch</command> command again. This time, give it one 13.363 argument: the name of the branch you want to create.</para> 13.364 13.365 &interaction.branch-named.create; 13.366 13.367 - <para>After you've created a branch, you might wonder what effect 13.368 + <para id="x_398">After you've created a branch, you might wonder what effect 13.369 the <command role="hg-cmd">hg branch</command> command has had. 13.370 What do the <command role="hg-cmd">hg status</command> and 13.371 <command role="hg-cmd">hg tip</command> commands report?</para> 13.372 13.373 &interaction.branch-named.status; 13.374 13.375 - <para>Nothing has changed in the 13.376 + <para id="x_399">Nothing has changed in the 13.377 working directory, and there's been no new history created. As 13.378 this suggests, running the <command role="hg-cmd">hg 13.379 branch</command> command has no permanent effect; it only 13.380 tells Mercurial what branch name to use the 13.381 <emphasis>next</emphasis> time you commit a changeset.</para> 13.382 13.383 - <para>When you commit a change, Mercurial records the name of the 13.384 + <para id="x_39a">When you commit a change, Mercurial records the name of the 13.385 branch on which you committed. Once you've switched from the 13.386 <literal>default</literal> branch to another and committed, 13.387 you'll see the name of the new branch show up in the output of 13.388 @@ -392,12 +392,12 @@ 13.389 13.390 &interaction.branch-named.commit; 13.391 13.392 - <para>The <command role="hg-cmd">hg log</command>-like commands 13.393 + <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands 13.394 will print the branch name of every changeset that's not on the 13.395 <literal>default</literal> branch. As a result, if you never 13.396 use named branches, you'll never see this information.</para> 13.397 13.398 - <para>Once you've named a branch and committed a change with that 13.399 + <para id="x_39c">Once you've named a branch and committed a change with that 13.400 name, every subsequent commit that descends from that change 13.401 will inherit the same branch name. You can change the name of a 13.402 branch at any time, using the <command role="hg-cmd">hg 13.403 @@ -405,7 +405,7 @@ 13.404 13.405 &interaction.branch-named.rebranch; 13.406 13.407 - <para>In practice, this is something you won't do very often, as 13.408 + <para id="x_39d">In practice, this is something you won't do very often, as 13.409 branch names tend to have fairly long lifetimes. (This isn't a 13.410 rule, just an observation.)</para> 13.411 13.412 @@ -414,7 +414,7 @@ 13.413 <title>Dealing with multiple named branches in a 13.414 repository</title> 13.415 13.416 - <para>If you have more than one named branch in a repository, 13.417 + <para id="x_39e">If you have more than one named branch in a repository, 13.418 Mercurial will remember the branch that your working directory 13.419 on when you start a command like <command role="hg-cmd">hg 13.420 update</command> or <command role="hg-cmd">hg pull 13.421 @@ -424,17 +424,17 @@ 13.422 you may need to use the <option role="hg-opt-update">-C</option> 13.423 option to <command role="hg-cmd">hg update</command>.</para> 13.424 13.425 - <para>This behaviour is a little subtle, so let's see it in 13.426 + <para id="x_39f">This behaviour is a little subtle, so let's see it in 13.427 action. First, let's remind ourselves what branch we're 13.428 currently on, and what branches are in our repository.</para> 13.429 13.430 &interaction.branch-named.parents; 13.431 13.432 - <para>We're on the <literal>bar</literal> branch, but there also 13.433 + <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also 13.434 exists an older <command role="hg-cmd">hg foo</command> 13.435 branch.</para> 13.436 13.437 - <para>We can <command role="hg-cmd">hg update</command> back and 13.438 + <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and 13.439 forth between the tips of the <literal>foo</literal> and 13.440 <literal>bar</literal> branches without needing to use the 13.441 <option role="hg-opt-update">-C</option> option, because this 13.442 @@ -443,14 +443,14 @@ 13.443 13.444 &interaction.branch-named.update-switchy; 13.445 13.446 - <para>If we go back to the <literal>foo</literal> branch and then 13.447 + <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then 13.448 run <command role="hg-cmd">hg update</command>, it will keep us 13.449 on <literal>foo</literal>, not move us to the tip of 13.450 <literal>bar</literal>.</para> 13.451 13.452 &interaction.branch-named.update-nothing; 13.453 13.454 - <para>Committing a new change on the <literal>foo</literal> branch 13.455 + <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch 13.456 introduces a new head.</para> 13.457 13.458 &interaction.branch-named.foo-commit; 13.459 @@ -459,7 +459,7 @@ 13.460 <sect1> 13.461 <title>Branch names and merging</title> 13.462 13.463 - <para>As you've probably noticed, merges in Mercurial are not 13.464 + <para id="x_3a4">As you've probably noticed, merges in Mercurial are not 13.465 symmetrical. Let's say our repository has two heads, 17 and 23. 13.466 If I <command role="hg-cmd">hg update</command> to 17 and then 13.467 <command role="hg-cmd">hg merge</command> with 23, Mercurial 13.468 @@ -469,14 +469,14 @@ 13.469 17, it records 23 as the first parent, and 17 as the 13.470 second.</para> 13.471 13.472 - <para>This affects Mercurial's choice of branch name when you 13.473 + <para id="x_3a5">This affects Mercurial's choice of branch name when you 13.474 merge. After a merge, Mercurial will retain the branch name of 13.475 the first parent when you commit the result of the merge. If 13.476 your first parent's branch name is <literal>foo</literal>, and 13.477 you merge with <literal>bar</literal>, the branch name will 13.478 still be <literal>foo</literal> after you merge.</para> 13.479 13.480 - <para>It's not unusual for a repository to contain multiple heads, 13.481 + <para id="x_3a6">It's not unusual for a repository to contain multiple heads, 13.482 each with the same branch name. Let's say I'm working on the 13.483 <literal>foo</literal> branch, and so are you. We commit 13.484 different changes; I pull your changes; I now have two heads, 13.485 @@ -484,13 +484,13 @@ 13.486 result of a merge will be a single head on the 13.487 <literal>foo</literal> branch, as you might hope.</para> 13.488 13.489 - <para>But if I'm working on the <literal>bar</literal> branch, and 13.490 + <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and 13.491 I merge work from the <literal>foo</literal> branch, the result 13.492 will remain on the <literal>bar</literal> branch.</para> 13.493 13.494 &interaction.branch-named.merge; 13.495 13.496 - <para>To give a more concrete example, if I'm working on the 13.497 + <para id="x_3a8">To give a more concrete example, if I'm working on the 13.498 <literal>bleeding-edge</literal> branch, and I want to bring in 13.499 the latest fixes from the <literal>stable</literal> branch, 13.500 Mercurial will choose the <quote>right</quote> 13.501 @@ -501,17 +501,17 @@ 13.502 <sect1> 13.503 <title>Branch naming is generally useful</title> 13.504 13.505 - <para>You shouldn't think of named branches as applicable only to 13.506 + <para id="x_3a9">You shouldn't think of named branches as applicable only to 13.507 situations where you have multiple long-lived branches 13.508 cohabiting in a single repository. They're very useful even in 13.509 the one-branch-per-repository case.</para> 13.510 13.511 - <para>In the simplest case, giving a name to each branch gives you 13.512 + <para id="x_3aa">In the simplest case, giving a name to each branch gives you 13.513 a permanent record of which branch a changeset originated on. 13.514 This gives you more context when you're trying to follow the 13.515 history of a long-lived branchy project.</para> 13.516 13.517 - <para>If you're working with shared repositories, you can set up a 13.518 + <para id="x_3ab">If you're working with shared repositories, you can set up a 13.519 <literal role="hook">pretxnchangegroup</literal> hook on each 13.520 that will block incoming changes that have the 13.521 <quote>wrong</quote> branch name. This provides a simple, but
14.1 --- a/en/ch08-undo.xml Thu Mar 19 20:54:12 2009 -0700 14.2 +++ b/en/ch08-undo.xml Thu Mar 19 21:18:52 2009 -0700 14.3 @@ -4,7 +4,7 @@ 14.4 <?dbhtml filename="finding-and-fixing-mistakes.html"?> 14.5 <title>Finding and fixing mistakes</title> 14.6 14.7 - <para>To err might be human, but to really handle the consequences 14.8 + <para id="x_d2">To err might be human, but to really handle the consequences 14.9 well takes a top-notch revision control system. In this chapter, 14.10 we'll discuss some of the techniques you can use when you find 14.11 that a problem has crept into your project. Mercurial has some 14.12 @@ -17,7 +17,7 @@ 14.13 <sect2> 14.14 <title>The accidental commit</title> 14.15 14.16 - <para>I have the occasional but persistent problem of typing 14.17 + <para id="x_d3">I have the occasional but persistent problem of typing 14.18 rather more quickly than I can think, which sometimes results 14.19 in me committing a changeset that is either incomplete or 14.20 plain wrong. In my case, the usual kind of incomplete 14.21 @@ -30,7 +30,7 @@ 14.22 <sect2 id="sec:undo:rollback"> 14.23 <title>Rolling back a transaction</title> 14.24 14.25 - <para>In section <xref linkend="sec:concepts:txn"/>, I mentioned 14.26 + <para id="x_d4">In section <xref linkend="sec:concepts:txn"/>, I mentioned 14.27 that Mercurial treats each modification of a repository as a 14.28 <emphasis>transaction</emphasis>. Every time you commit a 14.29 changeset or pull changes from another repository, Mercurial 14.30 @@ -40,20 +40,20 @@ 14.31 section <xref linkend="sec:undo:rollback-after-push"/> for an 14.32 important caveat about the use of this command.)</para> 14.33 14.34 - <para>Here's a mistake that I often find myself making: 14.35 + <para id="x_d5">Here's a mistake that I often find myself making: 14.36 committing a change in which I've created a new file, but 14.37 forgotten to <command role="hg-cmd">hg add</command> 14.38 it.</para> 14.39 14.40 &interaction.rollback.commit; 14.41 14.42 - <para>Looking at the output of <command role="hg-cmd">hg 14.43 + <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 14.44 status</command> after the commit immediately confirms the 14.45 error.</para> 14.46 14.47 &interaction.rollback.status; 14.48 14.49 - <para>The commit captured the changes to the file 14.50 + <para id="x_d7">The commit captured the changes to the file 14.51 <filename>a</filename>, but not the new file 14.52 <filename>b</filename>. If I were to push this changeset to a 14.53 repository that I shared with a colleague, the chances are 14.54 @@ -62,14 +62,14 @@ 14.55 repository when they pulled my changes. I would thus become 14.56 the object of some indignation.</para> 14.57 14.58 - <para>However, luck is with me&emdash;I've caught my error 14.59 + <para id="x_d8">However, luck is with me&emdash;I've caught my error 14.60 before I pushed the changeset. I use the <command 14.61 role="hg-cmd">hg rollback</command> command, and Mercurial 14.62 makes that last changeset vanish.</para> 14.63 14.64 &interaction.rollback.rollback; 14.65 14.66 - <para>Notice that the changeset is no longer present in the 14.67 + <para id="x_d9">Notice that the changeset is no longer present in the 14.68 repository's history, and the working directory once again 14.69 thinks that the file <filename>a</filename> is modified. The 14.70 commit and rollback have left the working directory exactly as 14.71 @@ -84,14 +84,14 @@ 14.72 <sect2> 14.73 <title>The erroneous pull</title> 14.74 14.75 - <para>It's common practice with Mercurial to maintain separate 14.76 + <para id="x_da">It's common practice with Mercurial to maintain separate 14.77 development branches of a project in different repositories. 14.78 Your development team might have one shared repository for 14.79 your project's <quote>0.9</quote> release, and another, 14.80 containing different changes, for the <quote>1.0</quote> 14.81 release.</para> 14.82 14.83 - <para>Given this, you can imagine that the consequences could be 14.84 + <para id="x_db">Given this, you can imagine that the consequences could be 14.85 messy if you had a local <quote>0.9</quote> repository, and 14.86 accidentally pulled changes from the shared <quote>1.0</quote> 14.87 repository into it. At worst, you could be paying 14.88 @@ -103,7 +103,7 @@ 14.89 see it pull a suspiciously large number of changes into the 14.90 repository.</para> 14.91 14.92 - <para>The <command role="hg-cmd">hg rollback</command> command 14.93 + <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 14.94 will work nicely to expunge all of the changesets that you 14.95 just pulled. Mercurial groups all changes from one <command 14.96 role="hg-cmd">hg pull</command> into a single transaction, 14.97 @@ -114,7 +114,7 @@ 14.98 <sect2 id="sec:undo:rollback-after-push"> 14.99 <title>Rolling back is useless once you've pushed</title> 14.100 14.101 - <para>The value of the <command role="hg-cmd">hg 14.102 + <para id="x_dd">The value of the <command role="hg-cmd">hg 14.103 rollback</command> command drops to zero once you've pushed 14.104 your changes to another repository. Rolling back a change 14.105 makes it disappear entirely, but <emphasis>only</emphasis> in 14.106 @@ -123,7 +123,7 @@ 14.107 eliminates history, there's no way for the disappearance of a 14.108 change to propagate between repositories.</para> 14.109 14.110 - <para>If you've pushed a change to another 14.111 + <para id="x_de">If you've pushed a change to another 14.112 repository&emdash;particularly if it's a shared 14.113 repository&emdash;it has essentially <quote>escaped into the 14.114 wild,</quote> and you'll have to recover from your mistake 14.115 @@ -132,7 +132,7 @@ 14.116 you pushed to, is that the changeset will reappear in your 14.117 repository.</para> 14.118 14.119 - <para>(If you absolutely know for sure that the change you want 14.120 + <para id="x_df">(If you absolutely know for sure that the change you want 14.121 to roll back is the most recent change in the repository that 14.122 you pushed to, <emphasis>and</emphasis> you know that nobody 14.123 else could have pulled it from that repository, you can roll 14.124 @@ -146,7 +146,7 @@ 14.125 <sect2> 14.126 <title>You can only roll back once</title> 14.127 14.128 - <para>Mercurial stores exactly one transaction in its 14.129 + <para id="x_e0">Mercurial stores exactly one transaction in its 14.130 transaction log; that transaction is the most recent one that 14.131 occurred in the repository. This means that you can only roll 14.132 back one transaction. If you expect to be able to roll back 14.133 @@ -155,7 +155,7 @@ 14.134 14.135 &interaction.rollback.twice; 14.136 14.137 - <para>Once you've rolled back one transaction in a repository, 14.138 + <para id="x_e1">Once you've rolled back one transaction in a repository, 14.139 you can't roll back again in that repository until you perform 14.140 another commit or pull.</para> 14.141 14.142 @@ -164,7 +164,7 @@ 14.143 <sect1> 14.144 <title>Reverting the mistaken change</title> 14.145 14.146 - <para>If you make a modification to a file, and decide that you 14.147 + <para id="x_e2">If you make a modification to a file, and decide that you 14.148 really didn't want to change the file at all, and you haven't 14.149 yet committed your changes, the <command role="hg-cmd">hg 14.150 revert</command> command is the one you'll need. It looks at 14.151 @@ -173,42 +173,42 @@ 14.152 changeset. (That's a long-winded way of saying that, in the 14.153 normal case, it undoes your modifications.)</para> 14.154 14.155 - <para>Let's illustrate how the <command role="hg-cmd">hg 14.156 + <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 14.157 revert</command> command works with yet another small example. 14.158 We'll begin by modifying a file that Mercurial is already 14.159 tracking.</para> 14.160 14.161 &interaction.daily.revert.modify; 14.162 14.163 - <para>If we don't 14.164 + <para id="x_e4">If we don't 14.165 want that change, we can simply <command role="hg-cmd">hg 14.166 revert</command> the file.</para> 14.167 14.168 &interaction.daily.revert.unmodify; 14.169 14.170 - <para>The <command role="hg-cmd">hg revert</command> command 14.171 + <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 14.172 provides us with an extra degree of safety by saving our 14.173 modified file with a <filename>.orig</filename> 14.174 extension.</para> 14.175 14.176 &interaction.daily.revert.status; 14.177 14.178 - <para>Here is a summary of the cases that the <command 14.179 + <para id="x_e6">Here is a summary of the cases that the <command 14.180 role="hg-cmd">hg revert</command> command can deal with. We 14.181 will describe each of these in more detail in the section that 14.182 follows.</para> 14.183 <itemizedlist> 14.184 - <listitem><para>If you modify a file, it will restore the file 14.185 + <listitem><para id="x_e7">If you modify a file, it will restore the file 14.186 to its unmodified state.</para> 14.187 </listitem> 14.188 - <listitem><para>If you <command role="hg-cmd">hg add</command> a 14.189 + <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 14.190 file, it will undo the <quote>added</quote> state of the 14.191 file, but leave the file itself untouched.</para> 14.192 </listitem> 14.193 - <listitem><para>If you delete a file without telling Mercurial, 14.194 + <listitem><para id="x_e9">If you delete a file without telling Mercurial, 14.195 it will restore the file to its unmodified contents.</para> 14.196 </listitem> 14.197 - <listitem><para>If you use the <command role="hg-cmd">hg 14.198 + <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 14.199 remove</command> command to remove a file, it will undo 14.200 the <quote>removed</quote> state of the file, and restore 14.201 the file to its unmodified contents.</para> 14.202 @@ -217,13 +217,13 @@ 14.203 <sect2 id="sec:undo:mgmt"> 14.204 <title>File management errors</title> 14.205 14.206 - <para>The <command role="hg-cmd">hg revert</command> command is 14.207 + <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 14.208 useful for more than just modified files. It lets you reverse 14.209 the results of all of Mercurial's file management 14.210 commands&emdash;<command role="hg-cmd">hg add</command>, 14.211 <command role="hg-cmd">hg remove</command>, and so on.</para> 14.212 14.213 - <para>If you <command role="hg-cmd">hg add</command> a file, 14.214 + <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 14.215 then decide that in fact you don't want Mercurial to track it, 14.216 use <command role="hg-cmd">hg revert</command> to undo the 14.217 add. Don't worry; Mercurial will not modify the file in any 14.218 @@ -231,7 +231,7 @@ 14.219 14.220 &interaction.daily.revert.add; 14.221 14.222 - <para>Similarly, if you ask Mercurial to <command 14.223 + <para id="x_ed">Similarly, if you ask Mercurial to <command 14.224 role="hg-cmd">hg remove</command> a file, you can use 14.225 <command role="hg-cmd">hg revert</command> to restore it to 14.226 the contents it had as of the parent of the working directory. 14.227 @@ -242,7 +242,7 @@ 14.228 14.229 &interaction.daily.revert.missing; 14.230 14.231 - <para>If you revert a <command role="hg-cmd">hg copy</command>, 14.232 + <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 14.233 the copied-to file remains in your working directory 14.234 afterwards, untracked. Since a copy doesn't affect the 14.235 copied-from file in any way, Mercurial doesn't do anything 14.236 @@ -253,7 +253,7 @@ 14.237 <sect3> 14.238 <title>A slightly special case: reverting a rename</title> 14.239 14.240 - <para>If you <command role="hg-cmd">hg rename</command> a 14.241 + <para id="x_ef">If you <command role="hg-cmd">hg rename</command> a 14.242 file, there is one small detail that you should remember. 14.243 When you <command role="hg-cmd">hg revert</command> a 14.244 rename, it's not enough to provide the name of the 14.245 @@ -261,7 +261,7 @@ 14.246 14.247 &interaction.daily.revert.rename; 14.248 14.249 - <para>As you can see from the output of <command 14.250 + <para id="x_f0">As you can see from the output of <command 14.251 role="hg-cmd">hg status</command>, the renamed-to file is 14.252 no longer identified as added, but the 14.253 renamed-<emphasis>from</emphasis> file is still removed! 14.254 @@ -270,22 +270,22 @@ 14.255 14.256 &interaction.daily.revert.rename-orig; 14.257 14.258 - <para>So remember, to revert a <command role="hg-cmd">hg 14.259 + <para id="x_f1">So remember, to revert a <command role="hg-cmd">hg 14.260 rename</command>, you must provide 14.261 <emphasis>both</emphasis> the source and destination 14.262 names.</para> 14.263 14.264 - <para>% TODO: the output doesn't look like it will be 14.265 + <para id="x_f2">% TODO: the output doesn't look like it will be 14.266 removed!</para> 14.267 14.268 - <para>(By the way, if you rename a file, then modify the 14.269 + <para id="x_f3">(By the way, if you rename a file, then modify the 14.270 renamed-to file, then revert both components of the rename, 14.271 when Mercurial restores the file that was removed as part of 14.272 the rename, it will be unmodified. If you need the 14.273 modifications in the renamed-to file to show up in the 14.274 renamed-from file, don't forget to copy them over.)</para> 14.275 14.276 - <para>These fiddly aspects of reverting a rename arguably 14.277 + <para id="x_f4">These fiddly aspects of reverting a rename arguably 14.278 constitute a small bug in Mercurial.</para> 14.279 14.280 </sect3> 14.281 @@ -294,13 +294,13 @@ 14.282 <sect1> 14.283 <title>Dealing with committed changes</title> 14.284 14.285 - <para>Consider a case where you have committed a change $a$, and 14.286 + <para id="x_f5">Consider a case where you have committed a change $a$, and 14.287 another change $b$ on top of it; you then realise that change 14.288 $a$ was incorrect. Mercurial lets you <quote>back out</quote> 14.289 an entire changeset automatically, and building blocks that let 14.290 you reverse part of a changeset by hand.</para> 14.291 14.292 - <para>Before you read this section, here's something to keep in 14.293 + <para id="x_f6">Before you read this section, here's something to keep in 14.294 mind: the <command role="hg-cmd">hg backout</command> command 14.295 undoes changes by <emphasis>adding</emphasis> history, not by 14.296 modifying or erasing it. It's the right tool to use if you're 14.297 @@ -311,7 +311,7 @@ 14.298 <sect2> 14.299 <title>Backing out a changeset</title> 14.300 14.301 - <para>The <command role="hg-cmd">hg backout</command> command 14.302 + <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 14.303 lets you <quote>undo</quote> the effects of an entire 14.304 changeset in an automated fashion. Because Mercurial's 14.305 history is immutable, this command <emphasis>does 14.306 @@ -320,14 +320,14 @@ 14.307 <emphasis>reverses</emphasis> the effect of the to-be-undone 14.308 changeset.</para> 14.309 14.310 - <para>The operation of the <command role="hg-cmd">hg 14.311 + <para id="x_f8">The operation of the <command role="hg-cmd">hg 14.312 backout</command> command is a little intricate, so let's 14.313 illustrate it with some examples. First, we'll create a 14.314 repository with some simple changes.</para> 14.315 14.316 &interaction.backout.init; 14.317 14.318 - <para>The <command role="hg-cmd">hg backout</command> command 14.319 + <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 14.320 takes a single changeset ID as its argument; this is the 14.321 changeset to back out. Normally, <command role="hg-cmd">hg 14.322 backout</command> will drop you into a text editor to write 14.323 @@ -340,12 +340,12 @@ 14.324 <sect2> 14.325 <title>Backing out the tip changeset</title> 14.326 14.327 - <para>We're going to start by backing out the last changeset we 14.328 + <para id="x_fa">We're going to start by backing out the last changeset we 14.329 committed.</para> 14.330 14.331 &interaction.backout.simple; 14.332 14.333 - <para>You can see that the second line from 14.334 + <para id="x_fb">You can see that the second line from 14.335 <filename>myfile</filename> is no longer present. Taking a 14.336 look at the output of <command role="hg-cmd">hg log</command> 14.337 gives us an idea of what the <command role="hg-cmd">hg 14.338 @@ -361,7 +361,7 @@ 14.339 <informalfigure id="fig:undo:backout"> 14.340 <mediaobject><imageobject><imagedata 14.341 fileref="undo-simple"/></imageobject><textobject><phrase>XXX 14.342 - add text</phrase></textobject><caption><para>Backing out 14.343 + add text</phrase></textobject><caption><para id="x_fc">Backing out 14.344 a change using the <command role="hg-cmd">hg 14.345 backout</command> 14.346 command</para></caption></mediaobject> 14.347 @@ -372,27 +372,27 @@ 14.348 <sect2> 14.349 <title>Backing out a non-tip change</title> 14.350 14.351 - <para>If you want to back out a change other than the last one 14.352 + <para id="x_fd">If you want to back out a change other than the last one 14.353 you committed, pass the <option 14.354 role="hg-opt-backout">--merge</option> option to the 14.355 <command role="hg-cmd">hg backout</command> command.</para> 14.356 14.357 &interaction.backout.non-tip.clone; 14.358 14.359 - <para>This makes backing out any changeset a 14.360 + <para id="x_fe">This makes backing out any changeset a 14.361 <quote>one-shot</quote> operation that's usually simple and 14.362 fast.</para> 14.363 14.364 &interaction.backout.non-tip.backout; 14.365 14.366 - <para>If you take a look at the contents of 14.367 + <para id="x_ff">If you take a look at the contents of 14.368 <filename>myfile</filename> after the backout finishes, you'll 14.369 see that the first and third changes are present, but not the 14.370 second.</para> 14.371 14.372 &interaction.backout.non-tip.cat; 14.373 14.374 - <para>As the graphical history in figure <xref 14.375 + <para id="x_100">As the graphical history in figure <xref 14.376 linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 14.377 actually commits <emphasis>two</emphasis> changes in this kind 14.378 of situation (the box-shaped nodes are the ones that Mercurial 14.379 @@ -403,19 +403,19 @@ 14.380 the previous parent of the working directory, and commits the 14.381 result of the merge.</para> 14.382 14.383 - <para>% TODO: to me it looks like mercurial doesn't commit the 14.384 + <para id="x_101">% TODO: to me it looks like mercurial doesn't commit the 14.385 second merge automatically!</para> 14.386 14.387 <informalfigure id="fig:undo:backout-non-tip"> 14.388 <mediaobject><imageobject><imagedata 14.389 fileref="undo-non-tip"/></imageobject><textobject><phrase>XXX 14.390 - add text</phrase></textobject><caption><para>Automated 14.391 + add text</phrase></textobject><caption><para id="x_102">Automated 14.392 backout of a non-tip change using the <command 14.393 role="hg-cmd">hg backout</command> 14.394 command</para></caption></mediaobject> 14.395 </informalfigure> 14.396 14.397 - <para>The result is that you end up <quote>back where you 14.398 + <para id="x_103">The result is that you end up <quote>back where you 14.399 were</quote>, only with some extra history that undoes the 14.400 effect of the changeset you wanted to back out.</para> 14.401 14.402 @@ -423,7 +423,7 @@ 14.403 <title>Always use the <option 14.404 role="hg-opt-backout">--merge</option> option</title> 14.405 14.406 - <para>In fact, since the <option 14.407 + <para id="x_104">In fact, since the <option 14.408 role="hg-opt-backout">--merge</option> option will do the 14.409 <quote>right thing</quote> whether or not the changeset 14.410 you're backing out is the tip (i.e. it won't try to merge if 14.411 @@ -436,7 +436,7 @@ 14.412 <sect2> 14.413 <title>Gaining more control of the backout process</title> 14.414 14.415 - <para>While I've recommended that you always use the <option 14.416 + <para id="x_105">While I've recommended that you always use the <option 14.417 role="hg-opt-backout">--merge</option> option when backing 14.418 out a change, the <command role="hg-cmd">hg backout</command> 14.419 command lets you decide how to merge a backout changeset. 14.420 @@ -449,13 +449,13 @@ 14.421 14.422 &interaction.backout.manual.clone; 14.423 14.424 - <para>As with our 14.425 + <para id="x_106">As with our 14.426 earlier example, We'll commit a third changeset, then back out 14.427 its parent, and see what happens.</para> 14.428 14.429 &interaction.backout.manual.backout; 14.430 14.431 - <para>Our new changeset is again a descendant of the changeset 14.432 + <para id="x_107">Our new changeset is again a descendant of the changeset 14.433 we backout out; it's thus a new head, <emphasis>not</emphasis> 14.434 a descendant of the changeset that was the tip. The <command 14.435 role="hg-cmd">hg backout</command> command was quite 14.436 @@ -463,7 +463,7 @@ 14.437 14.438 &interaction.backout.manual.log; 14.439 14.440 - <para>Again, it's easier to see what has happened by looking at 14.441 + <para id="x_108">Again, it's easier to see what has happened by looking at 14.442 a graph of the revision history, in figure <xref 14.443 linkend="fig:undo:backout-manual"/>. This makes it clear 14.444 that when we use <command role="hg-cmd">hg backout</command> 14.445 @@ -474,25 +474,25 @@ 14.446 <informalfigure id="fig:undo:backout-manual"> 14.447 <mediaobject><imageobject><imagedata 14.448 fileref="undo-manual"/></imageobject><textobject><phrase>XXX 14.449 - add text</phrase></textobject><caption><para>Backing out 14.450 + add text</phrase></textobject><caption><para id="x_109">Backing out 14.451 a change using the <command role="hg-cmd">hg 14.452 backout</command> 14.453 command</para></caption></mediaobject> 14.454 14.455 </informalfigure> 14.456 14.457 - <para>After the <command role="hg-cmd">hg backout</command> 14.458 + <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 14.459 command has completed, it leaves the new 14.460 <quote>backout</quote> changeset as the parent of the working 14.461 directory.</para> 14.462 14.463 &interaction.backout.manual.parents; 14.464 14.465 - <para>Now we have two isolated sets of changes.</para> 14.466 + <para id="x_10b">Now we have two isolated sets of changes.</para> 14.467 14.468 &interaction.backout.manual.heads; 14.469 14.470 - <para>Let's think about what we expect to see as the contents of 14.471 + <para id="x_10c">Let's think about what we expect to see as the contents of 14.472 <filename>myfile</filename> now. The first change should be 14.473 present, because we've never backed it out. The second change 14.474 should be missing, as that's the change we backed out. Since 14.475 @@ -502,19 +502,19 @@ 14.476 14.477 &interaction.backout.manual.cat; 14.478 14.479 - <para>To get the third change back into the file, we just do a 14.480 + <para id="x_10d">To get the third change back into the file, we just do a 14.481 normal merge of our two heads.</para> 14.482 14.483 &interaction.backout.manual.merge; 14.484 14.485 - <para>Afterwards, the graphical history of our repository looks 14.486 + <para id="x_10e">Afterwards, the graphical history of our repository looks 14.487 like figure 14.488 <xref linkend="fig:undo:backout-manual-merge"/>.</para> 14.489 14.490 <informalfigure id="fig:undo:backout-manual-merge"> 14.491 <mediaobject><imageobject><imagedata 14.492 fileref="undo-manual-merge"/></imageobject><textobject><phrase>XXX 14.493 - add text</phrase></textobject><caption><para>Manually 14.494 + add text</phrase></textobject><caption><para id="x_10f">Manually 14.495 merging a backout change</para></caption></mediaobject> 14.496 14.497 </informalfigure> 14.498 @@ -524,43 +524,43 @@ 14.499 <title>Why <command role="hg-cmd">hg backout</command> works as 14.500 it does</title> 14.501 14.502 - <para>Here's a brief description of how the <command 14.503 + <para id="x_110">Here's a brief description of how the <command 14.504 role="hg-cmd">hg backout</command> command works.</para> 14.505 <orderedlist> 14.506 - <listitem><para>It ensures that the working directory is 14.507 + <listitem><para id="x_111">It ensures that the working directory is 14.508 <quote>clean</quote>, i.e. that the output of <command 14.509 role="hg-cmd">hg status</command> would be empty.</para> 14.510 </listitem> 14.511 - <listitem><para>It remembers the current parent of the working 14.512 + <listitem><para id="x_112">It remembers the current parent of the working 14.513 directory. Let's call this changeset 14.514 <literal>orig</literal></para> 14.515 </listitem> 14.516 - <listitem><para>It does the equivalent of a <command 14.517 + <listitem><para id="x_113">It does the equivalent of a <command 14.518 role="hg-cmd">hg update</command> to sync the working 14.519 directory to the changeset you want to back out. Let's 14.520 call this changeset <literal>backout</literal></para> 14.521 </listitem> 14.522 - <listitem><para>It finds the parent of that changeset. Let's 14.523 + <listitem><para id="x_114">It finds the parent of that changeset. Let's 14.524 call that changeset <literal>parent</literal>.</para> 14.525 </listitem> 14.526 - <listitem><para>For each file that the 14.527 + <listitem><para id="x_115">For each file that the 14.528 <literal>backout</literal> changeset affected, it does the 14.529 equivalent of a <command role="hg-cmd">hg revert -r 14.530 parent</command> on that file, to restore it to the 14.531 contents it had before that changeset was 14.532 committed.</para> 14.533 </listitem> 14.534 - <listitem><para>It commits the result as a new changeset. 14.535 + <listitem><para id="x_116">It commits the result as a new changeset. 14.536 This changeset has <literal>backout</literal> as its 14.537 parent.</para> 14.538 </listitem> 14.539 - <listitem><para>If you specify <option 14.540 + <listitem><para id="x_117">If you specify <option 14.541 role="hg-opt-backout">--merge</option> on the command 14.542 line, it merges with <literal>orig</literal>, and commits 14.543 the result of the merge.</para> 14.544 </listitem></orderedlist> 14.545 14.546 - <para>An alternative way to implement the <command 14.547 + <para id="x_118">An alternative way to implement the <command 14.548 role="hg-cmd">hg backout</command> command would be to 14.549 <command role="hg-cmd">hg export</command> the 14.550 to-be-backed-out changeset as a diff, then use the <option 14.551 @@ -570,14 +570,14 @@ 14.552 sounds much simpler, but it would not work nearly as 14.553 well.</para> 14.554 14.555 - <para>The reason that <command role="hg-cmd">hg 14.556 + <para id="x_119">The reason that <command role="hg-cmd">hg 14.557 backout</command> does an update, a commit, a merge, and 14.558 another commit is to give the merge machinery the best chance 14.559 to do a good job when dealing with all the changes 14.560 <emphasis>between</emphasis> the change you're backing out and 14.561 the current tip.</para> 14.562 14.563 - <para>If you're backing out a changeset that's 100 revisions 14.564 + <para id="x_11a">If you're backing out a changeset that's 100 revisions 14.565 back in your project's history, the chances that the 14.566 <command>patch</command> command will be able to apply a 14.567 reverse diff cleanly are not good, because intervening changes 14.568 @@ -596,13 +596,13 @@ 14.569 <sect1 id="sec:undo:aaaiiieee"> 14.570 <title>Changes that should never have been</title> 14.571 14.572 - <para>Most of the time, the <command role="hg-cmd">hg 14.573 + <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 14.574 backout</command> command is exactly what you need if you want 14.575 to undo the effects of a change. It leaves a permanent record 14.576 of exactly what you did, both when committing the original 14.577 changeset and when you cleaned up after it.</para> 14.578 14.579 - <para>On rare occasions, though, you may find that you've 14.580 + <para id="x_11c">On rare occasions, though, you may find that you've 14.581 committed a change that really should not be present in the 14.582 repository at all. For example, it would be very unusual, and 14.583 usually considered a mistake, to commit a software project's 14.584 @@ -611,12 +611,12 @@ 14.585 so they increase the size of the repository and the amount of 14.586 time it takes to clone or pull changes.</para> 14.587 14.588 - <para>Before I discuss the options that you have if you commit a 14.589 + <para id="x_11d">Before I discuss the options that you have if you commit a 14.590 <quote>brown paper bag</quote> change (the kind that's so bad 14.591 that you want to pull a brown paper bag over your head), let me 14.592 first discuss some approaches that probably won't work.</para> 14.593 14.594 - <para>Since Mercurial treats history as accumulative&emdash;every 14.595 + <para id="x_11e">Since Mercurial treats history as accumulative&emdash;every 14.596 change builds on top of all changes that preceded it&emdash;you 14.597 generally can't just make disastrous changes disappear. The one 14.598 exception is when you've just committed a change, and it hasn't 14.599 @@ -625,7 +625,7 @@ 14.600 command, as I detailed in section <xref 14.601 linkend="sec:undo:rollback"/>.</para> 14.602 14.603 - <para>After you've pushed a bad change to another repository, you 14.604 + <para id="x_11f">After you've pushed a bad change to another repository, you 14.605 <emphasis>could</emphasis> still use <command role="hg-cmd">hg 14.606 rollback</command> to make your local copy of the change 14.607 disappear, but it won't have the consequences you want. The 14.608 @@ -633,7 +633,7 @@ 14.609 will reappear in your local repository the next time you 14.610 pull.</para> 14.611 14.612 - <para>If a situation like this arises, and you know which 14.613 + <para id="x_120">If a situation like this arises, and you know which 14.614 repositories your bad change has propagated into, you can 14.615 <emphasis>try</emphasis> to get rid of the changeefrom 14.616 <emphasis>every</emphasis> one of those repositories. This is, 14.617 @@ -641,13 +641,13 @@ 14.618 single repository while you're expunging, the change is still 14.619 <quote>in the wild</quote>, and could propagate further.</para> 14.620 14.621 - <para>If you've committed one or more changes 14.622 + <para id="x_121">If you've committed one or more changes 14.623 <emphasis>after</emphasis> the change that you'd like to see 14.624 disappear, your options are further reduced. Mercurial doesn't 14.625 provide a way to <quote>punch a hole</quote> in history, leaving 14.626 changesets intact.</para> 14.627 14.628 - <para>XXX This needs filling out. The 14.629 + <para id="x_122">XXX This needs filling out. The 14.630 <literal>hg-replay</literal> script in the 14.631 <literal>examples</literal> directory works, but doesn't handle 14.632 merge changesets. Kind of an important omission.</para> 14.633 @@ -656,14 +656,14 @@ 14.634 <title>Protect yourself from <quote>escaped</quote> 14.635 changes</title> 14.636 14.637 - <para>If you've committed some changes to your local repository 14.638 + <para id="x_123">If you've committed some changes to your local repository 14.639 and they've been pushed or pulled somewhere else, this isn't 14.640 necessarily a disaster. You can protect yourself ahead of 14.641 time against some classes of bad changeset. This is 14.642 particularly easy if your team usually pulls changes from a 14.643 central repository.</para> 14.644 14.645 - <para>By configuring some hooks on that repository to validate 14.646 + <para id="x_124">By configuring some hooks on that repository to validate 14.647 incoming changesets (see chapter <xref linkend="chap:hook"/>), 14.648 you can 14.649 automatically prevent some kinds of bad changeset from being 14.650 @@ -673,7 +673,7 @@ 14.651 propagate into the central repository. Better yet, this 14.652 happens without any need for explicit intervention.</para> 14.653 14.654 - <para>For instance, an incoming change hook that verifies that a 14.655 + <para id="x_125">For instance, an incoming change hook that verifies that a 14.656 changeset will actually compile can prevent people from 14.657 inadvertantly <quote>breaking the build</quote>.</para> 14.658 14.659 @@ -682,14 +682,14 @@ 14.660 <sect1 id="sec:undo:bisect"> 14.661 <title>Finding the source of a bug</title> 14.662 14.663 - <para>While it's all very well to be able to back out a changeset 14.664 + <para id="x_126">While it's all very well to be able to back out a changeset 14.665 that introduced a bug, this requires that you know which 14.666 changeset to back out. Mercurial provides an invaluable 14.667 command, called <command role="hg-cmd">hg bisect</command>, that 14.668 helps you to automate this process and accomplish it very 14.669 efficiently.</para> 14.670 14.671 - <para>The idea behind the <command role="hg-cmd">hg 14.672 + <para id="x_127">The idea behind the <command role="hg-cmd">hg 14.673 bisect</command> command is that a changeset has introduced 14.674 some change of behaviour that you can identify with a simple 14.675 binary test. You don't know which piece of code introduced the 14.676 @@ -698,41 +698,41 @@ 14.677 test to direct its search for the changeset that introduced the 14.678 code that caused the bug.</para> 14.679 14.680 - <para>Here are a few scenarios to help you understand how you 14.681 + <para id="x_128">Here are a few scenarios to help you understand how you 14.682 might apply this command.</para> 14.683 <itemizedlist> 14.684 - <listitem><para>The most recent version of your software has a 14.685 + <listitem><para id="x_129">The most recent version of your software has a 14.686 bug that you remember wasn't present a few weeks ago, but 14.687 you don't know when it was introduced. Here, your binary 14.688 test checks for the presence of that bug.</para> 14.689 </listitem> 14.690 - <listitem><para>You fixed a bug in a rush, and now it's time to 14.691 + <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 14.692 close the entry in your team's bug database. The bug 14.693 database requires a changeset ID when you close an entry, 14.694 but you don't remember which changeset you fixed the bug in. 14.695 Once again, your binary test checks for the presence of the 14.696 bug.</para> 14.697 </listitem> 14.698 - <listitem><para>Your software works correctly, but runs 15% 14.699 + <listitem><para id="x_12b">Your software works correctly, but runs 15% 14.700 slower than the last time you measured it. You want to know 14.701 which changeset introduced the performance regression. In 14.702 this case, your binary test measures the performance of your 14.703 software, to see whether it's <quote>fast</quote> or 14.704 <quote>slow</quote>.</para> 14.705 </listitem> 14.706 - <listitem><para>The sizes of the components of your project that 14.707 + <listitem><para id="x_12c">The sizes of the components of your project that 14.708 you ship exploded recently, and you suspect that something 14.709 changed in the way you build your project.</para> 14.710 </listitem></itemizedlist> 14.711 14.712 - <para>From these examples, it should be clear that the <command 14.713 + <para id="x_12d">From these examples, it should be clear that the <command 14.714 role="hg-cmd">hg bisect</command> command is not useful only 14.715 for finding the sources of bugs. You can use it to find any 14.716 <quote>emergent property</quote> of a repository (anything that 14.717 you can't find from a simple text search of the files in the 14.718 tree) for which you can write a binary test.</para> 14.719 14.720 - <para>We'll introduce a little bit of terminology here, just to 14.721 + <para id="x_12e">We'll introduce a little bit of terminology here, just to 14.722 make it clear which parts of the search process are your 14.723 responsibility, and which are Mercurial's. A 14.724 <emphasis>test</emphasis> is something that 14.725 @@ -745,7 +745,7 @@ 14.726 the <command role="hg-cmd">hg bisect</command> 14.727 command</quote>.</para> 14.728 14.729 - <para>One simple way to automate the searching process would be 14.730 + <para id="x_12f">One simple way to automate the searching process would be 14.731 simply to probe every changeset. However, this scales poorly. 14.732 If it took ten minutes to test a single changeset, and you had 14.733 10,000 changesets in your repository, the exhaustive approach 14.734 @@ -755,7 +755,7 @@ 14.735 your search to those, you'd still be looking at over 40 hours to 14.736 find the changeset that introduced your bug.</para> 14.737 14.738 - <para>What the <command role="hg-cmd">hg bisect</command> command 14.739 + <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 14.740 does is use its knowledge of the <quote>shape</quote> of your 14.741 project's revision history to perform a search in time 14.742 proportional to the <emphasis>logarithm</emphasis> of the number 14.743 @@ -766,7 +766,7 @@ 14.744 Limit your search to the last hundred changesets, and it will 14.745 take only about an hour (roughly seven tests).</para> 14.746 14.747 - <para>The <command role="hg-cmd">hg bisect</command> command is 14.748 + <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 14.749 aware of the <quote>branchy</quote> nature of a Mercurial 14.750 project's revision history, so it has no problems dealing with 14.751 branches, merges, or multiple heads in a repository. It can 14.752 @@ -777,24 +777,24 @@ 14.753 <title>Using the <command role="hg-cmd">hg bisect</command> 14.754 command</title> 14.755 14.756 - <para>Here's an example of <command role="hg-cmd">hg 14.757 + <para id="x_132">Here's an example of <command role="hg-cmd">hg 14.758 bisect</command> in action.</para> 14.759 14.760 <note> 14.761 - <para> In versions 0.9.5 and earlier of Mercurial, <command 14.762 + <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 14.763 role="hg-cmd">hg bisect</command> was not a core command: 14.764 it was distributed with Mercurial as an extension. This 14.765 section describes the built-in command, not the old 14.766 extension.</para> 14.767 </note> 14.768 14.769 - <para>Now let's create a repository, so that we can try out the 14.770 + <para id="x_134">Now let's create a repository, so that we can try out the 14.771 <command role="hg-cmd">hg bisect</command> command in 14.772 isolation.</para> 14.773 14.774 &interaction.bisect.init; 14.775 14.776 - <para>We'll simulate a project that has a bug in it in a 14.777 + <para id="x_135">We'll simulate a project that has a bug in it in a 14.778 simple-minded way: create trivial changes in a loop, and 14.779 nominate one specific change that will have the 14.780 <quote>bug</quote>. This loop creates 35 changesets, each 14.781 @@ -804,44 +804,44 @@ 14.782 14.783 &interaction.bisect.commits; 14.784 14.785 - <para>The next thing that we'd like to do is figure out how to 14.786 + <para id="x_136">The next thing that we'd like to do is figure out how to 14.787 use the <command role="hg-cmd">hg bisect</command> command. 14.788 We can use Mercurial's normal built-in help mechanism for 14.789 this.</para> 14.790 14.791 &interaction.bisect.help; 14.792 14.793 - <para>The <command role="hg-cmd">hg bisect</command> command 14.794 + <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 14.795 works in steps. Each step proceeds as follows.</para> 14.796 <orderedlist> 14.797 - <listitem><para>You run your binary test.</para> 14.798 + <listitem><para id="x_138">You run your binary test.</para> 14.799 <itemizedlist> 14.800 - <listitem><para>If the test succeeded, you tell <command 14.801 + <listitem><para id="x_139">If the test succeeded, you tell <command 14.802 role="hg-cmd">hg bisect</command> by running the 14.803 <command role="hg-cmd">hg bisect good</command> 14.804 command.</para> 14.805 </listitem> 14.806 - <listitem><para>If it failed, run the <command 14.807 + <listitem><para id="x_13a">If it failed, run the <command 14.808 role="hg-cmd">hg bisect bad</command> 14.809 command.</para></listitem></itemizedlist> 14.810 </listitem> 14.811 - <listitem><para>The command uses your information to decide 14.812 + <listitem><para id="x_13b">The command uses your information to decide 14.813 which changeset to test next.</para> 14.814 </listitem> 14.815 - <listitem><para>It updates the working directory to that 14.816 + <listitem><para id="x_13c">It updates the working directory to that 14.817 changeset, and the process begins again.</para> 14.818 </listitem></orderedlist> 14.819 - <para>The process ends when <command role="hg-cmd">hg 14.820 + <para id="x_13d">The process ends when <command role="hg-cmd">hg 14.821 bisect</command> identifies a unique changeset that marks 14.822 the point where your test transitioned from 14.823 <quote>succeeding</quote> to <quote>failing</quote>.</para> 14.824 14.825 - <para>To start the search, we must run the <command 14.826 + <para id="x_13e">To start the search, we must run the <command 14.827 role="hg-cmd">hg bisect --reset</command> command.</para> 14.828 14.829 &interaction.bisect.search.init; 14.830 14.831 - <para>In our case, the binary test we use is simple: we check to 14.832 + <para id="x_13f">In our case, the binary test we use is simple: we check to 14.833 see if any file in the repository contains the string <quote>i 14.834 have a gub</quote>. If it does, this changeset contains the 14.835 change that <quote>caused the bug</quote>. By convention, a 14.836 @@ -849,14 +849,14 @@ 14.837 <quote>bad</quote>, while one that doesn't is 14.838 <quote>good</quote>.</para> 14.839 14.840 - <para>Most of the time, the revision to which the working 14.841 + <para id="x_140">Most of the time, the revision to which the working 14.842 directory is synced (usually the tip) already exhibits the 14.843 problem introduced by the buggy change, so we'll mark it as 14.844 <quote>bad</quote>.</para> 14.845 14.846 &interaction.bisect.search.bad-init; 14.847 14.848 - <para>Our next task is to nominate a changeset that we know 14.849 + <para id="x_141">Our next task is to nominate a changeset that we know 14.850 <emphasis>doesn't</emphasis> have the bug; the <command 14.851 role="hg-cmd">hg bisect</command> command will 14.852 <quote>bracket</quote> its search between the first pair of 14.853 @@ -866,38 +866,38 @@ 14.854 14.855 &interaction.bisect.search.good-init; 14.856 14.857 - <para>Notice that this command printed some output.</para> 14.858 + <para id="x_142">Notice that this command printed some output.</para> 14.859 <itemizedlist> 14.860 - <listitem><para>It told us how many changesets it must 14.861 + <listitem><para id="x_143">It told us how many changesets it must 14.862 consider before it can identify the one that introduced 14.863 the bug, and how many tests that will require.</para> 14.864 </listitem> 14.865 - <listitem><para>It updated the working directory to the next 14.866 + <listitem><para id="x_144">It updated the working directory to the next 14.867 changeset to test, and told us which changeset it's 14.868 testing.</para> 14.869 </listitem></itemizedlist> 14.870 14.871 - <para>We now run our test in the working directory. We use the 14.872 + <para id="x_145">We now run our test in the working directory. We use the 14.873 <command>grep</command> command to see if our 14.874 <quote>bad</quote> file is present in the working directory. 14.875 If it is, this revision is bad; if not, this revision is good. 14.876 &interaction.bisect.search.step1;</para> 14.877 14.878 - <para>This test looks like a perfect candidate for automation, 14.879 + <para id="x_146">This test looks like a perfect candidate for automation, 14.880 so let's turn it into a shell function.</para> 14.881 &interaction.bisect.search.mytest; 14.882 14.883 - <para>We can now run an entire test step with a single command, 14.884 + <para id="x_147">We can now run an entire test step with a single command, 14.885 <literal>mytest</literal>.</para> 14.886 14.887 &interaction.bisect.search.step2; 14.888 14.889 - <para>A few more invocations of our canned test step command, 14.890 + <para id="x_148">A few more invocations of our canned test step command, 14.891 and we're done.</para> 14.892 14.893 &interaction.bisect.search.rest; 14.894 14.895 - <para>Even though we had 40 changesets to search through, the 14.896 + <para id="x_149">Even though we had 40 changesets to search through, the 14.897 <command role="hg-cmd">hg bisect</command> command let us find 14.898 the changeset that introduced our <quote>bug</quote> with only 14.899 five tests. Because the number of tests that the <command 14.900 @@ -910,7 +910,7 @@ 14.901 <sect2> 14.902 <title>Cleaning up after your search</title> 14.903 14.904 - <para>When you're finished using the <command role="hg-cmd">hg 14.905 + <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 14.906 bisect</command> command in a repository, you can use the 14.907 <command role="hg-cmd">hg bisect reset</command> command to 14.908 drop the information it was using to drive your search. The 14.909 @@ -930,7 +930,7 @@ 14.910 <sect2> 14.911 <title>Give consistent input</title> 14.912 14.913 - <para>The <command role="hg-cmd">hg bisect</command> command 14.914 + <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 14.915 requires that you correctly report the result of every test 14.916 you perform. If you tell it that a test failed when it really 14.917 succeeded, it <emphasis>might</emphasis> be able to detect the 14.918 @@ -944,7 +944,7 @@ 14.919 <sect2> 14.920 <title>Automate as much as possible</title> 14.921 14.922 - <para>When I started using the <command role="hg-cmd">hg 14.923 + <para id="x_14c">When I started using the <command role="hg-cmd">hg 14.924 bisect</command> command, I tried a few times to run my 14.925 tests by hand, on the command line. This is an approach that 14.926 I, at least, am not suited to. After a few tries, I found 14.927 @@ -952,7 +952,7 @@ 14.928 my searches several times before finally getting correct 14.929 results.</para> 14.930 14.931 - <para>My initial problems with driving the <command 14.932 + <para id="x_14d">My initial problems with driving the <command 14.933 role="hg-cmd">hg bisect</command> command by hand occurred 14.934 even with simple searches on small repositories; if the 14.935 problem you're looking for is more subtle, or the number of 14.936 @@ -961,14 +961,14 @@ 14.937 the search is much higher. Once I started automating my 14.938 tests, I had much better results.</para> 14.939 14.940 - <para>The key to automated testing is twofold:</para> 14.941 + <para id="x_14e">The key to automated testing is twofold:</para> 14.942 <itemizedlist> 14.943 - <listitem><para>always test for the same symptom, and</para> 14.944 - </listitem> 14.945 - <listitem><para>always feed consistent input to the <command 14.946 + <listitem><para id="x_14f">always test for the same symptom, and</para> 14.947 + </listitem> 14.948 + <listitem><para id="x_150">always feed consistent input to the <command 14.949 role="hg-cmd">hg bisect</command> command.</para> 14.950 </listitem></itemizedlist> 14.951 - <para>In my tutorial example above, the <command>grep</command> 14.952 + <para id="x_151">In my tutorial example above, the <command>grep</command> 14.953 command tests for the symptom, and the <literal>if</literal> 14.954 statement takes the result of this check and ensures that we 14.955 always feed the same input to the <command role="hg-cmd">hg 14.956 @@ -980,21 +980,21 @@ 14.957 <sect2> 14.958 <title>Check your results</title> 14.959 14.960 - <para>Because the output of a <command role="hg-cmd">hg 14.961 + <para id="x_152">Because the output of a <command role="hg-cmd">hg 14.962 bisect</command> search is only as good as the input you 14.963 give it, don't take the changeset it reports as the absolute 14.964 truth. A simple way to cross-check its report is to manually 14.965 run your test at each of the following changesets:</para> 14.966 <itemizedlist> 14.967 - <listitem><para>The changeset that it reports as the first bad 14.968 + <listitem><para id="x_153">The changeset that it reports as the first bad 14.969 revision. Your test should still report this as 14.970 bad.</para> 14.971 </listitem> 14.972 - <listitem><para>The parent of that changeset (either parent, 14.973 + <listitem><para id="x_154">The parent of that changeset (either parent, 14.974 if it's a merge). Your test should report this changeset 14.975 as good.</para> 14.976 </listitem> 14.977 - <listitem><para>A child of that changeset. Your test should 14.978 + <listitem><para id="x_155">A child of that changeset. Your test should 14.979 report this changeset as bad.</para> 14.980 </listitem></itemizedlist> 14.981 14.982 @@ -1002,7 +1002,7 @@ 14.983 <sect2> 14.984 <title>Beware interference between bugs</title> 14.985 14.986 - <para>It's possible that your search for one bug could be 14.987 + <para id="x_156">It's possible that your search for one bug could be 14.988 disrupted by the presence of another. For example, let's say 14.989 your software crashes at revision 100, and worked correctly at 14.990 revision 50. Unknown to you, someone else introduced a 14.991 @@ -1010,7 +1010,7 @@ 14.992 revision 80. This could distort your results in one of 14.993 several ways.</para> 14.994 14.995 - <para>It is possible that this other bug completely 14.996 + <para id="x_157">It is possible that this other bug completely 14.997 <quote>masks</quote> yours, which is to say that it occurs 14.998 before your bug has a chance to manifest itself. If you can't 14.999 avoid that other bug (for example, it prevents your project 14.1000 @@ -1020,14 +1020,14 @@ 14.1001 you can mark a changeset as untested by running <command 14.1002 role="hg-cmd">hg bisect --skip</command>.</para> 14.1003 14.1004 - <para>A different problem could arise if your test for a bug's 14.1005 + <para id="x_158">A different problem could arise if your test for a bug's 14.1006 presence is not specific enough. If you check for <quote>my 14.1007 program crashes</quote>, then both your crashing bug and an 14.1008 unrelated crashing bug that masks it will look like the same 14.1009 thing, and mislead <command role="hg-cmd">hg 14.1010 bisect</command>.</para> 14.1011 14.1012 - <para>Another useful situation in which to use <command 14.1013 + <para id="x_159">Another useful situation in which to use <command 14.1014 role="hg-cmd">hg bisect --skip</command> is if you can't 14.1015 test a revision because your project was in a broken and hence 14.1016 untestable state at that revision, perhaps because someone 14.1017 @@ -1038,7 +1038,7 @@ 14.1018 <sect2> 14.1019 <title>Bracket your search lazily</title> 14.1020 14.1021 - <para>Choosing the first <quote>good</quote> and 14.1022 + <para id="x_15a">Choosing the first <quote>good</quote> and 14.1023 <quote>bad</quote> changesets that will mark the end points of 14.1024 your search is often easy, but it bears a little discussion 14.1025 nevertheless. From the perspective of <command 14.1026 @@ -1046,7 +1046,7 @@ 14.1027 changeset is conventionally <quote>bad</quote>, and the older 14.1028 changeset is <quote>good</quote>.</para> 14.1029 14.1030 - <para>If you're having trouble remembering when a suitable 14.1031 + <para id="x_15b">If you're having trouble remembering when a suitable 14.1032 <quote>good</quote> change was, so that you can tell <command 14.1033 role="hg-cmd">hg bisect</command>, you could do worse than 14.1034 testing changesets at random. Just remember to eliminate 14.1035 @@ -1055,7 +1055,7 @@ 14.1036 where another problem masks the bug (as I discussed 14.1037 above).</para> 14.1038 14.1039 - <para>Even if you end up <quote>early</quote> by thousands of 14.1040 + <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 14.1041 changesets or months of history, you will only add a handful 14.1042 of tests to the total number that <command role="hg-cmd">hg 14.1043 bisect</command> must perform, thanks to its logarithmic
15.1 --- a/en/ch09-hook.xml Thu Mar 19 20:54:12 2009 -0700 15.2 +++ b/en/ch09-hook.xml Thu Mar 19 21:18:52 2009 -0700 15.3 @@ -4,12 +4,12 @@ 15.4 <?dbhtml filename="handling-repository-events-with-hooks.html"?> 15.5 <title>Handling repository events with hooks</title> 15.6 15.7 - <para>Mercurial offers a powerful mechanism to let you perform 15.8 + <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform 15.9 automated actions in response to events that occur in a 15.10 repository. In some cases, you can even control Mercurial's 15.11 response to those events.</para> 15.12 15.13 - <para>The name Mercurial uses for one of these actions is a 15.14 + <para id="x_1e7">The name Mercurial uses for one of these actions is a 15.15 <emphasis>hook</emphasis>. Hooks are called 15.16 <quote>triggers</quote> in some revision control systems, but the 15.17 two names refer to the same idea.</para> 15.18 @@ -17,49 +17,49 @@ 15.19 <sect1> 15.20 <title>An overview of hooks in Mercurial</title> 15.21 15.22 - <para>Here is a brief list of the hooks that Mercurial supports. 15.23 + <para id="x_1e8">Here is a brief list of the hooks that Mercurial supports. 15.24 We will revisit each of these hooks in more detail later, in 15.25 section <xref linkend="sec:hook:ref"/>.</para> 15.26 15.27 <itemizedlist> 15.28 - <listitem><para><literal role="hook">changegroup</literal>: This 15.29 + <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This 15.30 is run after a group of changesets has been brought into the 15.31 repository from elsewhere.</para> 15.32 </listitem> 15.33 - <listitem><para><literal role="hook">commit</literal>: This is 15.34 + <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is 15.35 run after a new changeset has been created in the local 15.36 repository.</para> 15.37 </listitem> 15.38 - <listitem><para><literal role="hook">incoming</literal>: This is 15.39 + <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is 15.40 run once for each new changeset that is brought into the 15.41 repository from elsewhere. Notice the difference from 15.42 <literal role="hook">changegroup</literal>, which is run 15.43 once per <emphasis>group</emphasis> of changesets brought 15.44 in.</para> 15.45 </listitem> 15.46 - <listitem><para><literal role="hook">outgoing</literal>: This is 15.47 + <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is 15.48 run after a group of changesets has been transmitted from 15.49 this repository.</para> 15.50 </listitem> 15.51 - <listitem><para><literal role="hook">prechangegroup</literal>: 15.52 + <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: 15.53 This is run before starting to bring a group of changesets 15.54 into the repository. 15.55 </para> 15.56 </listitem> 15.57 - <listitem><para><literal role="hook">precommit</literal>: 15.58 + <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: 15.59 Controlling. This is run before starting a commit. 15.60 </para> 15.61 </listitem> 15.62 - <listitem><para><literal role="hook">preoutgoing</literal>: 15.63 + <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: 15.64 Controlling. This is run before starting to transmit a group 15.65 of changesets from this repository. 15.66 </para> 15.67 </listitem> 15.68 - <listitem><para><literal role="hook">pretag</literal>: 15.69 + <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: 15.70 Controlling. This is run before creating a tag. 15.71 </para> 15.72 </listitem> 15.73 - <listitem><para><literal 15.74 + <listitem><para id="x_1f1"><literal 15.75 role="hook">pretxnchangegroup</literal>: Controlling. This 15.76 is run after a group of changesets has been brought into the 15.77 local repository from another, but before the transaction 15.78 @@ -67,27 +67,27 @@ 15.79 repository. 15.80 </para> 15.81 </listitem> 15.82 - <listitem><para><literal role="hook">pretxncommit</literal>: 15.83 + <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: 15.84 Controlling. This is run after a new changeset has been 15.85 created in the local repository, but before the transaction 15.86 completes that will make it permanent. 15.87 </para> 15.88 </listitem> 15.89 - <listitem><para><literal role="hook">preupdate</literal>: 15.90 + <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: 15.91 Controlling. This is run before starting an update or merge 15.92 of the working directory. 15.93 </para> 15.94 </listitem> 15.95 - <listitem><para><literal role="hook">tag</literal>: This is run 15.96 + <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run 15.97 after a tag is created. 15.98 </para> 15.99 </listitem> 15.100 - <listitem><para><literal role="hook">update</literal>: This is 15.101 + <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is 15.102 run after an update or merge of the working directory has 15.103 finished. 15.104 </para> 15.105 </listitem></itemizedlist> 15.106 - <para>Each of the hooks whose description begins with the word 15.107 + <para id="x_1f6">Each of the hooks whose description begins with the word 15.108 <quote>Controlling</quote> has the ability to determine whether 15.109 an activity can proceed. If the hook succeeds, the activity may 15.110 proceed; if it fails, the activity is either not permitted or 15.111 @@ -101,7 +101,7 @@ 15.112 <sect2> 15.113 <title>Hooks are run with your privileges</title> 15.114 15.115 - <para>When you run a Mercurial command in a repository, and the 15.116 + <para id="x_1f7">When you run a Mercurial command in a repository, and the 15.117 command causes a hook to run, that hook runs on 15.118 <emphasis>your</emphasis> system, under 15.119 <emphasis>your</emphasis> user account, with 15.120 @@ -112,14 +112,14 @@ 15.121 it does. 15.122 </para> 15.123 15.124 - <para>In some cases, you may be exposed to hooks that you did 15.125 + <para id="x_1f8">In some cases, you may be exposed to hooks that you did 15.126 not install yourself. If you work with Mercurial on an 15.127 unfamiliar system, Mercurial will run hooks defined in that 15.128 system's global <filename role="special">~/.hgrc</filename> 15.129 file. 15.130 </para> 15.131 15.132 - <para>If you are working with a repository owned by another 15.133 + <para id="x_1f9">If you are working with a repository owned by another 15.134 user, Mercurial can run hooks defined in that user's 15.135 repository, but it will still run them as <quote>you</quote>. 15.136 For example, if you <command role="hg-cmd">hg pull</command> 15.137 @@ -131,7 +131,7 @@ 15.138 </para> 15.139 15.140 <note> 15.141 - <para> This only applies if you are pulling from a repository 15.142 + <para id="x_1fa"> This only applies if you are pulling from a repository 15.143 on a local or network filesystem. If you're pulling over 15.144 http or ssh, any <literal role="hook">outgoing</literal> 15.145 hook will run under whatever account is executing the server 15.146 @@ -139,7 +139,7 @@ 15.147 </para> 15.148 </note> 15.149 15.150 - <para>XXX To see what hooks are defined in a repository, use the 15.151 + <para id="x_1fb">XXX To see what hooks are defined in a repository, use the 15.152 <command role="hg-cmd">hg config hooks</command> command. If 15.153 you are working in one repository, but talking to another that 15.154 you do not own (e.g. using <command role="hg-cmd">hg 15.155 @@ -152,27 +152,27 @@ 15.156 <sect2> 15.157 <title>Hooks do not propagate</title> 15.158 15.159 - <para>In Mercurial, hooks are not revision controlled, and do 15.160 + <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do 15.161 not propagate when you clone, or pull from, a repository. The 15.162 reason for this is simple: a hook is a completely arbitrary 15.163 piece of executable code. It runs under your user identity, 15.164 with your privilege level, on your machine. 15.165 </para> 15.166 15.167 - <para>It would be extremely reckless for any distributed 15.168 + <para id="x_1fd">It would be extremely reckless for any distributed 15.169 revision control system to implement revision-controlled 15.170 hooks, as this would offer an easily exploitable way to 15.171 subvert the accounts of users of the revision control system. 15.172 </para> 15.173 15.174 - <para>Since Mercurial does not propagate hooks, if you are 15.175 + <para id="x_1fe">Since Mercurial does not propagate hooks, if you are 15.176 collaborating with other people on a common project, you 15.177 should not assume that they are using the same Mercurial hooks 15.178 as you are, or that theirs are correctly configured. You 15.179 should document the hooks you expect people to use. 15.180 </para> 15.181 15.182 - <para>In a corporate intranet, this is somewhat easier to 15.183 + <para id="x_1ff">In a corporate intranet, this is somewhat easier to 15.184 control, as you can for example provide a 15.185 <quote>standard</quote> installation of Mercurial on an NFS 15.186 filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 15.187 @@ -183,12 +183,12 @@ 15.188 <sect2> 15.189 <title>Hooks can be overridden</title> 15.190 15.191 - <para>Mercurial allows you to override a hook definition by 15.192 + <para id="x_200">Mercurial allows you to override a hook definition by 15.193 redefining the hook. You can disable it by setting its value 15.194 to the empty string, or change its behaviour as you wish. 15.195 </para> 15.196 15.197 - <para>If you deploy a system- or site-wide <filename 15.198 + <para id="x_201">If you deploy a system- or site-wide <filename 15.199 role="special">~/.hgrc</filename> file that defines some 15.200 hooks, you should thus understand that your users can disable 15.201 or override those hooks. 15.202 @@ -198,7 +198,7 @@ 15.203 <sect2> 15.204 <title>Ensuring that critical hooks are run</title> 15.205 15.206 - <para>Sometimes you may want to enforce a policy that you do not 15.207 + <para id="x_202">Sometimes you may want to enforce a policy that you do not 15.208 want others to be able to work around. For example, you may 15.209 have a requirement that every changeset must pass a rigorous 15.210 set of tests. Defining this requirement via a hook in a 15.211 @@ -207,13 +207,13 @@ 15.212 can subvert it at will by overriding the hook. 15.213 </para> 15.214 15.215 - <para>Instead, you can set up your policies for use of Mercurial 15.216 + <para id="x_203">Instead, you can set up your policies for use of Mercurial 15.217 so that people are expected to propagate changes through a 15.218 well-known <quote>canonical</quote> server that you have 15.219 locked down and configured appropriately. 15.220 </para> 15.221 15.222 - <para>One way to do this is via a combination of social 15.223 + <para id="x_204">One way to do this is via a combination of social 15.224 engineering and technology. Set up a restricted-access 15.225 account; users can push changes over the network to 15.226 repositories managed by this account, but they cannot log into 15.227 @@ -222,7 +222,7 @@ 15.228 they want. 15.229 </para> 15.230 15.231 - <para>When someone pushes a changeset to the server that 15.232 + <para id="x_205">When someone pushes a changeset to the server that 15.233 everyone pulls from, the server will test the changeset before 15.234 it accepts it as permanent, and reject it if it fails to pass 15.235 the test suite. If people only pull changes from this 15.236 @@ -236,19 +236,19 @@ 15.237 <title>Care with <literal>pretxn</literal> hooks in a 15.238 shared-access repository</title> 15.239 15.240 - <para>If you want to use hooks to do some automated work in a 15.241 + <para id="x_206">If you want to use hooks to do some automated work in a 15.242 repository that a number of people have shared access to, you 15.243 need to be careful in how you do this. 15.244 </para> 15.245 15.246 - <para>Mercurial only locks a repository when it is writing to the 15.247 + <para id="x_207">Mercurial only locks a repository when it is writing to the 15.248 repository, and only the parts of Mercurial that write to the 15.249 repository pay attention to locks. Write locks are necessary to 15.250 prevent multiple simultaneous writers from scribbling on each 15.251 other's work, corrupting the repository. 15.252 </para> 15.253 15.254 - <para>Because Mercurial is careful with the order in which it 15.255 + <para id="x_208">Because Mercurial is careful with the order in which it 15.256 reads and writes data, it does not need to acquire a lock when 15.257 it wants to read data from the repository. The parts of 15.258 Mercurial that read from the repository never pay attention to 15.259 @@ -256,14 +256,14 @@ 15.260 performance and concurrency. 15.261 </para> 15.262 15.263 - <para>With great performance comes a trade-off, though, one which 15.264 + <para id="x_209">With great performance comes a trade-off, though, one which 15.265 has the potential to cause you trouble unless you're aware of 15.266 it. To describe this requires a little detail about how 15.267 Mercurial adds changesets to a repository and reads those 15.268 changes. 15.269 </para> 15.270 15.271 - <para>When Mercurial <emphasis>writes</emphasis> metadata, it 15.272 + <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it 15.273 writes it straight into the destination file. It writes file 15.274 data first, then manifest data (which contains pointers to the 15.275 new file data), then changelog data (which contains pointers to 15.276 @@ -274,13 +274,13 @@ 15.277 before the transaction began. 15.278 </para> 15.279 15.280 - <para>When Mercurial <emphasis>reads</emphasis> metadata, it reads 15.281 + <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads 15.282 the changelog first, then everything else. Since a reader will 15.283 only access parts of the manifest or file metadata that it can 15.284 see in the changelog, it can never see partially written data. 15.285 </para> 15.286 15.287 - <para>Some controlling hooks (<literal 15.288 + <para id="x_20c">Some controlling hooks (<literal 15.289 role="hook">pretxncommit</literal> and <literal 15.290 role="hook">pretxnchangegroup</literal>) run when a 15.291 transaction is almost complete. All of the metadata has been 15.292 @@ -288,7 +288,7 @@ 15.293 cause the newly-written data to disappear. 15.294 </para> 15.295 15.296 - <para>If one of these hooks runs for long, it opens a window of 15.297 + <para id="x_20d">If one of these hooks runs for long, it opens a window of 15.298 time during which a reader can see the metadata for changesets 15.299 that are not yet permanent, and should not be thought of as 15.300 <quote>really there</quote>. The longer the hook runs, the 15.301 @@ -298,7 +298,7 @@ 15.302 <sect2> 15.303 <title>The problem illustrated</title> 15.304 15.305 - <para>In principle, a good use for the <literal 15.306 + <para id="x_20e">In principle, a good use for the <literal 15.307 role="hook">pretxnchangegroup</literal> hook would be to 15.308 automatically build and test incoming changes before they are 15.309 accepted into a central repository. This could let you 15.310 @@ -309,7 +309,7 @@ 15.311 potentially breaking their build. 15.312 </para> 15.313 15.314 - <para>The safest technological answer to this challenge is to 15.315 + <para id="x_20f">The safest technological answer to this challenge is to 15.316 set up such a <quote>gatekeeper</quote> repository as 15.317 <emphasis>unidirectional</emphasis>. Let it take changes 15.318 pushed in from the outside, but do not allow anyone to pull 15.319 @@ -321,7 +321,7 @@ 15.320 <emphasis>can</emphasis> pull from. 15.321 </para> 15.322 15.323 - <para>In practice, putting a centralised bottleneck like this in 15.324 + <para id="x_210">In practice, putting a centralised bottleneck like this in 15.325 place is not often a good idea, and transaction visibility has 15.326 nothing to do with the problem. As the size of a 15.327 project&emdash;and the time it takes to build and 15.328 @@ -332,7 +332,7 @@ 15.329 involved. 15.330 </para> 15.331 15.332 - <para>An approach that scales better is to get people to build 15.333 + <para id="x_211">An approach that scales better is to get people to build 15.334 and test before they push, then run automated builds and tests 15.335 centrally <emphasis>after</emphasis> a push, to be sure all is 15.336 well. The advantage of this approach is that it does not 15.337 @@ -345,18 +345,18 @@ 15.338 <sect1 id="sec:hook:simple"> 15.339 <title>A short tutorial on using hooks</title> 15.340 15.341 - <para>It is easy to write a Mercurial hook. Let's start with a 15.342 + <para id="x_212">It is easy to write a Mercurial hook. Let's start with a 15.343 hook that runs when you finish a <command role="hg-cmd">hg 15.344 commit</command>, and simply prints the hash of the changeset 15.345 you just created. The hook is called <literal 15.346 role="hook">commit</literal>. 15.347 </para> 15.348 15.349 - <para>All hooks follow the pattern in this example.</para> 15.350 + <para id="x_213">All hooks follow the pattern in this example.</para> 15.351 15.352 &interaction.hook.simple.init; 15.353 15.354 - <para>You add an entry to the <literal 15.355 + <para id="x_214">You add an entry to the <literal 15.356 role="rc-hooks">hooks</literal> section of your <filename 15.357 role="special">~/.hgrc</filename>. On the left is the name of 15.358 the event to trigger on; on the right is the action to take. As 15.359 @@ -368,12 +368,12 @@ 15.360 <sect2> 15.361 <title>Performing multiple actions per event</title> 15.362 15.363 - <para>Quite often, you will want to define more than one hook 15.364 + <para id="x_215">Quite often, you will want to define more than one hook 15.365 for a particular kind of event, as shown below.</para> 15.366 15.367 &interaction.hook.simple.ext; 15.368 15.369 - <para>Mercurial lets you do this by adding an 15.370 + <para id="x_216">Mercurial lets you do this by adding an 15.371 <emphasis>extension</emphasis> to the end of a hook's name. 15.372 You extend a hook's name by giving the name of the hook, 15.373 followed by a full stop (the 15.374 @@ -384,7 +384,7 @@ 15.375 <literal>commit</literal> event occurs. 15.376 </para> 15.377 15.378 - <para>To give a well-defined order of execution when there are 15.379 + <para id="x_217">To give a well-defined order of execution when there are 15.380 multiple hooks defined for an event, Mercurial sorts hooks by 15.381 extension, and executes the hook commands in this sorted 15.382 order. In the above example, it will execute 15.383 @@ -393,7 +393,7 @@ 15.384 before both. 15.385 </para> 15.386 15.387 - <para>It is a good idea to use a somewhat descriptive extension 15.388 + <para id="x_218">It is a good idea to use a somewhat descriptive extension 15.389 when you define a new hook. This will help you to remember 15.390 what the hook was for. If the hook fails, you'll get an error 15.391 message that contains the hook name and extension, so using a 15.392 @@ -406,20 +406,20 @@ 15.393 <sect2 id="sec:hook:perm"> 15.394 <title>Controlling whether an activity can proceed</title> 15.395 15.396 - <para>In our earlier examples, we used the <literal 15.397 + <para id="x_219">In our earlier examples, we used the <literal 15.398 role="hook">commit</literal> hook, which is run after a 15.399 commit has completed. This is one of several Mercurial hooks 15.400 that run after an activity finishes. Such hooks have no way 15.401 of influencing the activity itself. 15.402 </para> 15.403 15.404 - <para>Mercurial defines a number of events that occur before an 15.405 + <para id="x_21a">Mercurial defines a number of events that occur before an 15.406 activity starts; or after it starts, but before it finishes. 15.407 Hooks that trigger on these events have the added ability to 15.408 choose whether the activity can continue, or will abort. 15.409 </para> 15.410 15.411 - <para>The <literal role="hook">pretxncommit</literal> hook runs 15.412 + <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs 15.413 after a commit has all but completed. In other words, the 15.414 metadata representing the changeset has been written out to 15.415 disk, but the transaction has not yet been allowed to 15.416 @@ -428,7 +428,7 @@ 15.417 complete, or must be rolled back. 15.418 </para> 15.419 15.420 - <para>If the <literal role="hook">pretxncommit</literal> hook 15.421 + <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook 15.422 exits with a status code of zero, the transaction is allowed 15.423 to complete; the commit finishes; and the <literal 15.424 role="hook">commit</literal> hook is run. If the <literal 15.425 @@ -440,7 +440,7 @@ 15.426 15.427 &interaction.hook.simple.pretxncommit; 15.428 15.429 - <para>The hook in the example above checks that a commit comment 15.430 + <para id="x_21d">The hook in the example above checks that a commit comment 15.431 contains a bug ID. If it does, the commit can complete. If 15.432 not, the commit is rolled back. 15.433 </para> 15.434 @@ -450,7 +450,7 @@ 15.435 <sect1> 15.436 <title>Writing your own hooks</title> 15.437 15.438 - <para>When you are writing a hook, you might find it useful to run 15.439 + <para id="x_21e">When you are writing a hook, you might find it useful to run 15.440 Mercurial either with the <option 15.441 role="hg-opt-global">-v</option> option, or the <envar 15.442 role="rc-item-ui">verbose</envar> config item set to 15.443 @@ -461,19 +461,19 @@ 15.444 <sect2 id="sec:hook:lang"> 15.445 <title>Choosing how your hook should run</title> 15.446 15.447 - <para>You can write a hook either as a normal 15.448 + <para id="x_21f">You can write a hook either as a normal 15.449 program&emdash;typically a shell script&emdash;or as a Python 15.450 function that is executed within the Mercurial process. 15.451 </para> 15.452 15.453 - <para>Writing a hook as an external program has the advantage 15.454 + <para id="x_220">Writing a hook as an external program has the advantage 15.455 that it requires no knowledge of Mercurial's internals. You 15.456 can call normal Mercurial commands to get any added 15.457 information you need. The trade-off is that external hooks 15.458 are slower than in-process hooks. 15.459 </para> 15.460 15.461 - <para>An in-process Python hook has complete access to the 15.462 + <para id="x_221">An in-process Python hook has complete access to the 15.463 Mercurial API, and does not <quote>shell out</quote> to 15.464 another process, so it is inherently faster than an external 15.465 hook. It is also easier to obtain much of the information 15.466 @@ -481,7 +481,7 @@ 15.467 running Mercurial commands. 15.468 </para> 15.469 15.470 - <para>If you are comfortable with Python, or require high 15.471 + <para id="x_222">If you are comfortable with Python, or require high 15.472 performance, writing your hooks in Python may be a good 15.473 choice. However, when you have a straightforward hook to 15.474 write and you don't need to care about performance (probably 15.475 @@ -492,13 +492,13 @@ 15.476 <sect2 id="sec:hook:param"> 15.477 <title>Hook parameters</title> 15.478 15.479 - <para>Mercurial calls each hook with a set of well-defined 15.480 + <para id="x_223">Mercurial calls each hook with a set of well-defined 15.481 parameters. In Python, a parameter is passed as a keyword 15.482 argument to your hook function. For an external program, a 15.483 parameter is passed as an environment variable. 15.484 </para> 15.485 15.486 - <para>Whether your hook is written in Python or as a shell 15.487 + <para id="x_224">Whether your hook is written in Python or as a shell 15.488 script, the hook-specific parameter names and values will be 15.489 the same. A boolean parameter will be represented as a 15.490 boolean value in Python, but as the number 1 (for 15.491 @@ -514,7 +514,7 @@ 15.492 <sect2> 15.493 <title>Hook return values and activity control</title> 15.494 15.495 - <para>A hook that executes successfully must exit with a status 15.496 + <para id="x_225">A hook that executes successfully must exit with a status 15.497 of zero if external, or return boolean <quote>false</quote> if 15.498 in-process. Failure is indicated with a non-zero exit status 15.499 from an external hook, or an in-process hook returning boolean 15.500 @@ -522,7 +522,7 @@ 15.501 exception, the hook is considered to have failed. 15.502 </para> 15.503 15.504 - <para>For a hook that controls whether an activity can proceed, 15.505 + <para id="x_226">For a hook that controls whether an activity can proceed, 15.506 zero/false means <quote>allow</quote>, while 15.507 non-zero/true/exception means <quote>deny</quote>. 15.508 </para> 15.509 @@ -531,23 +531,23 @@ 15.510 <sect2> 15.511 <title>Writing an external hook</title> 15.512 15.513 - <para>When you define an external hook in your <filename 15.514 + <para id="x_227">When you define an external hook in your <filename 15.515 role="special">~/.hgrc</filename> and the hook is run, its 15.516 value is passed to your shell, which interprets it. This 15.517 means that you can use normal shell constructs in the body of 15.518 the hook. 15.519 </para> 15.520 15.521 - <para>An executable hook is always run with its current 15.522 + <para id="x_228">An executable hook is always run with its current 15.523 directory set to a repository's root directory. 15.524 </para> 15.525 15.526 - <para>Each hook parameter is passed in as an environment 15.527 + <para id="x_229">Each hook parameter is passed in as an environment 15.528 variable; the name is upper-cased, and prefixed with the 15.529 string <quote><literal>HG_</literal></quote>. 15.530 </para> 15.531 15.532 - <para>With the exception of hook parameters, Mercurial does not 15.533 + <para id="x_22a">With the exception of hook parameters, Mercurial does not 15.534 set or modify any environment variables when running a hook. 15.535 This is useful to remember if you are writing a site-wide hook 15.536 that may be run by a number of different users with differing 15.537 @@ -560,7 +560,7 @@ 15.538 <sect2> 15.539 <title>Telling Mercurial to use an in-process hook</title> 15.540 15.541 - <para>The <filename role="special">~/.hgrc</filename> syntax 15.542 + <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax 15.543 for defining an in-process hook is slightly different than for 15.544 an executable hook. The value of the hook must start with the 15.545 text <quote><literal>python:</literal></quote>, and continue 15.546 @@ -568,19 +568,19 @@ 15.547 the hook's value. 15.548 </para> 15.549 15.550 - <para>The module in which a hook lives is automatically imported 15.551 + <para id="x_22c">The module in which a hook lives is automatically imported 15.552 when a hook is run. So long as you have the module name and 15.553 <envar>PYTHONPATH</envar> right, it should <quote>just 15.554 work</quote>. 15.555 </para> 15.556 15.557 - <para>The following <filename role="special">~/.hgrc</filename> 15.558 + <para id="x_22d">The following <filename role="special">~/.hgrc</filename> 15.559 example snippet illustrates the syntax and meaning of the 15.560 notions we just described. 15.561 </para> 15.562 <programlisting>[hooks] 15.563 commit.example = python:mymodule.submodule.myhook</programlisting> 15.564 - <para>When Mercurial runs the <literal>commit.example</literal> 15.565 + <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> 15.566 hook, it imports <literal>mymodule.submodule</literal>, looks 15.567 for the callable object named <literal>myhook</literal>, and 15.568 calls it. 15.569 @@ -590,12 +590,12 @@ 15.570 <sect2> 15.571 <title>Writing an in-process hook</title> 15.572 15.573 - <para>The simplest in-process hook does nothing, but illustrates 15.574 + <para id="x_22f">The simplest in-process hook does nothing, but illustrates 15.575 the basic shape of the hook API: 15.576 </para> 15.577 <programlisting>def myhook(ui, repo, **kwargs): 15.578 pass</programlisting> 15.579 - <para>The first argument to a Python hook is always a <literal 15.580 + <para id="x_230">The first argument to a Python hook is always a <literal 15.581 role="py-mod-mercurial.ui">ui</literal> object. The second 15.582 is a repository object; at the moment, it is always an 15.583 instance of <literal 15.584 @@ -615,7 +615,7 @@ 15.585 <sect2> 15.586 <title>Writing meaningful commit messages</title> 15.587 15.588 - <para>It's hard to imagine a useful commit message being very 15.589 + <para id="x_231">It's hard to imagine a useful commit message being very 15.590 short. The simple <literal role="hook">pretxncommit</literal> 15.591 hook of the example below will prevent you from committing a 15.592 changeset with a message that is less than ten bytes long. 15.593 @@ -627,7 +627,7 @@ 15.594 <sect2> 15.595 <title>Checking for trailing whitespace</title> 15.596 15.597 - <para>An interesting use of a commit-related hook is to help you 15.598 + <para id="x_232">An interesting use of a commit-related hook is to help you 15.599 to write cleaner code. A simple example of <quote>cleaner 15.600 code</quote> is the dictum that a change should not add any 15.601 new lines of text that contain <quote>trailing 15.602 @@ -638,7 +638,7 @@ 15.603 prefer to get rid of it. 15.604 </para> 15.605 15.606 - <para>You can use either the <literal 15.607 + <para id="x_233">You can use either the <literal 15.608 role="hook">precommit</literal> or <literal 15.609 role="hook">pretxncommit</literal> hook to tell whether you 15.610 have a trailing whitespace problem. If you use the <literal 15.611 @@ -654,7 +654,7 @@ 15.612 seem right. 15.613 </para> 15.614 15.615 - <para>Should you choose the <literal 15.616 + <para id="x_234">Should you choose the <literal 15.617 role="hook">pretxncommit</literal> hook, the check won't 15.618 occur until just before the transaction for the commit 15.619 completes. This will allow you to check for problems only the 15.620 @@ -667,7 +667,7 @@ 15.621 15.622 &interaction.hook.ws.simple; 15.623 15.624 - <para>In this example, we introduce a simple <literal 15.625 + <para id="x_235">In this example, we introduce a simple <literal 15.626 role="hook">pretxncommit</literal> hook that checks for 15.627 trailing whitespace. This hook is short, but not very 15.628 helpful. It exits with an error status if a change adds a 15.629 @@ -678,7 +678,7 @@ 15.630 trailing whitespace cause problems. 15.631 </para> 15.632 15.633 - <para>The above version is much more complex, but also more 15.634 + <para id="x_236">The above version is much more complex, but also more 15.635 useful. It parses a unified diff to see if any lines add 15.636 trailing whitespace, and prints the name of the file and the 15.637 line number of each such occurrence. Even better, if the 15.638 @@ -692,7 +692,7 @@ 15.639 15.640 &interaction.hook.ws.better; 15.641 15.642 - <para>As a final aside, note in the example above the use of 15.643 + <para id="x_237">As a final aside, note in the example above the use of 15.644 <command>perl</command>'s in-place editing feature to get rid 15.645 of trailing whitespace from a file. This is concise and 15.646 useful enough that I will reproduce it here. 15.647 @@ -704,7 +704,7 @@ 15.648 <sect1> 15.649 <title>Bundled hooks</title> 15.650 15.651 - <para>Mercurial ships with several bundled hooks. You can find 15.652 + <para id="x_238">Mercurial ships with several bundled hooks. You can find 15.653 them in the <filename class="directory">hgext</filename> 15.654 directory of a Mercurial source tree. If you are using a 15.655 Mercurial binary package, the hooks will be located in the 15.656 @@ -716,7 +716,7 @@ 15.657 <title><literal role="hg-ext">acl</literal>&emdash;access 15.658 control for parts of a repository</title> 15.659 15.660 - <para>The <literal role="hg-ext">acl</literal> extension lets 15.661 + <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets 15.662 you control which remote users are allowed to push changesets 15.663 to a networked server. You can protect any portion of a 15.664 repository (including the entire repo), so that a specific 15.665 @@ -724,7 +724,7 @@ 15.666 portion. 15.667 </para> 15.668 15.669 - <para>This extension implements access control based on the 15.670 + <para id="x_23a">This extension implements access control based on the 15.671 identity of the user performing a push, 15.672 <emphasis>not</emphasis> on who committed the changesets 15.673 they're pushing. It makes sense to use this hook only if you 15.674 @@ -737,7 +737,7 @@ 15.675 <title>Configuring the <literal role="hook">acl</literal> 15.676 hook</title> 15.677 15.678 - <para>In order to manage incoming changesets, the <literal 15.679 + <para id="x_23b">In order to manage incoming changesets, the <literal 15.680 role="hg-ext">acl</literal> hook must be used as a 15.681 <literal role="hook">pretxnchangegroup</literal> hook. This 15.682 lets it see which files are modified by each incoming 15.683 @@ -747,18 +747,18 @@ 15.684 <programlisting>[hooks] 15.685 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> 15.686 15.687 - <para>The <literal role="hg-ext">acl</literal> extension is 15.688 + <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is 15.689 configured using three sections. 15.690 </para> 15.691 15.692 - <para>The <literal role="rc-acl">acl</literal> section has 15.693 + <para id="x_23d">The <literal role="rc-acl">acl</literal> section has 15.694 only one entry, <envar role="rc-item-acl">sources</envar>, 15.695 which lists the sources of incoming changesets that the hook 15.696 should pay attention to. You don't normally need to 15.697 configure this section. 15.698 </para> 15.699 <itemizedlist> 15.700 - <listitem><para><envar role="rc-item-acl">serve</envar>: 15.701 + <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: 15.702 Control incoming changesets that are arriving from a 15.703 remote repository over http or ssh. This is the default 15.704 value of <envar role="rc-item-acl">sources</envar>, and 15.705 @@ -766,23 +766,23 @@ 15.706 configuration item. 15.707 </para> 15.708 </listitem> 15.709 - <listitem><para><envar role="rc-item-acl">pull</envar>: 15.710 + <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: 15.711 Control incoming changesets that are arriving via a pull 15.712 from a local repository. 15.713 </para> 15.714 </listitem> 15.715 - <listitem><para><envar role="rc-item-acl">push</envar>: 15.716 + <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: 15.717 Control incoming changesets that are arriving via a push 15.718 from a local repository. 15.719 </para> 15.720 </listitem> 15.721 - <listitem><para><envar role="rc-item-acl">bundle</envar>: 15.722 + <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: 15.723 Control incoming changesets that are arriving from 15.724 another repository via a bundle. 15.725 </para> 15.726 </listitem></itemizedlist> 15.727 15.728 - <para>The <literal role="rc-acl.allow">acl.allow</literal> 15.729 + <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> 15.730 section controls the users that are allowed to add 15.731 changesets to the repository. If this section is not 15.732 present, all users that are not explicitly denied are 15.733 @@ -791,13 +791,13 @@ 15.734 that all users are denied). 15.735 </para> 15.736 15.737 - <para>The <literal role="rc-acl.deny">acl.deny</literal> 15.738 + <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> 15.739 section determines which users are denied from adding 15.740 changesets to the repository. If this section is not 15.741 present or is empty, no users are denied. 15.742 </para> 15.743 15.744 - <para>The syntaxes for the <literal 15.745 + <para id="x_244">The syntaxes for the <literal 15.746 role="rc-acl.allow">acl.allow</literal> and <literal 15.747 role="rc-acl.deny">acl.deny</literal> sections are 15.748 identical. On the left of each entry is a glob pattern that 15.749 @@ -805,7 +805,7 @@ 15.750 repository; on the right, a user name. 15.751 </para> 15.752 15.753 - <para>In the following example, the user 15.754 + <para id="x_245">In the following example, the user 15.755 <literal>docwriter</literal> can only push changes to the 15.756 <filename class="directory">docs</filename> subtree of the 15.757 repository, while <literal>intern</literal> can push changes 15.758 @@ -821,7 +821,7 @@ 15.759 <sect3> 15.760 <title>Testing and troubleshooting</title> 15.761 15.762 - <para>If you want to test the <literal 15.763 + <para id="x_246">If you want to test the <literal 15.764 role="hg-ext">acl</literal> hook, run it with Mercurial's 15.765 debugging output enabled. Since you'll probably be running 15.766 it on a server where it's not convenient (or sometimes 15.767 @@ -832,7 +832,7 @@ 15.768 </para> 15.769 <programlisting>[ui] 15.770 debug = true</programlisting> 15.771 - <para>With this enabled, the <literal 15.772 + <para id="x_247">With this enabled, the <literal 15.773 role="hg-ext">acl</literal> hook will print enough 15.774 information to let you figure out why it is allowing or 15.775 forbidding pushes from specific users. 15.776 @@ -845,14 +845,14 @@ 15.777 role="hg-ext">bugzilla</literal>&emdash;integration with 15.778 Bugzilla</title> 15.779 15.780 - <para>The <literal role="hg-ext">bugzilla</literal> extension 15.781 + <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension 15.782 adds a comment to a Bugzilla bug whenever it finds a reference 15.783 to that bug ID in a commit comment. You can install this hook 15.784 on a shared server, so that any time a remote user pushes 15.785 changes to this server, the hook gets run. 15.786 </para> 15.787 15.788 - <para>It adds a comment to the bug that looks like this (you can 15.789 + <para id="x_249">It adds a comment to the bug that looks like this (you can 15.790 configure the contents of the comment&emdash;see below): 15.791 </para> 15.792 <programlisting>Changeset aad8b264143a, made by Joe User 15.793 @@ -861,19 +861,19 @@ 15.794 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 15.795 Changeset description: Fix bug 10483 by guarding against some 15.796 NULL pointers</programlisting> 15.797 - <para>The value of this hook is that it automates the process of 15.798 + <para id="x_24a">The value of this hook is that it automates the process of 15.799 updating a bug any time a changeset refers to it. If you 15.800 configure the hook properly, it makes it easy for people to 15.801 browse straight from a Bugzilla bug to a changeset that refers 15.802 to that bug. 15.803 </para> 15.804 15.805 - <para>You can use the code in this hook as a starting point for 15.806 + <para id="x_24b">You can use the code in this hook as a starting point for 15.807 some more exotic Bugzilla integration recipes. Here are a few 15.808 possibilities: 15.809 </para> 15.810 <itemizedlist> 15.811 - <listitem><para>Require that every changeset pushed to the 15.812 + <listitem><para id="x_24c">Require that every changeset pushed to the 15.813 server have a valid bug ID in its commit comment. In this 15.814 case, you'd want to configure the hook as a <literal 15.815 role="hook">pretxncommit</literal> hook. This would 15.816 @@ -881,7 +881,7 @@ 15.817 IDs. 15.818 </para> 15.819 </listitem> 15.820 - <listitem><para>Allow incoming changesets to automatically 15.821 + <listitem><para id="x_24d">Allow incoming changesets to automatically 15.822 modify the <emphasis>state</emphasis> of a bug, as well as 15.823 simply adding a comment. For example, the hook could 15.824 recognise the string <quote>fixed bug 31337</quote> as 15.825 @@ -894,7 +894,7 @@ 15.826 <title>Configuring the <literal role="hook">bugzilla</literal> 15.827 hook</title> 15.828 15.829 - <para>You should configure this hook in your server's 15.830 + <para id="x_24e">You should configure this hook in your server's 15.831 <filename role="special">~/.hgrc</filename> as an <literal 15.832 role="hook">incoming</literal> hook, for example as 15.833 follows: 15.834 @@ -902,25 +902,25 @@ 15.835 <programlisting>[hooks] 15.836 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> 15.837 15.838 - <para>Because of the specialised nature of this hook, and 15.839 + <para id="x_24f">Because of the specialised nature of this hook, and 15.840 because Bugzilla was not written with this kind of 15.841 integration in mind, configuring this hook is a somewhat 15.842 involved process. 15.843 </para> 15.844 15.845 - <para>Before you begin, you must install the MySQL bindings 15.846 + <para id="x_250">Before you begin, you must install the MySQL bindings 15.847 for Python on the host(s) where you'll be running the hook. 15.848 If this is not available as a binary package for your 15.849 system, you can download it from 15.850 <citation>web:mysql-python</citation>. 15.851 </para> 15.852 15.853 - <para>Configuration information for this hook lives in the 15.854 + <para id="x_251">Configuration information for this hook lives in the 15.855 <literal role="rc-bugzilla">bugzilla</literal> section of 15.856 your <filename role="special">~/.hgrc</filename>. 15.857 </para> 15.858 <itemizedlist> 15.859 - <listitem><para><envar 15.860 + <listitem><para id="x_252"><envar 15.861 role="rc-item-bugzilla">version</envar>: The version 15.862 of Bugzilla installed on the server. The database 15.863 schema that Bugzilla uses changes occasionally, so this 15.864 @@ -929,14 +929,14 @@ 15.865 <literal>2.16</literal>. 15.866 </para> 15.867 </listitem> 15.868 - <listitem><para><envar role="rc-item-bugzilla">host</envar>: 15.869 + <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: 15.870 The hostname of the MySQL server that stores your 15.871 Bugzilla data. The database must be configured to allow 15.872 connections from whatever host you are running the 15.873 <literal role="hook">bugzilla</literal> hook on. 15.874 </para> 15.875 </listitem> 15.876 - <listitem><para><envar role="rc-item-bugzilla">user</envar>: 15.877 + <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: 15.878 The username with which to connect to the MySQL server. 15.879 The database must be configured to allow this user to 15.880 connect from whatever host you are running the <literal 15.881 @@ -947,7 +947,7 @@ 15.882 MySQL database. 15.883 </para> 15.884 </listitem> 15.885 - <listitem><para><envar 15.886 + <listitem><para id="x_255"><envar 15.887 role="rc-item-bugzilla">password</envar>: The MySQL 15.888 password for the user you configured above. This is 15.889 stored as plain text, so you should make sure that 15.890 @@ -956,14 +956,14 @@ 15.891 store this information. 15.892 </para> 15.893 </listitem> 15.894 - <listitem><para><envar role="rc-item-bugzilla">db</envar>: 15.895 + <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: 15.896 The name of the Bugzilla database on the MySQL server. 15.897 The default value of this item is 15.898 <literal>bugs</literal>, which is the standard name of 15.899 the MySQL database where Bugzilla stores its data. 15.900 </para> 15.901 </listitem> 15.902 - <listitem><para><envar 15.903 + <listitem><para id="x_257"><envar 15.904 role="rc-item-bugzilla">notify</envar>: If you want 15.905 Bugzilla to send out a notification email to subscribers 15.906 after this hook has added a comment to a bug, you will 15.907 @@ -976,7 +976,7 @@ 15.908 <programlisting>cd /var/www/html/bugzilla && 15.909 ./processmail %s nobody@nowhere.com</programlisting> 15.910 </listitem> 15.911 - <listitem><para> The Bugzilla 15.912 + <listitem><para id="x_258"> The Bugzilla 15.913 <literal>processmail</literal> program expects to be 15.914 given a bug ID (the hook replaces 15.915 <quote><literal>%s</literal></quote> with the bug ID) 15.916 @@ -993,7 +993,7 @@ 15.917 <sect3> 15.918 <title>Mapping committer names to Bugzilla user names</title> 15.919 15.920 - <para>By default, the <literal 15.921 + <para id="x_259">By default, the <literal 15.922 role="hg-ext">bugzilla</literal> hook tries to use the 15.923 email address of a changeset's committer as the Bugzilla 15.924 user name with which to update a bug. If this does not suit 15.925 @@ -1002,14 +1002,14 @@ 15.926 role="rc-usermap">usermap</literal> section. 15.927 </para> 15.928 15.929 - <para>Each item in the <literal 15.930 + <para id="x_25a">Each item in the <literal 15.931 role="rc-usermap">usermap</literal> section contains an 15.932 email address on the left, and a Bugzilla user name on the 15.933 right. 15.934 </para> 15.935 <programlisting>[usermap] 15.936 jane.user@example.com = jane</programlisting> 15.937 - <para>You can either keep the <literal 15.938 + <para id="x_25b">You can either keep the <literal 15.939 role="rc-usermap">usermap</literal> data in a normal 15.940 <filename role="special">~/.hgrc</filename>, or tell the 15.941 <literal role="hg-ext">bugzilla</literal> hook to read the 15.942 @@ -1025,7 +1025,7 @@ 15.943 <programlisting># regular hgrc file refers to external usermap file 15.944 [bugzilla] 15.945 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 15.946 - <para>While the <filename>usermap</filename> file that it 15.947 + <para id="x_25c">While the <filename>usermap</filename> file that it 15.948 refers to might look like this: 15.949 </para> 15.950 <programlisting># bugzilla-usermap.conf - inside a hg repository 15.951 @@ -1035,14 +1035,14 @@ 15.952 <sect3> 15.953 <title>Configuring the text that gets added to a bug</title> 15.954 15.955 - <para>You can configure the text that this hook adds as a 15.956 + <para id="x_25d">You can configure the text that this hook adds as a 15.957 comment; you specify it in the form of a Mercurial template. 15.958 Several <filename role="special">~/.hgrc</filename> entries 15.959 (still in the <literal role="rc-bugzilla">bugzilla</literal> 15.960 section) control this behaviour. 15.961 </para> 15.962 <itemizedlist> 15.963 - <listitem><para><literal>strip</literal>: The number of 15.964 + <listitem><para id="x_25e"><literal>strip</literal>: The number of 15.965 leading path elements to strip from a repository's path 15.966 name to construct a partial path for a URL. For example, 15.967 if the repositories on your server live under <filename 15.968 @@ -1056,7 +1056,7 @@ 15.969 expanding a template, as <literal>webroot</literal>. 15.970 </para> 15.971 </listitem> 15.972 - <listitem><para><literal>template</literal>: The text of the 15.973 + <listitem><para id="x_25f"><literal>template</literal>: The text of the 15.974 template to use. In addition to the usual 15.975 changeset-related variables, this template can use 15.976 <literal>hgweb</literal> (the value of the 15.977 @@ -1066,7 +1066,7 @@ 15.978 </para> 15.979 </listitem></itemizedlist> 15.980 15.981 - <para>In addition, you can add a <envar 15.982 + <para id="x_260">In addition, you can add a <envar 15.983 role="rc-item-web">baseurl</envar> item to the <literal 15.984 role="rc-web">web</literal> section of your <filename 15.985 role="special">~/.hgrc</filename>. The <literal 15.986 @@ -1078,7 +1078,7 @@ 15.987 <programlisting>[web] 15.988 baseurl = http://hg.domain.com/</programlisting> 15.989 15.990 - <para>Here is an example set of <literal 15.991 + <para id="x_261">Here is an example set of <literal 15.992 role="hg-ext">bugzilla</literal> hook config information. 15.993 </para> 15.994 15.995 @@ -1088,13 +1088,13 @@ 15.996 <sect3> 15.997 <title>Testing and troubleshooting</title> 15.998 15.999 - <para>The most common problems with configuring the <literal 15.1000 + <para id="x_262">The most common problems with configuring the <literal 15.1001 role="hg-ext">bugzilla</literal> hook relate to running 15.1002 Bugzilla's <filename>processmail</filename> script and 15.1003 mapping committer names to user names. 15.1004 </para> 15.1005 15.1006 - <para>Recall from section <xref 15.1007 + <para id="x_263">Recall from section <xref 15.1008 linkend="sec:hook:bugzilla:config"/> above that the user 15.1009 that runs the Mercurial process on the server is also the 15.1010 one that will run the <filename>processmail</filename> 15.1011 @@ -1105,19 +1105,19 @@ 15.1012 under. 15.1013 </para> 15.1014 15.1015 - <para>You can cause <filename>processmail</filename> to be run 15.1016 + <para id="x_264">You can cause <filename>processmail</filename> to be run 15.1017 with the suitable user's identity using the 15.1018 <command>sudo</command> command. Here is an example entry 15.1019 for a <filename>sudoers</filename> file. 15.1020 </para> 15.1021 <programlisting>hg_user = (httpd_user) 15.1022 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> 15.1023 - <para>This allows the <literal>hg_user</literal> user to run a 15.1024 + <para id="x_265">This allows the <literal>hg_user</literal> user to run a 15.1025 <filename>processmail-wrapper</filename> program under the 15.1026 identity of <literal>httpd_user</literal>. 15.1027 </para> 15.1028 15.1029 - <para>This indirection through a wrapper script is necessary, 15.1030 + <para id="x_266">This indirection through a wrapper script is necessary, 15.1031 because <filename>processmail</filename> expects to be run 15.1032 with its current directory set to wherever you installed 15.1033 Bugzilla; you can't specify that kind of constraint in a 15.1034 @@ -1126,18 +1126,18 @@ 15.1035 </para> 15.1036 <programlisting>#!/bin/sh 15.1037 cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> 15.1038 - <para>It doesn't seem to matter what email address you pass to 15.1039 + <para id="x_267">It doesn't seem to matter what email address you pass to 15.1040 <filename>processmail</filename>. 15.1041 </para> 15.1042 15.1043 - <para>If your <literal role="rc-usermap">usermap</literal> is 15.1044 + <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is 15.1045 not set up correctly, users will see an error message from 15.1046 the <literal role="hg-ext">bugzilla</literal> hook when they 15.1047 push changes to the server. The error message will look 15.1048 like this: 15.1049 </para> 15.1050 <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> 15.1051 - <para>What this means is that the committer's address, 15.1052 + <para id="x_269">What this means is that the committer's address, 15.1053 <literal>john.q.public@example.com</literal>, is not a valid 15.1054 Bugzilla user name, nor does it have an entry in your 15.1055 <literal role="rc-usermap">usermap</literal> that maps it to 15.1056 @@ -1150,7 +1150,7 @@ 15.1057 <title><literal role="hg-ext">notify</literal>&emdash;send email 15.1058 notifications</title> 15.1059 15.1060 - <para>Although Mercurial's built-in web server provides RSS 15.1061 + <para id="x_26a">Although Mercurial's built-in web server provides RSS 15.1062 feeds of changes in every repository, many people prefer to 15.1063 receive change notifications via email. The <literal 15.1064 role="hg-ext">notify</literal> hook lets you send out 15.1065 @@ -1158,13 +1158,13 @@ 15.1066 arrive that those subscribers are interested in. 15.1067 </para> 15.1068 15.1069 - <para>As with the <literal role="hg-ext">bugzilla</literal> 15.1070 + <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> 15.1071 hook, the <literal role="hg-ext">notify</literal> hook is 15.1072 template-driven, so you can customise the contents of the 15.1073 notification messages that it sends. 15.1074 </para> 15.1075 15.1076 - <para>By default, the <literal role="hg-ext">notify</literal> 15.1077 + <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> 15.1078 hook includes a diff of every changeset that it sends out; you 15.1079 can limit the size of the diff, or turn this feature off 15.1080 entirely. It is useful for letting subscribers review changes 15.1081 @@ -1175,7 +1175,7 @@ 15.1082 <title>Configuring the <literal role="hg-ext">notify</literal> 15.1083 hook</title> 15.1084 15.1085 - <para>You can set up the <literal 15.1086 + <para id="x_26d">You can set up the <literal 15.1087 role="hg-ext">notify</literal> hook to send one email 15.1088 message per incoming changeset, or one per incoming group of 15.1089 changesets (all those that arrived in a single pull or 15.1090 @@ -1187,12 +1187,12 @@ 15.1091 # send one email per change 15.1092 incoming.notify = python:hgext.notify.hook</programlisting> 15.1093 15.1094 - <para>Configuration information for this hook lives in the 15.1095 + <para id="x_26e">Configuration information for this hook lives in the 15.1096 <literal role="rc-notify">notify</literal> section of a 15.1097 <filename role="special">~/.hgrc</filename> file. 15.1098 </para> 15.1099 <itemizedlist> 15.1100 - <listitem><para><envar role="rc-item-notify">test</envar>: 15.1101 + <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: 15.1102 By default, this hook does not send out email at all; 15.1103 instead, it prints the message that it 15.1104 <emphasis>would</emphasis> send. Set this item to 15.1105 @@ -1204,7 +1204,7 @@ 15.1106 notifications while you debug your configuration. 15.1107 </para> 15.1108 </listitem> 15.1109 - <listitem><para><envar role="rc-item-notify">config</envar>: 15.1110 + <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: 15.1111 The path to a configuration file that contains 15.1112 subscription information. This is kept separate from 15.1113 the main <filename role="special">~/.hgrc</filename> so 15.1114 @@ -1213,7 +1213,7 @@ 15.1115 subscriptions, and push the changes back to your server. 15.1116 </para> 15.1117 </listitem> 15.1118 - <listitem><para><envar role="rc-item-notify">strip</envar>: 15.1119 + <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: 15.1120 The number of leading path separator characters to strip 15.1121 from a repository's path, when deciding whether a 15.1122 repository has subscribers. For example, if the 15.1123 @@ -1230,13 +1230,13 @@ 15.1124 match subscribers against that. 15.1125 </para> 15.1126 </listitem> 15.1127 - <listitem><para><envar 15.1128 + <listitem><para id="x_272"><envar 15.1129 role="rc-item-notify">template</envar>: The template 15.1130 text to use when sending messages. This specifies both 15.1131 the contents of the message header and its body. 15.1132 </para> 15.1133 </listitem> 15.1134 - <listitem><para><envar 15.1135 + <listitem><para id="x_273"><envar 15.1136 role="rc-item-notify">maxdiff</envar>: The maximum 15.1137 number of lines of diff data to append to the end of a 15.1138 message. If a diff is longer than this, it is 15.1139 @@ -1245,7 +1245,7 @@ 15.1140 emails. 15.1141 </para> 15.1142 </listitem> 15.1143 - <listitem><para><envar 15.1144 + <listitem><para id="x_274"><envar 15.1145 role="rc-item-notify">sources</envar>: A list of 15.1146 sources of changesets to consider. This lets you limit 15.1147 <literal role="hg-ext">notify</literal> to only sending 15.1148 @@ -1257,19 +1257,19 @@ 15.1149 </para> 15.1150 </listitem></itemizedlist> 15.1151 15.1152 - <para>If you set the <envar role="rc-item-web">baseurl</envar> 15.1153 + <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> 15.1154 item in the <literal role="rc-web">web</literal> section, 15.1155 you can use it in a template; it will be available as 15.1156 <literal>webroot</literal>. 15.1157 </para> 15.1158 15.1159 - <para>Here is an example set of <literal 15.1160 + <para id="x_276">Here is an example set of <literal 15.1161 role="hg-ext">notify</literal> configuration information. 15.1162 </para> 15.1163 15.1164 &ch10-notify-config.lst; 15.1165 15.1166 - <para>This will produce a message that looks like the 15.1167 + <para id="x_277">This will produce a message that looks like the 15.1168 following: 15.1169 </para> 15.1170 15.1171 @@ -1279,7 +1279,7 @@ 15.1172 <sect3> 15.1173 <title>Testing and troubleshooting</title> 15.1174 15.1175 - <para>Do not forget that by default, the <literal 15.1176 + <para id="x_278">Do not forget that by default, the <literal 15.1177 role="hg-ext">notify</literal> extension <emphasis>will not 15.1178 send any mail</emphasis> until you explicitly configure it to do so, 15.1179 by setting <envar role="rc-item-notify">test</envar> to 15.1180 @@ -1296,11 +1296,11 @@ 15.1181 <sect2> 15.1182 <title>In-process hook execution</title> 15.1183 15.1184 - <para>An in-process hook is called with arguments of the 15.1185 + <para id="x_279">An in-process hook is called with arguments of the 15.1186 following form: 15.1187 </para> 15.1188 <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> 15.1189 - <para>The <literal>ui</literal> parameter is a <literal 15.1190 + <para id="x_27a">The <literal>ui</literal> parameter is a <literal 15.1191 role="py-mod-mercurial.ui">ui</literal> object. The 15.1192 <literal>repo</literal> parameter is a <literal 15.1193 role="py-mod-mercurial.localrepo">localrepository</literal> 15.1194 @@ -1309,38 +1309,38 @@ 15.1195 being invoked, with the following common features: 15.1196 </para> 15.1197 <itemizedlist> 15.1198 - <listitem><para>If a parameter is named 15.1199 + <listitem><para id="x_27b">If a parameter is named 15.1200 <literal>node</literal> or <literal>parentN</literal>, it 15.1201 will contain a hexadecimal changeset ID. The empty string 15.1202 is used to represent <quote>null changeset ID</quote> 15.1203 instead of a string of zeroes. 15.1204 </para> 15.1205 </listitem> 15.1206 - <listitem><para>If a parameter is named 15.1207 + <listitem><para id="x_27c">If a parameter is named 15.1208 <literal>url</literal>, it will contain the URL of a 15.1209 remote repository, if that can be determined. 15.1210 </para> 15.1211 </listitem> 15.1212 - <listitem><para>Boolean-valued parameters are represented as 15.1213 + <listitem><para id="x_27d">Boolean-valued parameters are represented as 15.1214 Python <literal>bool</literal> objects. 15.1215 </para> 15.1216 </listitem></itemizedlist> 15.1217 15.1218 - <para>An in-process hook is called without a change to the 15.1219 + <para id="x_27e">An in-process hook is called without a change to the 15.1220 process's working directory (unlike external hooks, which are 15.1221 run in the root of the repository). It must not change the 15.1222 process's working directory, or it will cause any calls it 15.1223 makes into the Mercurial API to fail. 15.1224 </para> 15.1225 15.1226 - <para>If a hook returns a boolean <quote>false</quote> value, it 15.1227 + <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it 15.1228 is considered to have succeeded. If it returns a boolean 15.1229 <quote>true</quote> value or raises an exception, it is 15.1230 considered to have failed. A useful way to think of the 15.1231 calling convention is <quote>tell me if you fail</quote>. 15.1232 </para> 15.1233 15.1234 - <para>Note that changeset IDs are passed into Python hooks as 15.1235 + <para id="x_280">Note that changeset IDs are passed into Python hooks as 15.1236 hexadecimal strings, not the binary hashes that Mercurial's 15.1237 APIs normally use. To convert a hash from hex to binary, use 15.1238 the <literal>bin</literal> function. 15.1239 @@ -1350,7 +1350,7 @@ 15.1240 <sect2> 15.1241 <title>External hook execution</title> 15.1242 15.1243 - <para>An external hook is passed to the shell of the user 15.1244 + <para id="x_281">An external hook is passed to the shell of the user 15.1245 running Mercurial. Features of that shell, such as variable 15.1246 substitution and command redirection, are available. The hook 15.1247 is run in the root directory of the repository (unlike 15.1248 @@ -1358,7 +1358,7 @@ 15.1249 Mercurial was run in). 15.1250 </para> 15.1251 15.1252 - <para>Hook parameters are passed to the hook as environment 15.1253 + <para id="x_282">Hook parameters are passed to the hook as environment 15.1254 variables. Each environment variable's name is converted in 15.1255 upper case and prefixed with the string 15.1256 <quote><literal>HG_</literal></quote>. For example, if the 15.1257 @@ -1367,7 +1367,7 @@ 15.1258 parameter will be <quote><literal>HG_NODE</literal></quote>. 15.1259 </para> 15.1260 15.1261 - <para>A boolean parameter is represented as the string 15.1262 + <para id="x_283">A boolean parameter is represented as the string 15.1263 <quote><literal>1</literal></quote> for <quote>true</quote>, 15.1264 <quote><literal>0</literal></quote> for <quote>false</quote>. 15.1265 If an environment variable is named <envar>HG_NODE</envar>, 15.1266 @@ -1379,7 +1379,7 @@ 15.1267 URL of a remote repository, if that can be determined. 15.1268 </para> 15.1269 15.1270 - <para>If a hook exits with a status of zero, it is considered to 15.1271 + <para id="x_284">If a hook exits with a status of zero, it is considered to 15.1272 have succeeded. If it exits with a non-zero status, it is 15.1273 considered to have failed. 15.1274 </para> 15.1275 @@ -1388,7 +1388,7 @@ 15.1276 <sect2> 15.1277 <title>Finding out where changesets come from</title> 15.1278 15.1279 - <para>A hook that involves the transfer of changesets between a 15.1280 + <para id="x_285">A hook that involves the transfer of changesets between a 15.1281 local repository and another may be able to find out 15.1282 information about the <quote>far side</quote>. Mercurial 15.1283 knows <emphasis>how</emphasis> changes are being transferred, 15.1284 @@ -1399,7 +1399,7 @@ 15.1285 <sect3 id="sec:hook:sources"> 15.1286 <title>Sources of changesets</title> 15.1287 15.1288 - <para>Mercurial will tell a hook what means are, or were, used 15.1289 + <para id="x_286">Mercurial will tell a hook what means are, or were, used 15.1290 to transfer changesets between repositories. This is 15.1291 provided by Mercurial in a Python parameter named 15.1292 <literal>source</literal>, or an environment variable named 15.1293 @@ -1407,22 +1407,22 @@ 15.1294 </para> 15.1295 15.1296 <itemizedlist> 15.1297 - <listitem><para><literal>serve</literal>: Changesets are 15.1298 + <listitem><para id="x_287"><literal>serve</literal>: Changesets are 15.1299 transferred to or from a remote repository over http or 15.1300 ssh. 15.1301 </para> 15.1302 </listitem> 15.1303 - <listitem><para><literal>pull</literal>: Changesets are 15.1304 + <listitem><para id="x_288"><literal>pull</literal>: Changesets are 15.1305 being transferred via a pull from one repository into 15.1306 another. 15.1307 </para> 15.1308 </listitem> 15.1309 - <listitem><para><literal>push</literal>: Changesets are 15.1310 + <listitem><para id="x_289"><literal>push</literal>: Changesets are 15.1311 being transferred via a push from one repository into 15.1312 another. 15.1313 </para> 15.1314 </listitem> 15.1315 - <listitem><para><literal>bundle</literal>: Changesets are 15.1316 + <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are 15.1317 being transferred to or from a bundle. 15.1318 </para> 15.1319 </listitem></itemizedlist> 15.1320 @@ -1432,7 +1432,7 @@ 15.1321 <title>Where changes are going&emdash;remote repository 15.1322 URLs</title> 15.1323 15.1324 - <para>When possible, Mercurial will tell a hook the location 15.1325 + <para id="x_28b">When possible, Mercurial will tell a hook the location 15.1326 of the <quote>far side</quote> of an activity that transfers 15.1327 changeset data between repositories. This is provided by 15.1328 Mercurial in a Python parameter named 15.1329 @@ -1440,26 +1440,26 @@ 15.1330 <envar>HG_URL</envar>. 15.1331 </para> 15.1332 15.1333 - <para>This information is not always known. If a hook is 15.1334 + <para id="x_28c">This information is not always known. If a hook is 15.1335 invoked in a repository that is being served via http or 15.1336 ssh, Mercurial cannot tell where the remote repository is, 15.1337 but it may know where the client is connecting from. In 15.1338 such cases, the URL will take one of the following forms: 15.1339 </para> 15.1340 <itemizedlist> 15.1341 - <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 15.1342 + <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 15.1343 ssh client, at the IP address 15.1344 <literal>1.2.3.4</literal>. 15.1345 </para> 15.1346 </listitem> 15.1347 - <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote 15.1348 + <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 15.1349 http client, at the IP address 15.1350 <literal>1.2.3.4</literal>. If the client is using SSL, 15.1351 this will be of the form 15.1352 <literal>remote:https:1.2.3.4</literal>. 15.1353 </para> 15.1354 </listitem> 15.1355 - <listitem><para>Empty&emdash;no information could be 15.1356 + <listitem><para id="x_28f">Empty&emdash;no information could be 15.1357 discovered about the remote client. 15.1358 </para> 15.1359 </listitem></itemizedlist> 15.1360 @@ -1474,7 +1474,7 @@ 15.1361 <title><literal role="hook">changegroup</literal>&emdash;after 15.1362 remote changesets added</title> 15.1363 15.1364 - <para>This hook is run after a group of pre-existing changesets 15.1365 + <para id="x_290">This hook is run after a group of pre-existing changesets 15.1366 has been added to the repository, for example via a <command 15.1367 role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 15.1368 unbundle</command>. This hook is run once per operation 15.1369 @@ -1484,16 +1484,16 @@ 15.1370 arrive in a group. 15.1371 </para> 15.1372 15.1373 - <para>Some possible uses for this hook include kicking off an 15.1374 + <para id="x_291">Some possible uses for this hook include kicking off an 15.1375 automated build or test of the added changesets, updating a 15.1376 bug database, or notifying subscribers that a repository 15.1377 contains new changes. 15.1378 </para> 15.1379 15.1380 - <para>Parameters to this hook: 15.1381 + <para id="x_292">Parameters to this hook: 15.1382 </para> 15.1383 <itemizedlist> 15.1384 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1385 + <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The 15.1386 changeset ID of the first changeset in the group that was 15.1387 added. All changesets between this and 15.1388 <literal role="tag">tip</literal>, inclusive, were added by a single 15.1389 @@ -1502,19 +1502,19 @@ 15.1390 role="hg-cmd">hg unbundle</command>. 15.1391 </para> 15.1392 </listitem> 15.1393 - <listitem><para><literal>source</literal>: A string. The 15.1394 + <listitem><para id="x_294"><literal>source</literal>: A string. The 15.1395 source of these changes. See section <xref 15.1396 linkend="sec:hook:sources"/> for details. 15.1397 </para> 15.1398 </listitem> 15.1399 - <listitem><para><literal>url</literal>: A URL. The location 15.1400 + <listitem><para id="x_295"><literal>url</literal>: A URL. The location 15.1401 of the remote repository, if known. See section <xref 15.1402 linkend="sec:hook:url"/> for more 15.1403 information. 15.1404 </para> 15.1405 </listitem></itemizedlist> 15.1406 15.1407 - <para>See also: <literal role="hook">incoming</literal> (section 15.1408 + <para id="x_296">See also: <literal role="hook">incoming</literal> (section 15.1409 <xref linkend="sec:hook:incoming"/>), <literal 15.1410 role="hook">prechangegroup</literal> (section <xref 15.1411 linkend="sec:hook:prechangegroup"/>), <literal 15.1412 @@ -1527,28 +1527,28 @@ 15.1413 <title><literal role="hook">commit</literal>&emdash;after a new 15.1414 changeset is created</title> 15.1415 15.1416 - <para>This hook is run after a new changeset has been created. 15.1417 - </para> 15.1418 - 15.1419 - <para>Parameters to this hook: 15.1420 + <para id="x_297">This hook is run after a new changeset has been created. 15.1421 + </para> 15.1422 + 15.1423 + <para id="x_298">Parameters to this hook: 15.1424 </para> 15.1425 <itemizedlist> 15.1426 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1427 + <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The 15.1428 changeset ID of the newly committed changeset. 15.1429 </para> 15.1430 </listitem> 15.1431 - <listitem><para><literal>parent1</literal>: A changeset ID. 15.1432 + <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. 15.1433 The changeset ID of the first parent of the newly 15.1434 committed changeset. 15.1435 </para> 15.1436 </listitem> 15.1437 - <listitem><para><literal>parent2</literal>: A changeset ID. 15.1438 + <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. 15.1439 The changeset ID of the second parent of the newly 15.1440 committed changeset. 15.1441 </para> 15.1442 </listitem></itemizedlist> 15.1443 15.1444 - <para>See also: <literal role="hook">precommit</literal> 15.1445 + <para id="x_29c">See also: <literal role="hook">precommit</literal> 15.1446 (section <xref linkend="sec:hook:precommit"/>), <literal 15.1447 role="hook">pretxncommit</literal> (section <xref 15.1448 linkend="sec:hook:pretxncommit"/>) 15.1449 @@ -1559,40 +1559,40 @@ 15.1450 <title><literal role="hook">incoming</literal>&emdash;after one 15.1451 remote changeset is added</title> 15.1452 15.1453 - <para>This hook is run after a pre-existing changeset has been 15.1454 + <para id="x_29d">This hook is run after a pre-existing changeset has been 15.1455 added to the repository, for example via a <command 15.1456 role="hg-cmd">hg push</command>. If a group of changesets 15.1457 was added in a single operation, this hook is called once for 15.1458 each added changeset. 15.1459 </para> 15.1460 15.1461 - <para>You can use this hook for the same purposes as the 15.1462 + <para id="x_29e">You can use this hook for the same purposes as the 15.1463 <literal role="hook">changegroup</literal> hook (section <xref 15.1464 linkend="sec:hook:changegroup"/>); it's simply 15.1465 more convenient sometimes to run a hook once per group of 15.1466 changesets, while other times it's handier once per changeset. 15.1467 </para> 15.1468 15.1469 - <para>Parameters to this hook: 15.1470 + <para id="x_29f">Parameters to this hook: 15.1471 </para> 15.1472 <itemizedlist> 15.1473 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1474 + <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The 15.1475 ID of the newly added changeset. 15.1476 </para> 15.1477 </listitem> 15.1478 - <listitem><para><literal>source</literal>: A string. The 15.1479 + <listitem><para id="x_2a1"><literal>source</literal>: A string. The 15.1480 source of these changes. See section <xref 15.1481 linkend="sec:hook:sources"/> for details. 15.1482 </para> 15.1483 </listitem> 15.1484 - <listitem><para><literal>url</literal>: A URL. The location 15.1485 + <listitem><para id="x_2a2"><literal>url</literal>: A URL. The location 15.1486 of the remote repository, if known. See section <xref 15.1487 linkend="sec:hook:url"/> for more 15.1488 information. 15.1489 </para> 15.1490 </listitem></itemizedlist> 15.1491 15.1492 - <para>See also: <literal role="hook">changegroup</literal> 15.1493 + <para id="x_2a3">See also: <literal role="hook">changegroup</literal> 15.1494 (section <xref linkend="sec:hook:changegroup"/>) <literal 15.1495 role="hook">prechangegroup</literal> (section <xref 15.1496 linkend="sec:hook:prechangegroup"/>), <literal 15.1497 @@ -1605,25 +1605,25 @@ 15.1498 <title><literal role="hook">outgoing</literal>&emdash;after 15.1499 changesets are propagated</title> 15.1500 15.1501 - <para>This hook is run after a group of changesets has been 15.1502 + <para id="x_2a4">This hook is run after a group of changesets has been 15.1503 propagated out of this repository, for example by a <command 15.1504 role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 15.1505 bundle</command> command. 15.1506 </para> 15.1507 15.1508 - <para>One possible use for this hook is to notify administrators 15.1509 + <para id="x_2a5">One possible use for this hook is to notify administrators 15.1510 that changes have been pulled. 15.1511 </para> 15.1512 15.1513 - <para>Parameters to this hook: 15.1514 + <para id="x_2a6">Parameters to this hook: 15.1515 </para> 15.1516 <itemizedlist> 15.1517 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1518 + <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The 15.1519 changeset ID of the first changeset of the group that was 15.1520 sent. 15.1521 </para> 15.1522 </listitem> 15.1523 - <listitem><para><literal>source</literal>: A string. The 15.1524 + <listitem><para id="x_2a8"><literal>source</literal>: A string. The 15.1525 source of the of the operation (see section <xref 15.1526 linkend="sec:hook:sources"/>). If a remote 15.1527 client pulled changes from this repository, 15.1528 @@ -1636,14 +1636,14 @@ 15.1529 client performed. 15.1530 </para> 15.1531 </listitem> 15.1532 - <listitem><para><literal>url</literal>: A URL. The location 15.1533 + <listitem><para id="x_2a9"><literal>url</literal>: A URL. The location 15.1534 of the remote repository, if known. See section <xref 15.1535 linkend="sec:hook:url"/> for more 15.1536 information. 15.1537 </para> 15.1538 </listitem></itemizedlist> 15.1539 15.1540 - <para>See also: <literal role="hook">preoutgoing</literal> 15.1541 + <para id="x_2aa">See also: <literal role="hook">preoutgoing</literal> 15.1542 (section <xref linkend="sec:hook:preoutgoing"/>) 15.1543 </para> 15.1544 15.1545 @@ -1653,39 +1653,39 @@ 15.1546 role="hook">prechangegroup</literal>&emdash;before starting 15.1547 to add remote changesets</title> 15.1548 15.1549 - <para>This controlling hook is run before Mercurial begins to 15.1550 + <para id="x_2ab">This controlling hook is run before Mercurial begins to 15.1551 add a group of changesets from another repository. 15.1552 </para> 15.1553 15.1554 - <para>This hook does not have any information about the 15.1555 + <para id="x_2ac">This hook does not have any information about the 15.1556 changesets to be added, because it is run before transmission 15.1557 of those changesets is allowed to begin. If this hook fails, 15.1558 the changesets will not be transmitted. 15.1559 </para> 15.1560 15.1561 - <para>One use for this hook is to prevent external changes from 15.1562 + <para id="x_2ad">One use for this hook is to prevent external changes from 15.1563 being added to a repository. For example, you could use this 15.1564 to <quote>freeze</quote> a server-hosted branch temporarily or 15.1565 permanently so that users cannot push to it, while still 15.1566 allowing a local administrator to modify the repository. 15.1567 </para> 15.1568 15.1569 - <para>Parameters to this hook: 15.1570 + <para id="x_2ae">Parameters to this hook: 15.1571 </para> 15.1572 <itemizedlist> 15.1573 - <listitem><para><literal>source</literal>: A string. The 15.1574 + <listitem><para id="x_2af"><literal>source</literal>: A string. The 15.1575 source of these changes. See section <xref 15.1576 linkend="sec:hook:sources"/> for details. 15.1577 </para> 15.1578 </listitem> 15.1579 - <listitem><para><literal>url</literal>: A URL. The location 15.1580 + <listitem><para id="x_2b0"><literal>url</literal>: A URL. The location 15.1581 of the remote repository, if known. See section <xref 15.1582 linkend="sec:hook:url"/> for more 15.1583 information. 15.1584 </para> 15.1585 </listitem></itemizedlist> 15.1586 15.1587 - <para>See also: <literal role="hook">changegroup</literal> 15.1588 + <para id="x_2b1">See also: <literal role="hook">changegroup</literal> 15.1589 (section <xref linkend="sec:hook:changegroup"/>), <literal 15.1590 role="hook">incoming</literal> (section <xref 15.1591 linkend="sec:hook:incoming"/>), , <literal 15.1592 @@ -1698,36 +1698,36 @@ 15.1593 <title><literal role="hook">precommit</literal>&emdash;before 15.1594 starting to commit a changeset</title> 15.1595 15.1596 - <para>This hook is run before Mercurial begins to commit a new 15.1597 + <para id="x_2b2">This hook is run before Mercurial begins to commit a new 15.1598 changeset. It is run before Mercurial has any of the metadata 15.1599 for the commit, such as the files to be committed, the commit 15.1600 message, or the commit date. 15.1601 </para> 15.1602 15.1603 - <para>One use for this hook is to disable the ability to commit 15.1604 + <para id="x_2b3">One use for this hook is to disable the ability to commit 15.1605 new changesets, while still allowing incoming changesets. 15.1606 Another is to run a build or test, and only allow the commit 15.1607 to begin if the build or test succeeds. 15.1608 </para> 15.1609 15.1610 - <para>Parameters to this hook: 15.1611 + <para id="x_2b4">Parameters to this hook: 15.1612 </para> 15.1613 <itemizedlist> 15.1614 - <listitem><para><literal>parent1</literal>: A changeset ID. 15.1615 + <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. 15.1616 The changeset ID of the first parent of the working 15.1617 directory. 15.1618 </para> 15.1619 </listitem> 15.1620 - <listitem><para><literal>parent2</literal>: A changeset ID. 15.1621 + <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. 15.1622 The changeset ID of the second parent of the working 15.1623 directory. 15.1624 </para> 15.1625 </listitem></itemizedlist> 15.1626 - <para>If the commit proceeds, the parents of the working 15.1627 + <para id="x_2b7">If the commit proceeds, the parents of the working 15.1628 directory will become the parents of the new changeset. 15.1629 </para> 15.1630 15.1631 - <para>See also: <literal role="hook">commit</literal> (section 15.1632 + <para id="x_2b8">See also: <literal role="hook">commit</literal> (section 15.1633 <xref linkend="sec:hook:commit"/>), <literal 15.1634 role="hook">pretxncommit</literal> (section <xref 15.1635 linkend="sec:hook:pretxncommit"/>) 15.1636 @@ -1738,18 +1738,18 @@ 15.1637 <title><literal role="hook">preoutgoing</literal>&emdash;before 15.1638 starting to propagate changesets</title> 15.1639 15.1640 - <para>This hook is invoked before Mercurial knows the identities 15.1641 + <para id="x_2b9">This hook is invoked before Mercurial knows the identities 15.1642 of the changesets to be transmitted. 15.1643 </para> 15.1644 15.1645 - <para>One use for this hook is to prevent changes from being 15.1646 + <para id="x_2ba">One use for this hook is to prevent changes from being 15.1647 transmitted to another repository. 15.1648 </para> 15.1649 15.1650 - <para>Parameters to this hook: 15.1651 + <para id="x_2bb">Parameters to this hook: 15.1652 </para> 15.1653 <itemizedlist> 15.1654 - <listitem><para><literal>source</literal>: A string. The 15.1655 + <listitem><para id="x_2bc"><literal>source</literal>: A string. The 15.1656 source of the operation that is attempting to obtain 15.1657 changes from this repository (see section <xref 15.1658 linkend="sec:hook:sources"/>). See the documentation 15.1659 @@ -1760,14 +1760,14 @@ 15.1660 this parameter. 15.1661 </para> 15.1662 </listitem> 15.1663 - <listitem><para><literal>url</literal>: A URL. The location 15.1664 + <listitem><para id="x_2bd"><literal>url</literal>: A URL. The location 15.1665 of the remote repository, if known. See section <xref 15.1666 linkend="sec:hook:url"/> for more 15.1667 information. 15.1668 </para> 15.1669 </listitem></itemizedlist> 15.1670 15.1671 - <para>See also: <literal role="hook">outgoing</literal> (section 15.1672 + <para id="x_2be">See also: <literal role="hook">outgoing</literal> (section 15.1673 <xref linkend="sec:hook:outgoing"/>) 15.1674 </para> 15.1675 15.1676 @@ -1776,38 +1776,38 @@ 15.1677 <title><literal role="hook">pretag</literal>&emdash;before 15.1678 tagging a changeset</title> 15.1679 15.1680 - <para>This controlling hook is run before a tag is created. If 15.1681 + <para id="x_2bf">This controlling hook is run before a tag is created. If 15.1682 the hook succeeds, creation of the tag proceeds. If the hook 15.1683 fails, the tag is not created. 15.1684 </para> 15.1685 15.1686 - <para>Parameters to this hook: 15.1687 + <para id="x_2c0">Parameters to this hook: 15.1688 </para> 15.1689 <itemizedlist> 15.1690 - <listitem><para><literal>local</literal>: A boolean. Whether 15.1691 + <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether 15.1692 the tag is local to this repository instance (i.e. stored 15.1693 in <filename role="special">.hg/localtags</filename>) or 15.1694 managed by Mercurial (stored in <filename 15.1695 role="special">.hgtags</filename>). 15.1696 </para> 15.1697 </listitem> 15.1698 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1699 + <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The 15.1700 ID of the changeset to be tagged. 15.1701 </para> 15.1702 </listitem> 15.1703 - <listitem><para><literal>tag</literal>: A string. The name of 15.1704 + <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of 15.1705 the tag to be created. 15.1706 </para> 15.1707 </listitem></itemizedlist> 15.1708 15.1709 - <para>If the tag to be created is revision-controlled, the 15.1710 + <para id="x_2c4">If the tag to be created is revision-controlled, the 15.1711 <literal role="hook">precommit</literal> and <literal 15.1712 role="hook">pretxncommit</literal> hooks (sections <xref 15.1713 linkend="sec:hook:commit"/> and <xref 15.1714 linkend="sec:hook:pretxncommit"/>) will also be run. 15.1715 </para> 15.1716 15.1717 - <para>See also: <literal role="hook">tag</literal> (section 15.1718 + <para id="x_2c5">See also: <literal role="hook">tag</literal> (section 15.1719 <xref linkend="sec:hook:tag"/>) 15.1720 </para> 15.1721 </sect2> 15.1722 @@ -1816,7 +1816,7 @@ 15.1723 role="hook">pretxnchangegroup</literal>&emdash;before 15.1724 completing addition of remote changesets</title> 15.1725 15.1726 - <para>This controlling hook is run before a 15.1727 + <para id="x_2c6">This controlling hook is run before a 15.1728 transaction&emdash;that manages the addition of a group of new 15.1729 changesets from outside the repository&emdash;completes. If 15.1730 the hook succeeds, the transaction completes, and all of the 15.1731 @@ -1825,28 +1825,28 @@ 15.1732 the changesets is erased. 15.1733 </para> 15.1734 15.1735 - <para>This hook can access the metadata associated with the 15.1736 + <para id="x_2c7">This hook can access the metadata associated with the 15.1737 almost-added changesets, but it should not do anything 15.1738 permanent with this data. It must also not modify the working 15.1739 directory. 15.1740 </para> 15.1741 15.1742 - <para>While this hook is running, if other Mercurial processes 15.1743 + <para id="x_2c8">While this hook is running, if other Mercurial processes 15.1744 access this repository, they will be able to see the 15.1745 almost-added changesets as if they are permanent. This may 15.1746 lead to race conditions if you do not take steps to avoid 15.1747 them. 15.1748 </para> 15.1749 15.1750 - <para>This hook can be used to automatically vet a group of 15.1751 + <para id="x_2c9">This hook can be used to automatically vet a group of 15.1752 changesets. If the hook fails, all of the changesets are 15.1753 <quote>rejected</quote> when the transaction rolls back. 15.1754 </para> 15.1755 15.1756 - <para>Parameters to this hook: 15.1757 + <para id="x_2ca">Parameters to this hook: 15.1758 </para> 15.1759 <itemizedlist> 15.1760 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1761 + <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The 15.1762 changeset ID of the first changeset in the group that was 15.1763 added. All changesets between this and 15.1764 <literal role="tag">tip</literal>, 15.1765 @@ -1856,19 +1856,19 @@ 15.1766 role="hg-cmd">hg unbundle</command>. 15.1767 </para> 15.1768 </listitem> 15.1769 - <listitem><para><literal>source</literal>: A string. The 15.1770 + <listitem><para id="x_2cc"><literal>source</literal>: A string. The 15.1771 source of these changes. See section <xref 15.1772 linkend="sec:hook:sources"/> for details. 15.1773 </para> 15.1774 </listitem> 15.1775 - <listitem><para><literal>url</literal>: A URL. The location 15.1776 + <listitem><para id="x_2cd"><literal>url</literal>: A URL. The location 15.1777 of the remote repository, if known. See section <xref 15.1778 linkend="sec:hook:url"/> for more 15.1779 information. 15.1780 </para> 15.1781 </listitem></itemizedlist> 15.1782 15.1783 - <para>See also: <literal role="hook">changegroup</literal> 15.1784 + <para id="x_2ce">See also: <literal role="hook">changegroup</literal> 15.1785 (section <xref linkend="sec:hook:changegroup"/>), <literal 15.1786 role="hook">incoming</literal> (section <xref 15.1787 linkend="sec:hook:incoming"/>), <literal 15.1788 @@ -1881,7 +1881,7 @@ 15.1789 <title><literal role="hook">pretxncommit</literal>&emdash;before 15.1790 completing commit of new changeset</title> 15.1791 15.1792 - <para>This controlling hook is run before a 15.1793 + <para id="x_2cf">This controlling hook is run before a 15.1794 transaction&emdash;that manages a new commit&emdash;completes. 15.1795 If the hook succeeds, the transaction completes and the 15.1796 changeset becomes permanent within this repository. If the 15.1797 @@ -1889,37 +1889,37 @@ 15.1798 data is erased. 15.1799 </para> 15.1800 15.1801 - <para>This hook can access the metadata associated with the 15.1802 + <para id="x_2d0">This hook can access the metadata associated with the 15.1803 almost-new changeset, but it should not do anything permanent 15.1804 with this data. It must also not modify the working 15.1805 directory. 15.1806 </para> 15.1807 15.1808 - <para>While this hook is running, if other Mercurial processes 15.1809 + <para id="x_2d1">While this hook is running, if other Mercurial processes 15.1810 access this repository, they will be able to see the 15.1811 almost-new changeset as if it is permanent. This may lead to 15.1812 race conditions if you do not take steps to avoid them. 15.1813 </para> 15.1814 15.1815 - <para>Parameters to this hook: 15.1816 + <para id="x_2d2">Parameters to this hook: 15.1817 </para> 15.1818 <itemizedlist> 15.1819 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1820 + <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 15.1821 changeset ID of the newly committed changeset. 15.1822 </para> 15.1823 </listitem> 15.1824 - <listitem><para><literal>parent1</literal>: A changeset ID. 15.1825 + <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. 15.1826 The changeset ID of the first parent of the newly 15.1827 committed changeset. 15.1828 </para> 15.1829 </listitem> 15.1830 - <listitem><para><literal>parent2</literal>: A changeset ID. 15.1831 + <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. 15.1832 The changeset ID of the second parent of the newly 15.1833 committed changeset. 15.1834 </para> 15.1835 </listitem></itemizedlist> 15.1836 15.1837 - <para>See also: <literal role="hook">precommit</literal> 15.1838 + <para id="x_2d6">See also: <literal role="hook">precommit</literal> 15.1839 (section <xref linkend="sec:hook:precommit"/>) 15.1840 </para> 15.1841 15.1842 @@ -1928,30 +1928,30 @@ 15.1843 <title><literal role="hook">preupdate</literal>&emdash;before 15.1844 updating or merging working directory</title> 15.1845 15.1846 - <para>This controlling hook is run before an update or merge of 15.1847 + <para id="x_2d7">This controlling hook is run before an update or merge of 15.1848 the working directory begins. It is run only if Mercurial's 15.1849 normal pre-update checks determine that the update or merge 15.1850 can proceed. If the hook succeeds, the update or merge may 15.1851 proceed; if it fails, the update or merge does not start. 15.1852 </para> 15.1853 15.1854 - <para>Parameters to this hook: 15.1855 + <para id="x_2d8">Parameters to this hook: 15.1856 </para> 15.1857 <itemizedlist> 15.1858 - <listitem><para><literal>parent1</literal>: A changeset ID. 15.1859 + <listitem><para id="x_2d9"><literal>parent1</literal>: A changeset ID. 15.1860 The ID of the parent that the working directory is to be 15.1861 updated to. If the working directory is being merged, it 15.1862 will not change this parent. 15.1863 </para> 15.1864 </listitem> 15.1865 - <listitem><para><literal>parent2</literal>: A changeset ID. 15.1866 + <listitem><para id="x_2da"><literal>parent2</literal>: A changeset ID. 15.1867 Only set if the working directory is being merged. The ID 15.1868 of the revision that the working directory is being merged 15.1869 with. 15.1870 </para> 15.1871 </listitem></itemizedlist> 15.1872 15.1873 - <para>See also: <literal role="hook">update</literal> (section 15.1874 + <para id="x_2db">See also: <literal role="hook">update</literal> (section 15.1875 <xref linkend="sec:hook:update"/>) 15.1876 </para> 15.1877 15.1878 @@ -1960,13 +1960,13 @@ 15.1879 <title><literal role="hook">tag</literal>&emdash;after tagging a 15.1880 changeset</title> 15.1881 15.1882 - <para>This hook is run after a tag has been created. 15.1883 - </para> 15.1884 - 15.1885 - <para>Parameters to this hook: 15.1886 + <para id="x_2dc">This hook is run after a tag has been created. 15.1887 + </para> 15.1888 + 15.1889 + <para id="x_2dd">Parameters to this hook: 15.1890 </para> 15.1891 <itemizedlist> 15.1892 - <listitem><para><literal>local</literal>: A boolean. Whether 15.1893 + <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether 15.1894 the new tag is local to this repository instance (i.e. 15.1895 stored in <filename 15.1896 role="special">.hg/localtags</filename>) or managed by 15.1897 @@ -1974,21 +1974,21 @@ 15.1898 role="special">.hgtags</filename>). 15.1899 </para> 15.1900 </listitem> 15.1901 - <listitem><para><literal>node</literal>: A changeset ID. The 15.1902 + <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The 15.1903 ID of the changeset that was tagged. 15.1904 </para> 15.1905 </listitem> 15.1906 - <listitem><para><literal>tag</literal>: A string. The name of 15.1907 + <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of 15.1908 the tag that was created. 15.1909 </para> 15.1910 </listitem></itemizedlist> 15.1911 15.1912 - <para>If the created tag is revision-controlled, the <literal 15.1913 + <para id="x_2e1">If the created tag is revision-controlled, the <literal 15.1914 role="hook">commit</literal> hook (section <xref 15.1915 linkend="sec:hook:commit"/>) is run before this hook. 15.1916 </para> 15.1917 15.1918 - <para>See also: <literal role="hook">pretag</literal> (section 15.1919 + <para id="x_2e2">See also: <literal role="hook">pretag</literal> (section 15.1920 <xref linkend="sec:hook:pretag"/>) 15.1921 </para> 15.1922 15.1923 @@ -1997,7 +1997,7 @@ 15.1924 <title><literal role="hook">update</literal>&emdash;after 15.1925 updating or merging working directory</title> 15.1926 15.1927 - <para>This hook is run after an update or merge of the working 15.1928 + <para id="x_2e3">This hook is run after an update or merge of the working 15.1929 directory completes. Since a merge can fail (if the external 15.1930 <command>hgmerge</command> command fails to resolve conflicts 15.1931 in a file), this hook communicates whether the update or merge 15.1932 @@ -2005,24 +2005,24 @@ 15.1933 </para> 15.1934 15.1935 <itemizedlist> 15.1936 - <listitem><para><literal>error</literal>: A boolean. 15.1937 + <listitem><para id="x_2e4"><literal>error</literal>: A boolean. 15.1938 Indicates whether the update or merge completed 15.1939 successfully. 15.1940 </para> 15.1941 </listitem> 15.1942 - <listitem><para><literal>parent1</literal>: A changeset ID. 15.1943 + <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. 15.1944 The ID of the parent that the working directory was 15.1945 updated to. If the working directory was merged, it will 15.1946 not have changed this parent. 15.1947 </para> 15.1948 </listitem> 15.1949 - <listitem><para><literal>parent2</literal>: A changeset ID. 15.1950 + <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. 15.1951 Only set if the working directory was merged. The ID of 15.1952 the revision that the working directory was merged with. 15.1953 </para> 15.1954 </listitem></itemizedlist> 15.1955 15.1956 - <para>See also: <literal role="hook">preupdate</literal> 15.1957 + <para id="x_2e7">See also: <literal role="hook">preupdate</literal> 15.1958 (section <xref linkend="sec:hook:preupdate"/>) 15.1959 </para> 15.1960
16.1 --- a/en/ch10-template.xml Thu Mar 19 20:54:12 2009 -0700 16.2 +++ b/en/ch10-template.xml Thu Mar 19 21:18:52 2009 -0700 16.3 @@ -4,7 +4,7 @@ 16.4 <?dbhtml filename="customizing-the-output-of-mercurial.html"?> 16.5 <title>Customising the output of Mercurial</title> 16.6 16.7 - <para>Mercurial provides a powerful mechanism to let you control how 16.8 + <para id="x_578">Mercurial provides a powerful mechanism to let you control how 16.9 it displays information. The mechanism is based on templates. 16.10 You can use templates to generate specific output for a single 16.11 command, or to customise the entire appearance of the built-in web 16.12 @@ -13,37 +13,37 @@ 16.13 <sect1 id="sec:style"> 16.14 <title>Using precanned output styles</title> 16.15 16.16 - <para>Packaged with Mercurial are some output styles that you can 16.17 + <para id="x_579">Packaged with Mercurial are some output styles that you can 16.18 use immediately. A style is simply a precanned template that 16.19 someone wrote and installed somewhere that Mercurial can 16.20 find.</para> 16.21 16.22 - <para>Before we take a look at Mercurial's bundled styles, let's 16.23 + <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's 16.24 review its normal output.</para> 16.25 16.26 &interaction.template.simple.normal; 16.27 16.28 - <para>This is somewhat informative, but it takes up a lot of 16.29 + <para id="x_57b">This is somewhat informative, but it takes up a lot of 16.30 space&emdash;five lines of output per changeset. The 16.31 <literal>compact</literal> style reduces this to three lines, 16.32 presented in a sparse manner.</para> 16.33 16.34 &interaction.template.simple.compact; 16.35 16.36 - <para>The <literal>changelog</literal> style hints at the 16.37 + <para id="x_57c">The <literal>changelog</literal> style hints at the 16.38 expressive power of Mercurial's templating engine. This style 16.39 attempts to follow the GNU Project's changelog 16.40 guidelines<citation>web:changelog</citation>.</para> 16.41 16.42 &interaction.template.simple.changelog; 16.43 16.44 - <para>You will not be shocked to learn that Mercurial's default 16.45 + <para id="x_57d">You will not be shocked to learn that Mercurial's default 16.46 output style is named <literal>default</literal>.</para> 16.47 16.48 <sect2> 16.49 <title>Setting a default style</title> 16.50 16.51 - <para>You can modify the output style that Mercurial will use 16.52 + <para id="x_57e">You can modify the output style that Mercurial will use 16.53 for every command by editing your <filename 16.54 role="special">~/.hgrc</filename> file, naming the style 16.55 you would prefer to use.</para> 16.56 @@ -51,7 +51,7 @@ 16.57 <programlisting>[ui] 16.58 style = compact</programlisting> 16.59 16.60 - <para>If you write a style of your own, you can use it by either 16.61 + <para id="x_57f">If you write a style of your own, you can use it by either 16.62 providing the path to your style file, or copying your style 16.63 file into a location where Mercurial can find it (typically 16.64 the <literal>templates</literal> subdirectory of your 16.65 @@ -62,14 +62,14 @@ 16.66 <sect1> 16.67 <title>Commands that support styles and templates</title> 16.68 16.69 - <para>All of Mercurial's 16.70 + <para id="x_580">All of Mercurial's 16.71 <quote><literal>log</literal>-like</quote> commands let you use 16.72 styles and templates: <command role="hg-cmd">hg 16.73 incoming</command>, <command role="hg-cmd">hg log</command>, 16.74 <command role="hg-cmd">hg outgoing</command>, and <command 16.75 role="hg-cmd">hg tip</command>.</para> 16.76 16.77 - <para>As I write this manual, these are so far the only commands 16.78 + <para id="x_581">As I write this manual, these are so far the only commands 16.79 that support styles and templates. Since these are the most 16.80 important commands that need customisable output, there has been 16.81 little pressure from the Mercurial user community to add style 16.82 @@ -79,22 +79,22 @@ 16.83 <sect1> 16.84 <title>The basics of templating</title> 16.85 16.86 - <para>At its simplest, a Mercurial template is a piece of text. 16.87 + <para id="x_582">At its simplest, a Mercurial template is a piece of text. 16.88 Some of the text never changes, while other parts are 16.89 <emphasis>expanded</emphasis>, or replaced with new text, when 16.90 necessary.</para> 16.91 16.92 - <para>Before we continue, let's look again at a simple example of 16.93 + <para id="x_583">Before we continue, let's look again at a simple example of 16.94 Mercurial's normal output.</para> 16.95 16.96 &interaction.template.simple.normal; 16.97 16.98 - <para>Now, let's run the same command, but using a template to 16.99 + <para id="x_584">Now, let's run the same command, but using a template to 16.100 change its output.</para> 16.101 16.102 &interaction.template.simple.simplest; 16.103 16.104 - <para>The example above illustrates the simplest possible 16.105 + <para id="x_585">The example above illustrates the simplest possible 16.106 template; it's just a piece of static text, printed once for 16.107 each changeset. The <option 16.108 role="hg-opt-log">--template</option> option to the <command 16.109 @@ -102,7 +102,7 @@ 16.110 the given text as the template when printing each 16.111 changeset.</para> 16.112 16.113 - <para>Notice that the template string above ends with the text 16.114 + <para id="x_586">Notice that the template string above ends with the text 16.115 <quote><literal>\n</literal></quote>. This is an 16.116 <emphasis>escape sequence</emphasis>, telling Mercurial to print 16.117 a newline at the end of each template item. If you omit this 16.118 @@ -110,13 +110,13 @@ 16.119 section <xref linkend="sec:template:escape"/> for more details 16.120 of escape sequences.</para> 16.121 16.122 - <para>A template that prints a fixed string of text all the time 16.123 + <para id="x_587">A template that prints a fixed string of text all the time 16.124 isn't very useful; let's try something a bit more 16.125 complex.</para> 16.126 16.127 &interaction.template.simple.simplesub; 16.128 16.129 - <para>As you can see, the string 16.130 + <para id="x_588">As you can see, the string 16.131 <quote><literal>{desc}</literal></quote> in the template has 16.132 been replaced in the output with the description of each 16.133 changeset. Every time Mercurial finds text enclosed in curly 16.134 @@ -131,21 +131,21 @@ 16.135 <sect1 id="sec:template:keyword"> 16.136 <title>Common template keywords</title> 16.137 16.138 - <para>You can start writing simple templates immediately using the 16.139 + <para id="x_589">You can start writing simple templates immediately using the 16.140 keywords below.</para> 16.141 16.142 <itemizedlist> 16.143 - <listitem><para><literal 16.144 + <listitem><para id="x_58a"><literal 16.145 role="template-keyword">author</literal>: String. The 16.146 unmodified author of the changeset.</para> 16.147 </listitem> 16.148 - <listitem><para><literal 16.149 + <listitem><para id="x_58b"><literal 16.150 role="template-keyword">branches</literal>: String. The 16.151 name of the branch on which the changeset was committed. 16.152 Will be empty if the branch name was 16.153 <literal>default</literal>.</para> 16.154 </listitem> 16.155 - <listitem><para><literal role="template-keyword">date</literal>: 16.156 + <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: 16.157 Date information. The date when the changeset was 16.158 committed. This is <emphasis>not</emphasis> human-readable; 16.159 you must pass it through a filter that will render it 16.160 @@ -156,45 +156,45 @@ 16.161 1, 1970); the second is the offset of the committer's 16.162 timezone from UTC, in seconds.</para> 16.163 </listitem> 16.164 - <listitem><para><literal role="template-keyword">desc</literal>: 16.165 + <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: 16.166 String. The text of the changeset description.</para> 16.167 </listitem> 16.168 - <listitem><para><literal 16.169 + <listitem><para id="x_58e"><literal 16.170 role="template-keyword">files</literal>: List of strings. 16.171 All files modified, added, or removed by this 16.172 changeset.</para> 16.173 </listitem> 16.174 - <listitem><para><literal 16.175 + <listitem><para id="x_58f"><literal 16.176 role="template-keyword">file_adds</literal>: List of 16.177 strings. Files added by this changeset.</para> 16.178 </listitem> 16.179 - <listitem><para><literal 16.180 + <listitem><para id="x_590"><literal 16.181 role="template-keyword">file_dels</literal>: List of 16.182 strings. Files removed by this changeset.</para> 16.183 </listitem> 16.184 - <listitem><para><literal role="template-keyword">node</literal>: 16.185 + <listitem><para id="x_591"><literal role="template-keyword">node</literal>: 16.186 String. The changeset identification hash, as a 16.187 40-character hexadecimal string.</para> 16.188 </listitem> 16.189 - <listitem><para><literal 16.190 + <listitem><para id="x_592"><literal 16.191 role="template-keyword">parents</literal>: List of 16.192 strings. The parents of the changeset.</para> 16.193 </listitem> 16.194 - <listitem><para><literal role="template-keyword">rev</literal>: 16.195 + <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: 16.196 Integer. The repository-local changeset revision 16.197 number.</para> 16.198 </listitem> 16.199 - <listitem><para><literal role="template-keyword">tags</literal>: 16.200 + <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: 16.201 List of strings. Any tags associated with the 16.202 changeset.</para> 16.203 </listitem></itemizedlist> 16.204 16.205 - <para>A few simple experiments will show us what to expect when we 16.206 + <para id="x_595">A few simple experiments will show us what to expect when we 16.207 use these keywords; you can see the results below.</para> 16.208 16.209 &interaction.template.simple.keywords; 16.210 16.211 - <para>As we noted above, the date keyword does not produce 16.212 + <para id="x_596">As we noted above, the date keyword does not produce 16.213 human-readable output, so we must treat it specially. This 16.214 involves using a <emphasis>filter</emphasis>, about which more 16.215 in section <xref 16.216 @@ -206,39 +206,39 @@ 16.217 <sect1 id="sec:template:escape"> 16.218 <title>Escape sequences</title> 16.219 16.220 - <para>Mercurial's templating engine recognises the most commonly 16.221 + <para id="x_597">Mercurial's templating engine recognises the most commonly 16.222 used escape sequences in strings. When it sees a backslash 16.223 (<quote><literal>\</literal></quote>) character, it looks at the 16.224 following character and substitutes the two characters with a 16.225 single replacement, as described below.</para> 16.226 16.227 <itemizedlist> 16.228 - <listitem><para><literal>\</literal>: 16.229 + <listitem><para id="x_598"><literal>\</literal>: 16.230 Backslash, <quote><literal>\</literal></quote>, ASCII 16.231 134.</para> 16.232 </listitem> 16.233 - <listitem><para><literal>\n</literal>: Newline, 16.234 + <listitem><para id="x_599"><literal>\n</literal>: Newline, 16.235 ASCII 12.</para> 16.236 </listitem> 16.237 - <listitem><para><literal>\r</literal>: Carriage 16.238 + <listitem><para id="x_59a"><literal>\r</literal>: Carriage 16.239 return, ASCII 15.</para> 16.240 </listitem> 16.241 - <listitem><para><literal>\t</literal>: Tab, ASCII 16.242 + <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII 16.243 11.</para> 16.244 </listitem> 16.245 - <listitem><para><literal>\v</literal>: Vertical 16.246 + <listitem><para id="x_59c"><literal>\v</literal>: Vertical 16.247 tab, ASCII 13.</para> 16.248 </listitem> 16.249 - <listitem><para><literal>{</literal>: Open curly 16.250 + <listitem><para id="x_59d"><literal>{</literal>: Open curly 16.251 brace, <quote><literal>{</literal></quote>, ASCII 16.252 173.</para> 16.253 </listitem> 16.254 - <listitem><para><literal>}</literal>: Close curly 16.255 + <listitem><para id="x_59e"><literal>}</literal>: Close curly 16.256 brace, <quote><literal>}</literal></quote>, ASCII 16.257 175.</para> 16.258 </listitem></itemizedlist> 16.259 16.260 - <para>As indicated above, if you want the expansion of a template 16.261 + <para id="x_59f">As indicated above, if you want the expansion of a template 16.262 to contain a literal <quote><literal>\</literal></quote>, 16.263 <quote><literal>{</literal></quote>, or 16.264 <quote><literal>{</literal></quote> character, you must escape 16.265 @@ -248,35 +248,35 @@ 16.266 <sect1 id="sec:template:filter"> 16.267 <title>Filtering keywords to change their results</title> 16.268 16.269 - <para>Some of the results of template expansion are not 16.270 + <para id="x_5a0">Some of the results of template expansion are not 16.271 immediately easy to use. Mercurial lets you specify an optional 16.272 chain of <emphasis>filters</emphasis> to modify the result of 16.273 expanding a keyword. You have already seen a common filter, 16.274 <literal role="template-kw-filt-date">isodate</literal>, in 16.275 action above, to make a date readable.</para> 16.276 16.277 - <para>Below is a list of the most commonly used filters that 16.278 + <para id="x_5a1">Below is a list of the most commonly used filters that 16.279 Mercurial supports. While some filters can be applied to any 16.280 text, others can only be used in specific circumstances. The 16.281 name of each filter is followed first by an indication of where 16.282 it can be used, then a description of its effect.</para> 16.283 16.284 <itemizedlist> 16.285 - <listitem><para><literal 16.286 + <listitem><para id="x_5a2"><literal 16.287 role="template-filter">addbreaks</literal>: Any text. Add 16.288 an XHTML <quote><literal><br/></literal></quote> tag 16.289 before the end of every line except the last. For example, 16.290 <quote><literal>foo\nbar</literal></quote> becomes 16.291 <quote><literal>foo<br/>\nbar</literal></quote>.</para> 16.292 </listitem> 16.293 - <listitem><para><literal 16.294 + <listitem><para id="x_5a3"><literal 16.295 role="template-kw-filt-date">age</literal>: <literal 16.296 role="template-keyword">date</literal> keyword. Render 16.297 the age of the date, relative to the current time. Yields a 16.298 string like <quote><literal>10 16.299 minutes</literal></quote>.</para> 16.300 </listitem> 16.301 - <listitem><para><literal 16.302 + <listitem><para id="x_5a4"><literal 16.303 role="template-filter">basename</literal>: Any text, but 16.304 most useful for the <literal 16.305 role="template-keyword">files</literal> keyword and its 16.306 @@ -285,7 +285,7 @@ 16.307 <quote><literal>foo/bar/baz</literal></quote> becomes 16.308 <quote><literal>baz</literal></quote>.</para> 16.309 </listitem> 16.310 - <listitem><para><literal 16.311 + <listitem><para id="x_5a5"><literal 16.312 role="template-kw-filt-date">date</literal>: <literal 16.313 role="template-keyword">date</literal> keyword. Render a 16.314 date in a similar format to the Unix <literal 16.315 @@ -293,7 +293,7 @@ 16.316 timezone included. Yields a string like <quote><literal>Mon 16.317 Sep 04 15:13:13 2006 -0700</literal></quote>.</para> 16.318 </listitem> 16.319 - <listitem><para><literal 16.320 + <listitem><para id="x_5a6"><literal 16.321 role="template-kw-filt-author">domain</literal>: Any text, 16.322 but most useful for the <literal 16.323 role="template-keyword">author</literal> keyword. Finds 16.324 @@ -303,7 +303,7 @@ 16.325 <bos@serpentine.com></literal></quote> becomes 16.326 <quote><literal>serpentine.com</literal></quote>.</para> 16.327 </listitem> 16.328 - <listitem><para><literal 16.329 + <listitem><para id="x_5a7"><literal 16.330 role="template-kw-filt-author">email</literal>: Any text, 16.331 but most useful for the <literal 16.332 role="template-keyword">author</literal> keyword. Extract 16.333 @@ -312,7 +312,7 @@ 16.334 <bos@serpentine.com></literal></quote> becomes 16.335 <quote><literal>bos@serpentine.com</literal></quote>.</para> 16.336 </listitem> 16.337 - <listitem><para><literal 16.338 + <listitem><para id="x_5a8"><literal 16.339 role="template-filter">escape</literal>: Any text. 16.340 Replace the special XML/XHTML characters 16.341 <quote><literal>&</literal></quote>, 16.342 @@ -320,7 +320,7 @@ 16.343 <quote><literal>></literal></quote> with XML 16.344 entities.</para> 16.345 </listitem> 16.346 - <listitem><para><literal 16.347 + <listitem><para id="x_5a9"><literal 16.348 role="template-filter">fill68</literal>: Any text. Wrap 16.349 the text to fit in 68 columns. This is useful before you 16.350 pass text through the <literal 16.351 @@ -328,30 +328,30 @@ 16.352 still want it to fit in an 80-column fixed-font 16.353 window.</para> 16.354 </listitem> 16.355 - <listitem><para><literal 16.356 + <listitem><para id="x_5aa"><literal 16.357 role="template-filter">fill76</literal>: Any text. Wrap 16.358 the text to fit in 76 columns.</para> 16.359 </listitem> 16.360 - <listitem><para><literal 16.361 + <listitem><para id="x_5ab"><literal 16.362 role="template-filter">firstline</literal>: Any text. 16.363 Yield the first line of text, without any trailing 16.364 newlines.</para> 16.365 </listitem> 16.366 - <listitem><para><literal 16.367 + <listitem><para id="x_5ac"><literal 16.368 role="template-kw-filt-date">hgdate</literal>: <literal 16.369 role="template-keyword">date</literal> keyword. Render 16.370 the date as a pair of readable numbers. Yields a string 16.371 like <quote><literal>1157407993 16.372 25200</literal></quote>.</para> 16.373 </listitem> 16.374 - <listitem><para><literal 16.375 + <listitem><para id="x_5ad"><literal 16.376 role="template-kw-filt-date">isodate</literal>: <literal 16.377 role="template-keyword">date</literal> keyword. Render 16.378 the date as a text string in ISO 8601 format. Yields a 16.379 string like <quote><literal>2006-09-04 15:13:13 16.380 -0700</literal></quote>.</para> 16.381 </listitem> 16.382 - <listitem><para><literal 16.383 + <listitem><para id="x_5ae"><literal 16.384 role="template-filter">obfuscate</literal>: Any text, but 16.385 most useful for the <literal 16.386 role="template-keyword">author</literal> keyword. Yield 16.387 @@ -359,7 +359,7 @@ 16.388 helps to defeat some particularly stupid screen-scraping 16.389 email harvesting spambots.</para> 16.390 </listitem> 16.391 - <listitem><para><literal 16.392 + <listitem><para id="x_5af"><literal 16.393 role="template-kw-filt-author">person</literal>: Any text, 16.394 but most useful for the <literal 16.395 role="template-keyword">author</literal> keyword. Yield 16.396 @@ -368,41 +368,41 @@ 16.397 <bos@serpentine.com></literal></quote> becomes 16.398 <quote><literal>Bryan O'Sullivan</literal></quote>.</para> 16.399 </listitem> 16.400 - <listitem><para><literal 16.401 + <listitem><para id="x_5b0"><literal 16.402 role="template-kw-filt-date">rfc822date</literal>: 16.403 <literal role="template-keyword">date</literal> keyword. 16.404 Render a date using the same format used in email headers. 16.405 Yields a string like <quote><literal>Mon, 04 Sep 2006 16.406 15:13:13 -0700</literal></quote>.</para> 16.407 </listitem> 16.408 - <listitem><para><literal 16.409 + <listitem><para id="x_5b1"><literal 16.410 role="template-kw-filt-node">short</literal>: Changeset 16.411 hash. Yield the short form of a changeset hash, i.e. a 16.412 12-character hexadecimal string.</para> 16.413 </listitem> 16.414 - <listitem><para><literal 16.415 + <listitem><para id="x_5b2"><literal 16.416 role="template-kw-filt-date">shortdate</literal>: <literal 16.417 role="template-keyword">date</literal> keyword. Render 16.418 the year, month, and day of the date. Yields a string like 16.419 <quote><literal>2006-09-04</literal></quote>.</para> 16.420 </listitem> 16.421 - <listitem><para><literal role="template-filter">strip</literal>: 16.422 + <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: 16.423 Any text. Strip all leading and trailing whitespace from 16.424 the string.</para> 16.425 </listitem> 16.426 - <listitem><para><literal 16.427 + <listitem><para id="x_5b4"><literal 16.428 role="template-filter">tabindent</literal>: Any text. 16.429 Yield the text, with every line except the first starting 16.430 with a tab character.</para> 16.431 </listitem> 16.432 - <listitem><para><literal 16.433 + <listitem><para id="x_5b5"><literal 16.434 role="template-filter">urlescape</literal>: Any text. 16.435 Escape all characters that are considered 16.436 <quote>special</quote> by URL parsers. For example, 16.437 <literal>foo bar</literal> becomes 16.438 <literal>foo%20bar</literal>.</para> 16.439 </listitem> 16.440 - <listitem><para><literal 16.441 + <listitem><para id="x_5b6"><literal 16.442 role="template-kw-filt-author">user</literal>: Any text, 16.443 but most useful for the <literal 16.444 role="template-keyword">author</literal> keyword. Return 16.445 @@ -415,7 +415,7 @@ 16.446 &interaction.template.simple.manyfilters; 16.447 16.448 <note> 16.449 - <para> If you try to apply a filter to a piece of data that it 16.450 + <para id="x_5b7"> If you try to apply a filter to a piece of data that it 16.451 cannot process, Mercurial will fail and print a Python 16.452 exception. For example, trying to run the output of the 16.453 <literal role="template-keyword">desc</literal> keyword into 16.454 @@ -426,7 +426,7 @@ 16.455 <sect2> 16.456 <title>Combining filters</title> 16.457 16.458 - <para>It is easy to combine filters to yield output in the form 16.459 + <para id="x_5b8">It is easy to combine filters to yield output in the form 16.460 you would like. The following chain of filters tidies up a 16.461 description, then makes sure that it fits cleanly into 68 16.462 columns, then indents it by a further 8 characters (at least 16.463 @@ -435,13 +435,13 @@ 16.464 16.465 &interaction.template.simple.combine; 16.466 16.467 - <para>Note the use of <quote><literal>\t</literal></quote> (a 16.468 + <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a 16.469 tab character) in the template to force the first line to be 16.470 indented; this is necessary since <literal 16.471 role="template-keyword">tabindent</literal> indents all 16.472 lines <emphasis>except</emphasis> the first.</para> 16.473 16.474 - <para>Keep in mind that the order of filters in a chain is 16.475 + <para id="x_5ba">Keep in mind that the order of filters in a chain is 16.476 significant. The first filter is applied to the result of the 16.477 keyword; the second to the result of the first filter; and so 16.478 on. For example, using <literal>fill68|tabindent</literal> 16.479 @@ -454,12 +454,12 @@ 16.480 <sect1> 16.481 <title>From templates to styles</title> 16.482 16.483 - <para>A command line template provides a quick and simple way to 16.484 + <para id="x_5bb">A command line template provides a quick and simple way to 16.485 format some output. Templates can become verbose, though, and 16.486 it's useful to be able to give a template a name. A style file 16.487 is a template with a name, stored in a file.</para> 16.488 16.489 - <para>More than that, using a style file unlocks the power of 16.490 + <para id="x_5bc">More than that, using a style file unlocks the power of 16.491 Mercurial's templating engine in ways that are not possible 16.492 using the command line <option 16.493 role="hg-opt-log">--template</option> option.</para> 16.494 @@ -467,11 +467,11 @@ 16.495 <sect2> 16.496 <title>The simplest of style files</title> 16.497 16.498 - <para>Our simple style file contains just one line:</para> 16.499 + <para id="x_5bd">Our simple style file contains just one line:</para> 16.500 16.501 &interaction.template.simple.rev; 16.502 16.503 - <para>This tells Mercurial, <quote>if you're printing a 16.504 + <para id="x_5be">This tells Mercurial, <quote>if you're printing a 16.505 changeset, use the text on the right as the 16.506 template</quote>.</para> 16.507 16.508 @@ -479,38 +479,38 @@ 16.509 <sect2> 16.510 <title>Style file syntax</title> 16.511 16.512 - <para>The syntax rules for a style file are simple.</para> 16.513 + <para id="x_5bf">The syntax rules for a style file are simple.</para> 16.514 16.515 <itemizedlist> 16.516 - <listitem><para>The file is processed one line at a 16.517 + <listitem><para id="x_5c0">The file is processed one line at a 16.518 time.</para> 16.519 </listitem> 16.520 - <listitem><para>Leading and trailing white space are 16.521 + <listitem><para id="x_5c1">Leading and trailing white space are 16.522 ignored.</para> 16.523 </listitem> 16.524 - <listitem><para>Empty lines are skipped.</para> 16.525 - </listitem> 16.526 - <listitem><para>If a line starts with either of the characters 16.527 + <listitem><para id="x_5c2">Empty lines are skipped.</para> 16.528 + </listitem> 16.529 + <listitem><para id="x_5c3">If a line starts with either of the characters 16.530 <quote><literal>#</literal></quote> or 16.531 <quote><literal>;</literal></quote>, the entire line is 16.532 treated as a comment, and skipped as if empty.</para> 16.533 </listitem> 16.534 - <listitem><para>A line starts with a keyword. This must start 16.535 + <listitem><para id="x_5c4">A line starts with a keyword. This must start 16.536 with an alphabetic character or underscore, and can 16.537 subsequently contain any alphanumeric character or 16.538 underscore. (In regexp notation, a keyword must match 16.539 <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para> 16.540 </listitem> 16.541 - <listitem><para>The next element must be an 16.542 + <listitem><para id="x_5c5">The next element must be an 16.543 <quote><literal>=</literal></quote> character, which can 16.544 be preceded or followed by an arbitrary amount of white 16.545 space.</para> 16.546 </listitem> 16.547 - <listitem><para>If the rest of the line starts and ends with 16.548 + <listitem><para id="x_5c6">If the rest of the line starts and ends with 16.549 matching quote characters (either single or double quote), 16.550 it is treated as a template body.</para> 16.551 </listitem> 16.552 - <listitem><para>If the rest of the line <emphasis>does 16.553 + <listitem><para id="x_5c7">If the rest of the line <emphasis>does 16.554 not</emphasis> start with a quote character, it is 16.555 treated as the name of a file; the contents of this file 16.556 will be read and used as a template body.</para> 16.557 @@ -521,7 +521,7 @@ 16.558 <sect1> 16.559 <title>Style files by example</title> 16.560 16.561 - <para>To illustrate how to write a style file, we will construct a 16.562 + <para id="x_5c8">To illustrate how to write a style file, we will construct a 16.563 few by example. Rather than provide a complete style file and 16.564 walk through it, we'll mirror the usual process of developing a 16.565 style file by starting with something very simple, and walking 16.566 @@ -530,40 +530,40 @@ 16.567 <sect2> 16.568 <title>Identifying mistakes in style files</title> 16.569 16.570 - <para>If Mercurial encounters a problem in a style file you are 16.571 + <para id="x_5c9">If Mercurial encounters a problem in a style file you are 16.572 working on, it prints a terse error message that, once you 16.573 figure out what it means, is actually quite useful.</para> 16.574 16.575 &interaction.template.svnstyle.syntax.input; 16.576 16.577 - <para>Notice that <filename>broken.style</filename> attempts to 16.578 + <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to 16.579 define a <literal>changeset</literal> keyword, but forgets to 16.580 give any content for it. When instructed to use this style 16.581 file, Mercurial promptly complains.</para> 16.582 16.583 &interaction.template.svnstyle.syntax.error; 16.584 16.585 - <para>This error message looks intimidating, but it is not too 16.586 + <para id="x_5cb">This error message looks intimidating, but it is not too 16.587 hard to follow.</para> 16.588 16.589 <itemizedlist> 16.590 - <listitem><para>The first component is simply Mercurial's way 16.591 + <listitem><para id="x_5cc">The first component is simply Mercurial's way 16.592 of saying <quote>I am giving up</quote>.</para> 16.593 <programlisting>___abort___: broken.style:1: parse error</programlisting> 16.594 </listitem> 16.595 - <listitem><para>Next comes the name of the style file that 16.596 + <listitem><para id="x_5cd">Next comes the name of the style file that 16.597 contains the error.</para> 16.598 <programlisting>abort: ___broken.style___:1: parse error</programlisting> 16.599 </listitem> 16.600 - <listitem><para>Following the file name is the line number 16.601 + <listitem><para id="x_5ce">Following the file name is the line number 16.602 where the error was encountered.</para> 16.603 <programlisting>abort: broken.style:___1___: parse error</programlisting> 16.604 </listitem> 16.605 - <listitem><para>Finally, a description of what went 16.606 + <listitem><para id="x_5cf">Finally, a description of what went 16.607 wrong.</para> 16.608 <programlisting>abort: broken.style:1: ___parse error___</programlisting> 16.609 </listitem> 16.610 - <listitem><para>The description of the problem is not always 16.611 + <listitem><para id="x_5d0">The description of the problem is not always 16.612 clear (as in this case), but even when it is cryptic, it 16.613 is almost always trivial to visually inspect the offending 16.614 line in the style file and see what is wrong.</para> 16.615 @@ -573,32 +573,32 @@ 16.616 <sect2> 16.617 <title>Uniquely identifying a repository</title> 16.618 16.619 - <para>If you would like to be able to identify a Mercurial 16.620 + <para id="x_5d1">If you would like to be able to identify a Mercurial 16.621 repository <quote>fairly uniquely</quote> using a short string 16.622 as an identifier, you can use the first revision in the 16.623 repository.</para> 16.624 16.625 &interaction.template.svnstyle.id; 16.626 16.627 - <para>This is not guaranteed to be unique, but it is 16.628 + <para id="x_5d2">This is not guaranteed to be unique, but it is 16.629 nevertheless useful in many cases.</para> 16.630 <itemizedlist> 16.631 - <listitem><para>It will not work in a completely empty 16.632 + <listitem><para id="x_5d3">It will not work in a completely empty 16.633 repository, because such a repository does not have a 16.634 revision zero.</para> 16.635 </listitem> 16.636 - <listitem><para>Neither will it work in the (extremely rare) 16.637 + <listitem><para id="x_5d4">Neither will it work in the (extremely rare) 16.638 case where a repository is a merge of two or more formerly 16.639 independent repositories, and you still have those 16.640 repositories around.</para> 16.641 </listitem></itemizedlist> 16.642 - <para>Here are some uses to which you could put this 16.643 + <para id="x_5d5">Here are some uses to which you could put this 16.644 identifier:</para> 16.645 <itemizedlist> 16.646 - <listitem><para>As a key into a table for a database that 16.647 + <listitem><para id="x_5d6">As a key into a table for a database that 16.648 manages repositories on a server.</para> 16.649 </listitem> 16.650 - <listitem><para>As half of a {<emphasis>repository 16.651 + <listitem><para id="x_5d7">As half of a {<emphasis>repository 16.652 ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 16.653 Save this information away when you run an automated build 16.654 or other activity, so that you can <quote>replay</quote> 16.655 @@ -609,29 +609,29 @@ 16.656 <sect2> 16.657 <title>Mimicking Subversion's output</title> 16.658 16.659 - <para>Let's try to emulate the default output format used by 16.660 + <para id="x_5d8">Let's try to emulate the default output format used by 16.661 another revision control tool, Subversion.</para> 16.662 16.663 &interaction.template.svnstyle.short; 16.664 16.665 - <para>Since Subversion's output style is fairly simple, it is 16.666 + <para id="x_5d9">Since Subversion's output style is fairly simple, it is 16.667 easy to copy-and-paste a hunk of its output into a file, and 16.668 replace the text produced above by Subversion with the 16.669 template values we'd like to see expanded.</para> 16.670 16.671 &interaction.template.svnstyle.template; 16.672 16.673 - <para>There are a few small ways in which this template deviates 16.674 + <para id="x_5da">There are a few small ways in which this template deviates 16.675 from the output produced by Subversion.</para> 16.676 <itemizedlist> 16.677 - <listitem><para>Subversion prints a <quote>readable</quote> 16.678 + <listitem><para id="x_5db">Subversion prints a <quote>readable</quote> 16.679 date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the 16.680 example output above) in parentheses. Mercurial's 16.681 templating engine does not provide a way to display a date 16.682 in this format without also printing the time and time 16.683 zone.</para> 16.684 </listitem> 16.685 - <listitem><para>We emulate Subversion's printing of 16.686 + <listitem><para id="x_5dc">We emulate Subversion's printing of 16.687 <quote>separator</quote> lines full of 16.688 <quote><literal>-</literal></quote> characters by ending 16.689 the template with such a line. We use the templating 16.690 @@ -640,20 +640,20 @@ 16.691 output (see below), thus achieving similar output to 16.692 Subversion.</para> 16.693 </listitem> 16.694 - <listitem><para>Subversion's output includes a count in the 16.695 + <listitem><para id="x_5dd">Subversion's output includes a count in the 16.696 header of the number of lines in the commit message. We 16.697 cannot replicate this in Mercurial; the templating engine 16.698 does not currently provide a filter that counts the number 16.699 of lines the template generates.</para> 16.700 </listitem></itemizedlist> 16.701 - <para>It took me no more than a minute or two of work to replace 16.702 + <para id="x_5de">It took me no more than a minute or two of work to replace 16.703 literal text from an example of Subversion's output with some 16.704 keywords and filters to give the template above. The style 16.705 file simply refers to the template.</para> 16.706 16.707 &interaction.template.svnstyle.style; 16.708 16.709 - <para>We could have included the text of the template file 16.710 + <para id="x_5df">We could have included the text of the template file 16.711 directly in the style file by enclosing it in quotes and 16.712 replacing the newlines with 16.713 <quote><literal>\n</literal></quote> sequences, but it would
17.1 --- a/en/ch11-mq.xml Thu Mar 19 20:54:12 2009 -0700 17.2 +++ b/en/ch11-mq.xml Thu Mar 19 21:18:52 2009 -0700 17.3 @@ -7,7 +7,7 @@ 17.4 <sect1 id="sec:mq:patch-mgmt"> 17.5 <title>The patch management problem</title> 17.6 17.7 - <para>Here is a common scenario: you need to install a software 17.8 + <para id="x_3ac">Here is a common scenario: you need to install a software 17.9 package from source, but you find a bug that you must fix in the 17.10 source before you can start using the package. You make your 17.11 changes, forget about the package for a while, and a few months 17.12 @@ -17,24 +17,24 @@ 17.13 the newer version. This is a tedious task, and it's easy to 17.14 make mistakes.</para> 17.15 17.16 - <para>This is a simple case of the <quote>patch management</quote> 17.17 + <para id="x_3ad">This is a simple case of the <quote>patch management</quote> 17.18 problem. You have an <quote>upstream</quote> source tree that 17.19 you can't change; you need to make some local changes on top of 17.20 the upstream tree; and you'd like to be able to keep those 17.21 changes separate, so that you can apply them to newer versions 17.22 of the upstream source.</para> 17.23 17.24 - <para>The patch management problem arises in many situations. 17.25 + <para id="x_3ae">The patch management problem arises in many situations. 17.26 Probably the most visible is that a user of an open source 17.27 software project will contribute a bug fix or new feature to the 17.28 project's maintainers in the form of a patch.</para> 17.29 17.30 - <para>Distributors of operating systems that include open source 17.31 + <para id="x_3af">Distributors of operating systems that include open source 17.32 software often need to make changes to the packages they 17.33 distribute so that they will build properly in their 17.34 environments.</para> 17.35 17.36 - <para>When you have few changes to maintain, it is easy to manage 17.37 + <para id="x_3b0">When you have few changes to maintain, it is easy to manage 17.38 a single patch using the standard <command>diff</command> and 17.39 <command>patch</command> programs (see section <xref 17.40 linkend="sec:mq:patch"/> for a discussion of these 17.41 @@ -49,14 +49,14 @@ 17.42 your fix in a subsequent release, you can simply drop that 17.43 single patch when you're updating to the newer release.</para> 17.44 17.45 - <para>Maintaining a single patch against an upstream tree is a 17.46 + <para id="x_3b1">Maintaining a single patch against an upstream tree is a 17.47 little tedious and error-prone, but not difficult. However, the 17.48 complexity of the problem grows rapidly as the number of patches 17.49 you have to maintain increases. With more than a tiny number of 17.50 patches in hand, understanding which ones you have applied and 17.51 maintaining them moves from messy to overwhelming.</para> 17.52 17.53 - <para>Fortunately, Mercurial includes a powerful extension, 17.54 + <para id="x_3b2">Fortunately, Mercurial includes a powerful extension, 17.55 Mercurial Queues (or simply <quote>MQ</quote>), that massively 17.56 simplifies the patch management problem.</para> 17.57 17.58 @@ -64,13 +64,13 @@ 17.59 <sect1 id="sec:mq:history"> 17.60 <title>The prehistory of Mercurial Queues</title> 17.61 17.62 - <para>During the late 1990s, several Linux kernel developers 17.63 + <para id="x_3b3">During the late 1990s, several Linux kernel developers 17.64 started to maintain <quote>patch series</quote> that modified 17.65 the behaviour of the Linux kernel. Some of these series were 17.66 focused on stability, some on feature coverage, and others were 17.67 more speculative.</para> 17.68 17.69 - <para>The sizes of these patch series grew rapidly. In 2002, 17.70 + <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002, 17.71 Andrew Morton published some shell scripts he had been using to 17.72 automate the task of managing his patch queues. Andrew was 17.73 successfully using these scripts to manage hundreds (sometimes 17.74 @@ -79,7 +79,7 @@ 17.75 <sect2 id="sec:mq:quilt"> 17.76 <title>A patchwork quilt</title> 17.77 17.78 - <para>In early 2003, Andreas Gruenbacher and Martin Quinson 17.79 + <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson 17.80 borrowed the approach of Andrew's scripts and published a tool 17.81 called <quote>patchwork quilt</quote> 17.82 <citation>web:quilt</citation>, or simply <quote>quilt</quote> 17.83 @@ -88,7 +88,7 @@ 17.84 management, it rapidly gained a large following among open 17.85 source software developers.</para> 17.86 17.87 - <para>Quilt manages a <emphasis>stack of patches</emphasis> on 17.88 + <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on 17.89 top of a directory tree. To begin, you tell quilt to manage a 17.90 directory tree, and tell it which files you want to manage; it 17.91 stores away the names and contents of those files. To fix a 17.92 @@ -96,14 +96,14 @@ 17.93 files you need to fix, then <quote>refresh</quote> the 17.94 patch.</para> 17.95 17.96 - <para>The refresh step causes quilt to scan the directory tree; 17.97 + <para id="x_3b7">The refresh step causes quilt to scan the directory tree; 17.98 it updates the patch with all of the changes you have made. 17.99 You can create another patch on top of the first, which will 17.100 track the changes required to modify the tree from <quote>tree 17.101 with one patch applied</quote> to <quote>tree with two 17.102 patches applied</quote>.</para> 17.103 17.104 - <para>You can <emphasis>change</emphasis> which patches are 17.105 + <para id="x_3b8">You can <emphasis>change</emphasis> which patches are 17.106 applied to the tree. If you <quote>pop</quote> a patch, the 17.107 changes made by that patch will vanish from the directory 17.108 tree. Quilt remembers which patches you have popped, though, 17.109 @@ -115,7 +115,7 @@ 17.110 any time, change both which patches are applied and what 17.111 modifications those patches make.</para> 17.112 17.113 - <para>Quilt knows nothing about revision control tools, so it 17.114 + <para id="x_3b9">Quilt knows nothing about revision control tools, so it 17.115 works equally well on top of an unpacked tarball or a 17.116 Subversion working copy.</para> 17.117 17.118 @@ -123,17 +123,17 @@ 17.119 <sect2 id="sec:mq:quilt-mq"> 17.120 <title>From patchwork quilt to Mercurial Queues</title> 17.121 17.122 - <para>In mid-2005, Chris Mason took the features of quilt and 17.123 + <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and 17.124 wrote an extension that he called Mercurial Queues, which 17.125 added quilt-like behaviour to Mercurial.</para> 17.126 17.127 - <para>The key difference between quilt and MQ is that quilt 17.128 + <para id="x_3bb">The key difference between quilt and MQ is that quilt 17.129 knows nothing about revision control systems, while MQ is 17.130 <emphasis>integrated</emphasis> into Mercurial. Each patch 17.131 that you push is represented as a Mercurial changeset. Pop a 17.132 patch, and the changeset goes away.</para> 17.133 17.134 - <para>Because quilt does not care about revision control tools, 17.135 + <para id="x_3bc">Because quilt does not care about revision control tools, 17.136 it is still a tremendously useful piece of software to know 17.137 about for situations where you cannot use Mercurial and 17.138 MQ.</para> 17.139 @@ -143,16 +143,16 @@ 17.140 <sect1> 17.141 <title>The huge advantage of MQ</title> 17.142 17.143 - <para>I cannot overstate the value that MQ offers through the 17.144 + <para id="x_3bd">I cannot overstate the value that MQ offers through the 17.145 unification of patches and revision control.</para> 17.146 17.147 - <para>A major reason that patches have persisted in the free 17.148 + <para id="x_3be">A major reason that patches have persisted in the free 17.149 software and open source world&emdash;in spite of the 17.150 availability of increasingly capable revision control tools over 17.151 the years&emdash;is the <emphasis>agility</emphasis> they 17.152 offer.</para> 17.153 17.154 - <para>Traditional revision control tools make a permanent, 17.155 + <para id="x_3bf">Traditional revision control tools make a permanent, 17.156 irreversible record of everything that you do. While this has 17.157 great value, it's also somewhat stifling. If you want to 17.158 perform a wild-eyed experiment, you have to be careful in how 17.159 @@ -160,7 +160,7 @@ 17.160 misleading or destabilising&emdash;traces of your missteps and 17.161 errors in the permanent revision record.</para> 17.162 17.163 - <para>By contrast, MQ's marriage of distributed revision control 17.164 + <para id="x_3c0">By contrast, MQ's marriage of distributed revision control 17.165 with patches makes it much easier to isolate your work. Your 17.166 patches live on top of normal revision history, and you can make 17.167 them disappear or reappear at will. If you don't like a patch, 17.168 @@ -168,7 +168,7 @@ 17.169 simply fix it&emdash;as many times as you need to, until you 17.170 have refined it into the form you desire.</para> 17.171 17.172 - <para>As an example, the integration of patches with revision 17.173 + <para id="x_3c1">As an example, the integration of patches with revision 17.174 control makes understanding patches and debugging their 17.175 effects&emdash;and their interplay with the code they're based 17.176 on&emdash;<emphasis>enormously</emphasis> easier. Since every 17.177 @@ -186,11 +186,11 @@ 17.178 <sect1 id="sec:mq:patch"> 17.179 <title>Understanding patches</title> 17.180 17.181 - <para>Because MQ doesn't hide its patch-oriented nature, it is 17.182 + <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is 17.183 helpful to understand what patches are, and a little about the 17.184 tools that work with them.</para> 17.185 17.186 - <para>The traditional Unix <command>diff</command> command 17.187 + <para id="x_3c3">The traditional Unix <command>diff</command> command 17.188 compares two files, and prints a list of differences between 17.189 them. The <command>patch</command> command understands these 17.190 differences as <emphasis>modifications</emphasis> to make to a 17.191 @@ -199,20 +199,20 @@ 17.192 17.193 &interaction.mq.dodiff.diff; 17.194 17.195 - <para>The type of file that <command>diff</command> generates (and 17.196 + <para id="x_3c4">The type of file that <command>diff</command> generates (and 17.197 <command>patch</command> takes as input) is called a 17.198 <quote>patch</quote> or a <quote>diff</quote>; there is no 17.199 difference between a patch and a diff. (We'll use the term 17.200 <quote>patch</quote>, since it's more commonly used.)</para> 17.201 17.202 - <para>A patch file can start with arbitrary text; the 17.203 + <para id="x_3c5">A patch file can start with arbitrary text; the 17.204 <command>patch</command> command ignores this text, but MQ uses 17.205 it as the commit message when creating changesets. To find the 17.206 beginning of the patch content, <command>patch</command> 17.207 searches for the first line that starts with the string 17.208 <quote><literal>diff -</literal></quote>.</para> 17.209 17.210 - <para>MQ works with <emphasis>unified</emphasis> diffs 17.211 + <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs 17.212 (<command>patch</command> can accept several other diff formats, 17.213 but MQ doesn't). A unified diff contains two kinds of header. 17.214 The <emphasis>file header</emphasis> describes the file being 17.215 @@ -220,7 +220,7 @@ 17.216 <command>patch</command> sees a new file header, it looks for a 17.217 file with that name to start modifying.</para> 17.218 17.219 - <para>After the file header comes a series of 17.220 + <para id="x_3c7">After the file header comes a series of 17.221 <emphasis>hunks</emphasis>. Each hunk starts with a header; 17.222 this identifies the range of line numbers within the file that 17.223 the hunk should modify. Following the header, a hunk starts and 17.224 @@ -232,7 +232,7 @@ 17.225 runs the hunks together, with a few lines of context between 17.226 modifications.</para> 17.227 17.228 - <para>Each line of context begins with a space character. Within 17.229 + <para id="x_3c8">Each line of context begins with a space character. Within 17.230 the hunk, a line that begins with 17.231 <quote><literal>-</literal></quote> means <quote>remove this 17.232 line,</quote> while a line that begins with 17.233 @@ -240,7 +240,7 @@ 17.234 line.</quote> For example, a line that is modified is 17.235 represented by one deletion and one insertion.</para> 17.236 17.237 - <para>We will return to some of the more subtle aspects of patches 17.238 + <para id="x_3c9">We will return to some of the more subtle aspects of patches 17.239 later (in section <xref linkend="sec:mq:adv-patch"/>), but you 17.240 should have 17.241 enough information now to use MQ.</para> 17.242 @@ -249,7 +249,7 @@ 17.243 <sect1 id="sec:mq:start"> 17.244 <title>Getting started with Mercurial Queues</title> 17.245 17.246 - <para>Because MQ is implemented as an extension, you must 17.247 + <para id="x_3ca">Because MQ is implemented as an extension, you must 17.248 explicitly enable before you can use it. (You don't need to 17.249 download anything; MQ ships with the standard Mercurial 17.250 distribution.) To enable MQ, edit your <filename 17.251 @@ -259,7 +259,7 @@ 17.252 <programlisting>[extensions] 17.253 hgext.mq =</programlisting> 17.254 17.255 - <para>Once the extension is enabled, it will make a number of new 17.256 + <para id="x_3cb">Once the extension is enabled, it will make a number of new 17.257 commands available. To verify that the extension is working, 17.258 you can use <command role="hg-cmd">hg help</command> to see if 17.259 the <command role="hg-ext-mq">qinit</command> command is now 17.260 @@ -267,14 +267,14 @@ 17.261 17.262 &interaction.mq.qinit-help.help; 17.263 17.264 - <para>You can use MQ with <emphasis>any</emphasis> Mercurial 17.265 + <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 17.266 repository, and its commands only operate within that 17.267 repository. To get started, simply prepare the repository using 17.268 the <command role="hg-ext-mq">qinit</command> command.</para> 17.269 17.270 &interaction.mq.tutorial.qinit; 17.271 17.272 - <para>This command creates an empty directory called <filename 17.273 + <para id="x_3cd">This command creates an empty directory called <filename 17.274 role="special" class="directory">.hg/patches</filename>, where 17.275 MQ will keep its metadata. As with many Mercurial commands, the 17.276 <command role="hg-ext-mq">qinit</command> command prints nothing 17.277 @@ -283,18 +283,18 @@ 17.278 <sect2> 17.279 <title>Creating a new patch</title> 17.280 17.281 - <para>To begin work on a new patch, use the <command 17.282 + <para id="x_3ce">To begin work on a new patch, use the <command 17.283 role="hg-ext-mq">qnew</command> command. This command takes 17.284 one argument, the name of the patch to create.</para> 17.285 17.286 - <para>MQ will use this as the name of an actual file in the 17.287 + <para id="x_3cf">MQ will use this as the name of an actual file in the 17.288 <filename role="special" 17.289 class="directory">.hg/patches</filename> directory, as you 17.290 can see below.</para> 17.291 17.292 &interaction.mq.tutorial.qnew; 17.293 17.294 - <para>Also newly present in the <filename role="special" 17.295 + <para id="x_3d0">Also newly present in the <filename role="special" 17.296 class="directory">.hg/patches</filename> directory are two 17.297 other files, <filename role="special">series</filename> and 17.298 <filename role="special">status</filename>. The <filename 17.299 @@ -306,7 +306,7 @@ 17.300 <emphasis>applied</emphasis> in this repository.</para> 17.301 17.302 <note> 17.303 - <para> You may sometimes want to edit the <filename 17.304 + <para id="x_3d1"> You may sometimes want to edit the <filename 17.305 role="special">series</filename> file by hand; for 17.306 example, to change the sequence in which some patches are 17.307 applied. However, manually editing the <filename 17.308 @@ -315,7 +315,7 @@ 17.309 happening.</para> 17.310 </note> 17.311 17.312 - <para>Once you have created your new patch, you can edit files 17.313 + <para id="x_3d2">Once you have created your new patch, you can edit files 17.314 in the working directory as you usually would. All of the 17.315 normal Mercurial commands, such as <command role="hg-cmd">hg 17.316 diff</command> and <command role="hg-cmd">hg 17.317 @@ -325,17 +325,17 @@ 17.318 <sect2> 17.319 <title>Refreshing a patch</title> 17.320 17.321 - <para>When you reach a point where you want to save your work, 17.322 + <para id="x_3d3">When you reach a point where you want to save your work, 17.323 use the <command role="hg-ext-mq">qrefresh</command> command 17.324 to update the patch you are working on.</para> 17.325 17.326 &interaction.mq.tutorial.qrefresh; 17.327 17.328 - <para>This command folds the changes you have made in the 17.329 + <para id="x_3d4">This command folds the changes you have made in the 17.330 working directory into your patch, and updates its 17.331 corresponding changeset to contain those changes.</para> 17.332 17.333 - <para>You can run <command role="hg-ext-mq">qrefresh</command> 17.334 + <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command> 17.335 as often as you like, so it's a good way to 17.336 <quote>checkpoint</quote> your work. Refresh your patch at an 17.337 opportune time; try an experiment; and if the experiment 17.338 @@ -348,19 +348,19 @@ 17.339 <sect2> 17.340 <title>Stacking and tracking patches</title> 17.341 17.342 - <para>Once you have finished working on a patch, or need to work 17.343 + <para id="x_3d6">Once you have finished working on a patch, or need to work 17.344 on another, you can use the <command 17.345 role="hg-ext-mq">qnew</command> command again to create a 17.346 new patch. Mercurial will apply this patch on top of your 17.347 existing patch.</para> 17.348 17.349 &interaction.mq.tutorial.qnew2; 17.350 - <para>Notice that the patch contains the changes in our prior 17.351 + <para id="x_3d7">Notice that the patch contains the changes in our prior 17.352 patch as part of its context (you can see this more clearly in 17.353 the output of <command role="hg-cmd">hg 17.354 annotate</command>).</para> 17.355 17.356 - <para>So far, with the exception of <command 17.357 + <para id="x_3d8">So far, with the exception of <command 17.358 role="hg-ext-mq">qnew</command> and <command 17.359 role="hg-ext-mq">qrefresh</command>, we've been careful to 17.360 only use regular Mercurial commands. However, MQ provides 17.361 @@ -370,13 +370,13 @@ 17.362 &interaction.mq.tutorial.qseries; 17.363 17.364 <itemizedlist> 17.365 - <listitem><para>The <command 17.366 + <listitem><para id="x_3d9">The <command 17.367 role="hg-ext-mq">qseries</command> command lists every 17.368 patch that MQ knows about in this repository, from oldest 17.369 to newest (most recently 17.370 <emphasis>created</emphasis>).</para> 17.371 </listitem> 17.372 - <listitem><para>The <command 17.373 + <listitem><para id="x_3da">The <command 17.374 role="hg-ext-mq">qapplied</command> command lists every 17.375 patch that MQ has <emphasis>applied</emphasis> in this 17.376 repository, again from oldest to newest (most recently 17.377 @@ -387,12 +387,12 @@ 17.378 <sect2> 17.379 <title>Manipulating the patch stack</title> 17.380 17.381 - <para>The previous discussion implied that there must be a 17.382 + <para id="x_3db">The previous discussion implied that there must be a 17.383 difference between <quote>known</quote> and 17.384 <quote>applied</quote> patches, and there is. MQ can manage a 17.385 patch without it being applied in the repository.</para> 17.386 17.387 - <para>An <emphasis>applied</emphasis> patch has a corresponding 17.388 + <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding 17.389 changeset in the repository, and the effects of the patch and 17.390 changeset are visible in the working directory. You can undo 17.391 the application of a patch using the <command 17.392 @@ -407,12 +407,12 @@ 17.393 <informalfigure id="fig:mq:stack"> 17.394 <mediaobject><imageobject><imagedata 17.395 fileref="mq-stack"/></imageobject><textobject><phrase>XXX 17.396 - add text</phrase></textobject><caption><para>Applied and 17.397 + add text</phrase></textobject><caption><para id="x_3dd">Applied and 17.398 unapplied patches in the MQ patch 17.399 stack</para></caption></mediaobject> 17.400 </informalfigure> 17.401 17.402 - <para>You can reapply an unapplied, or popped, patch using the 17.403 + <para id="x_3de">You can reapply an unapplied, or popped, patch using the 17.404 <command role="hg-ext-mq">qpush</command> command. This 17.405 creates a new changeset to correspond to the patch, and the 17.406 patch's changes once again become present in the working 17.407 @@ -421,7 +421,7 @@ 17.408 role="hg-ext-mq">qpush</command> in action.</para> 17.409 &interaction.mq.tutorial.qpop; 17.410 17.411 - <para>Notice that once we have popped a patch or two patches, 17.412 + <para id="x_3df">Notice that once we have popped a patch or two patches, 17.413 the output of <command role="hg-ext-mq">qseries</command> 17.414 remains the same, while that of <command 17.415 role="hg-ext-mq">qapplied</command> has changed.</para> 17.416 @@ -431,7 +431,7 @@ 17.417 <sect2> 17.418 <title>Pushing and popping many patches</title> 17.419 17.420 - <para>While <command role="hg-ext-mq">qpush</command> and 17.421 + <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and 17.422 <command role="hg-ext-mq">qpop</command> each operate on a 17.423 single patch at a time by default, you can push and pop many 17.424 patches in one go. The <option 17.425 @@ -450,7 +450,7 @@ 17.426 <sect2> 17.427 <title>Safety checks, and overriding them</title> 17.428 17.429 - <para>Several MQ commands check the working directory before 17.430 + <para id="x_3e1">Several MQ commands check the working directory before 17.431 they do anything, and fail if they find any modifications. 17.432 They do this to ensure that you won't lose any changes that 17.433 you have made, but not yet incorporated into a patch. The 17.434 @@ -462,7 +462,7 @@ 17.435 17.436 &interaction.mq.tutorial.add; 17.437 17.438 - <para>Commands that check the working directory all take an 17.439 + <para id="x_3e2">Commands that check the working directory all take an 17.440 <quote>I know what I'm doing</quote> option, which is always 17.441 named <option>-f</option>. The exact meaning of 17.442 <option>-f</option> depends on the command. For example, 17.443 @@ -479,14 +479,14 @@ 17.444 <sect2> 17.445 <title>Working on several patches at once</title> 17.446 17.447 - <para>The <command role="hg-ext-mq">qrefresh</command> command 17.448 + <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command 17.449 always refreshes the <emphasis>topmost</emphasis> applied 17.450 patch. This means that you can suspend work on one patch (by 17.451 refreshing it), pop or push to make a different patch the top, 17.452 and work on <emphasis>that</emphasis> patch for a 17.453 while.</para> 17.454 17.455 - <para>Here's an example that illustrates how you can use this 17.456 + <para id="x_3e4">Here's an example that illustrates how you can use this 17.457 ability. Let's say you're developing a new feature as two 17.458 patches. The first is a change to the core of your software, 17.459 and the second&emdash;layered on top of the 17.460 @@ -505,7 +505,7 @@ 17.461 <sect1 id="sec:mq:adv-patch"> 17.462 <title>More about patches</title> 17.463 17.464 - <para>MQ uses the GNU <command>patch</command> command to apply 17.465 + <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply 17.466 patches, so it's helpful to know a few more detailed aspects of 17.467 how <command>patch</command> works, and about patches 17.468 themselves.</para> 17.469 @@ -513,14 +513,14 @@ 17.470 <sect2> 17.471 <title>The strip count</title> 17.472 17.473 - <para>If you look at the file headers in a patch, you will 17.474 + <para id="x_3e6">If you look at the file headers in a patch, you will 17.475 notice that the pathnames usually have an extra component on 17.476 the front that isn't present in the actual path name. This is 17.477 a holdover from the way that people used to generate patches 17.478 (people still do this, but it's somewhat rare with modern 17.479 revision control tools).</para> 17.480 17.481 - <para>Alice would unpack a tarball, edit her files, then decide 17.482 + <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide 17.483 that she wanted to create a patch. So she'd rename her 17.484 working directory, unpack the tarball again (hence the need 17.485 for the rename), and use the <option 17.486 @@ -533,7 +533,7 @@ 17.487 header, and the name of the modified directory would be at the 17.488 front of the right-hand path.</para> 17.489 17.490 - <para>Since someone receiving a patch from the Alices of the net 17.491 + <para id="x_3e8">Since someone receiving a patch from the Alices of the net 17.492 would be unlikely to have unmodified and modified directories 17.493 with exactly the same names, the <command>patch</command> 17.494 command has a <option role="cmd-opt-patch">-p</option> option 17.495 @@ -541,7 +541,7 @@ 17.496 strip when trying to apply a patch. This number is called the 17.497 <emphasis>strip count</emphasis>.</para> 17.498 17.499 - <para>An option of <quote><literal>-p1</literal></quote> means 17.500 + <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means 17.501 <quote>use a strip count of one</quote>. If 17.502 <command>patch</command> sees a file name 17.503 <filename>foo/bar/baz</filename> in a file header, it will 17.504 @@ -554,7 +554,7 @@ 17.505 but <filename>/foo/bar</filename> (notice the extra leading 17.506 slash) into <filename>foo/bar</filename>.)</para> 17.507 17.508 - <para>The <quote>standard</quote> strip count for patches is 17.509 + <para id="x_3ea">The <quote>standard</quote> strip count for patches is 17.510 one; almost all patches contain one leading path name 17.511 component that needs to be stripped. Mercurial's <command 17.512 role="hg-cmd">hg diff</command> command generates path names 17.513 @@ -562,7 +562,7 @@ 17.514 import</command> command and MQ expect patches to have a 17.515 strip count of one.</para> 17.516 17.517 - <para>If you receive a patch from someone that you want to add 17.518 + <para id="x_3eb">If you receive a patch from someone that you want to add 17.519 to your patch queue, and the patch needs a strip count other 17.520 than one, you cannot just <command 17.521 role="hg-ext-mq">qimport</command> the patch, because 17.522 @@ -583,14 +583,14 @@ 17.523 <sect2> 17.524 <title>Strategies for applying a patch</title> 17.525 17.526 - <para>When <command>patch</command> applies a hunk, it tries a 17.527 + <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a 17.528 handful of successively less accurate strategies to try to 17.529 make the hunk apply. This falling-back technique often makes 17.530 it possible to take a patch that was generated against an old 17.531 version of a file, and apply it against a newer version of 17.532 that file.</para> 17.533 17.534 - <para>First, <command>patch</command> tries an exact match, 17.535 + <para id="x_3ed">First, <command>patch</command> tries an exact match, 17.536 where the line numbers, the context, and the text to be 17.537 modified must apply exactly. If it cannot make an exact 17.538 match, it tries to find an exact match for the context, 17.539 @@ -599,7 +599,7 @@ 17.540 applied, but at some <emphasis>offset</emphasis> from the 17.541 original line number.</para> 17.542 17.543 - <para>If a context-only match fails, <command>patch</command> 17.544 + <para id="x_3ee">If a context-only match fails, <command>patch</command> 17.545 removes the first and last lines of the context, and tries a 17.546 <emphasis>reduced</emphasis> context-only match. If the hunk 17.547 with reduced context succeeds, it prints a message saying that 17.548 @@ -608,7 +608,7 @@ 17.549 context <command>patch</command> had to trim before the patch 17.550 applied).</para> 17.551 17.552 - <para>When neither of these techniques works, 17.553 + <para id="x_3ef">When neither of these techniques works, 17.554 <command>patch</command> prints a message saying that the hunk 17.555 in question was rejected. It saves rejected hunks (also 17.556 simply called <quote>rejects</quote>) to a file with the same 17.557 @@ -628,36 +628,36 @@ 17.558 <sect2> 17.559 <title>Some quirks of patch representation</title> 17.560 17.561 - <para>There are a few useful things to know about how 17.562 + <para id="x_3f0">There are a few useful things to know about how 17.563 <command>patch</command> works with files.</para> 17.564 <itemizedlist> 17.565 - <listitem><para>This should already be obvious, but 17.566 + <listitem><para id="x_3f1">This should already be obvious, but 17.567 <command>patch</command> cannot handle binary 17.568 files.</para> 17.569 </listitem> 17.570 - <listitem><para>Neither does it care about the executable bit; 17.571 + <listitem><para id="x_3f2">Neither does it care about the executable bit; 17.572 it creates new files as readable, but not 17.573 executable.</para> 17.574 </listitem> 17.575 - <listitem><para><command>patch</command> treats the removal of 17.576 + <listitem><para id="x_3f3"><command>patch</command> treats the removal of 17.577 a file as a diff between the file to be removed and the 17.578 empty file. So your idea of <quote>I deleted this 17.579 file</quote> looks like <quote>every line of this file 17.580 was deleted</quote> in a patch.</para> 17.581 </listitem> 17.582 - <listitem><para>It treats the addition of a file as a diff 17.583 + <listitem><para id="x_3f4">It treats the addition of a file as a diff 17.584 between the empty file and the file to be added. So in a 17.585 patch, your idea of <quote>I added this file</quote> looks 17.586 like <quote>every line of this file was 17.587 added</quote>.</para> 17.588 </listitem> 17.589 - <listitem><para>It treats a renamed file as the removal of the 17.590 + <listitem><para id="x_3f5">It treats a renamed file as the removal of the 17.591 old name, and the addition of the new name. This means 17.592 that renamed files have a big footprint in patches. (Note 17.593 also that Mercurial does not currently try to infer when 17.594 files have been renamed or copied in a patch.)</para> 17.595 </listitem> 17.596 - <listitem><para><command>patch</command> cannot represent 17.597 + <listitem><para id="x_3f6"><command>patch</command> cannot represent 17.598 empty files, so you cannot use a patch to represent the 17.599 notion <quote>I added this empty file to the 17.600 tree</quote>.</para> 17.601 @@ -666,7 +666,7 @@ 17.602 <sect2> 17.603 <title>Beware the fuzz</title> 17.604 17.605 - <para>While applying a hunk at an offset, or with a fuzz factor, 17.606 + <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor, 17.607 will often be completely successful, these inexact techniques 17.608 naturally leave open the possibility of corrupting the patched 17.609 file. The most common cases typically involve applying a 17.610 @@ -676,7 +676,7 @@ 17.611 fuzz factor, you should make sure that the modified files are 17.612 correct afterwards.</para> 17.613 17.614 - <para>It's often a good idea to refresh a patch that has applied 17.615 + <para id="x_3f8">It's often a good idea to refresh a patch that has applied 17.616 with an offset or fuzz factor; refreshing the patch generates 17.617 new context information that will make it apply cleanly. I 17.618 say <quote>often,</quote> not <quote>always,</quote> because 17.619 @@ -691,30 +691,30 @@ 17.620 <sect2> 17.621 <title>Handling rejection</title> 17.622 17.623 - <para>If <command role="hg-ext-mq">qpush</command> fails to 17.624 + <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to 17.625 apply a patch, it will print an error message and exit. If it 17.626 has left <filename role="special">.rej</filename> files 17.627 behind, it is usually best to fix up the rejected hunks before 17.628 you push more patches or do any further work.</para> 17.629 17.630 - <para>If your patch <emphasis>used to</emphasis> apply cleanly, 17.631 + <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly, 17.632 and no longer does because you've changed the underlying code 17.633 that your patches are based on, Mercurial Queues can help; see 17.634 section <xref 17.635 linkend="sec:mq:merge"/> for details.</para> 17.636 17.637 - <para>Unfortunately, there aren't any great techniques for 17.638 + <para id="x_3fb">Unfortunately, there aren't any great techniques for 17.639 dealing with rejected hunks. Most often, you'll need to view 17.640 the <filename role="special">.rej</filename> file and edit the 17.641 target file, applying the rejected hunks by hand.</para> 17.642 17.643 - <para>If you're feeling adventurous, Neil Brown, a Linux kernel 17.644 + <para id="x_3fc">If you're feeling adventurous, Neil Brown, a Linux kernel 17.645 hacker, wrote a tool called <command>wiggle</command> 17.646 <citation>web:wiggle</citation>, which is more vigorous than 17.647 <command>patch</command> in its attempts to make a patch 17.648 apply.</para> 17.649 17.650 - <para>Another Linux kernel hacker, Chris Mason (the author of 17.651 + <para id="x_3fd">Another Linux kernel hacker, Chris Mason (the author of 17.652 Mercurial Queues), wrote a similar tool called 17.653 <command>mpatch</command> <citation>web:mpatch</citation>, 17.654 which takes a simple approach to automating the application of 17.655 @@ -723,21 +723,21 @@ 17.656 reasons that a hunk may be rejected:</para> 17.657 17.658 <itemizedlist> 17.659 - <listitem><para>The context in the middle of a hunk has 17.660 + <listitem><para id="x_3fe">The context in the middle of a hunk has 17.661 changed.</para> 17.662 </listitem> 17.663 - <listitem><para>A hunk is missing some context at the 17.664 + <listitem><para id="x_3ff">A hunk is missing some context at the 17.665 beginning or end.</para> 17.666 </listitem> 17.667 - <listitem><para>A large hunk might apply better&emdash;either 17.668 + <listitem><para id="x_400">A large hunk might apply better&emdash;either 17.669 entirely or in part&emdash;if it was broken up into 17.670 smaller hunks.</para> 17.671 </listitem> 17.672 - <listitem><para>A hunk removes lines with slightly different 17.673 + <listitem><para id="x_401">A hunk removes lines with slightly different 17.674 content than those currently present in the file.</para> 17.675 </listitem></itemizedlist> 17.676 17.677 - <para>If you use <command>wiggle</command> or 17.678 + <para id="x_402">If you use <command>wiggle</command> or 17.679 <command>mpatch</command>, you should be doubly careful to 17.680 check your results when you're done. In fact, 17.681 <command>mpatch</command> enforces this method of 17.682 @@ -751,7 +751,7 @@ 17.683 <sect1 id="sec:mq:perf"> 17.684 <title>Getting the best performance out of MQ</title> 17.685 17.686 - <para>MQ is very efficient at handling a large number of patches. 17.687 + <para id="x_403">MQ is very efficient at handling a large number of patches. 17.688 I ran some performance experiments in mid-2006 for a talk that I 17.689 gave at the 2006 EuroPython conference 17.690 <citation>web:europython</citation>. I used as my data set the 17.691 @@ -760,7 +760,7 @@ 17.692 all 27,472 revisions between Linux 2.6.12-rc2 and Linux 17.693 2.6.17.</para> 17.694 17.695 - <para>On my old, slow laptop, I was able to <command 17.696 + <para id="x_404">On my old, slow laptop, I was able to <command 17.697 role="hg-cmd">hg qpush <option 17.698 role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all 17.699 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 17.700 @@ -771,11 +771,11 @@ 17.701 (which made 22,779 lines of changes to 287 files) in 6.6 17.702 seconds.</para> 17.703 17.704 - <para>Clearly, MQ is well suited to working in large trees, but 17.705 + <para id="x_405">Clearly, MQ is well suited to working in large trees, but 17.706 there are a few tricks you can use to get the best performance 17.707 of it.</para> 17.708 17.709 - <para>First of all, try to <quote>batch</quote> operations 17.710 + <para id="x_406">First of all, try to <quote>batch</quote> operations 17.711 together. Every time you run <command 17.712 role="hg-ext-mq">qpush</command> or <command 17.713 role="hg-ext-mq">qpop</command>, these commands scan the 17.714 @@ -786,7 +786,7 @@ 17.715 medium-sized tree (containing tens of thousands of files), it 17.716 can take a second or more.</para> 17.717 17.718 - <para>The <command role="hg-ext-mq">qpush</command> and <command 17.719 + <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command 17.720 role="hg-ext-mq">qpop</command> commands allow you to push and 17.721 pop multiple patches at a time. You can identify the 17.722 <quote>destination patch</quote> that you want to end up at. 17.723 @@ -796,7 +796,7 @@ 17.724 role="hg-ext-mq">qpop</command> to a destination, MQ will pop 17.725 patches until the destination patch is at the top.</para> 17.726 17.727 - <para>You can identify a destination patch using either the name 17.728 + <para id="x_408">You can identify a destination patch using either the name 17.729 of the patch, or by number. If you use numeric addressing, 17.730 patches are counted from zero; this means that the first patch 17.731 is zero, the second is one, and so on.</para> 17.732 @@ -806,7 +806,7 @@ 17.733 <title>Updating your patches when the underlying code 17.734 changes</title> 17.735 17.736 - <para>It's common to have a stack of patches on top of an 17.737 + <para id="x_409">It's common to have a stack of patches on top of an 17.738 underlying repository that you don't modify directly. If you're 17.739 working on changes to third-party code, or on a feature that is 17.740 taking longer to develop than the rate of change of the code 17.741 @@ -815,7 +815,7 @@ 17.742 This is called <emphasis>rebasing</emphasis> your patch 17.743 series.</para> 17.744 17.745 - <para>The simplest way to do this is to <command role="hg-cmd">hg 17.746 + <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg 17.747 qpop <option role="hg-ext-mq-cmd-qpop-opt">hg 17.748 -a</option></command> your patches, then <command 17.749 role="hg-cmd">hg pull</command> changes into the underlying 17.750 @@ -827,26 +827,26 @@ 17.751 affected patch, and continue pushing until you have fixed your 17.752 entire stack.</para> 17.753 17.754 - <para>This approach is easy to use and works well if you don't 17.755 + <para id="x_40b">This approach is easy to use and works well if you don't 17.756 expect changes to the underlying code to affect how well your 17.757 patches apply. If your patch stack touches code that is modified 17.758 frequently or invasively in the underlying repository, however, 17.759 fixing up rejected hunks by hand quickly becomes 17.760 tiresome.</para> 17.761 17.762 - <para>It's possible to partially automate the rebasing process. 17.763 + <para id="x_40c">It's possible to partially automate the rebasing process. 17.764 If your patches apply cleanly against some revision of the 17.765 underlying repo, MQ can use this information to help you to 17.766 resolve conflicts between your patches and a different 17.767 revision.</para> 17.768 17.769 - <para>The process is a little involved.</para> 17.770 + <para id="x_40d">The process is a little involved.</para> 17.771 <orderedlist> 17.772 - <listitem><para>To begin, <command role="hg-cmd">hg qpush 17.773 + <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush 17.774 -a</command> all of your patches on top of the revision 17.775 where you know that they apply cleanly.</para> 17.776 </listitem> 17.777 - <listitem><para>Save a backup copy of your patch directory using 17.778 + <listitem><para id="x_40f">Save a backup copy of your patch directory using 17.779 <command role="hg-cmd">hg qsave <option 17.780 role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option 17.781 role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>. 17.782 @@ -860,17 +860,17 @@ 17.783 states of the <filename role="special">series</filename> and 17.784 <filename role="special">status</filename> files.</para> 17.785 </listitem> 17.786 - <listitem><para>Use <command role="hg-cmd">hg pull</command> to 17.787 + <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to 17.788 bring new changes into the underlying repository. (Don't 17.789 run <command role="hg-cmd">hg pull -u</command>; see below 17.790 for why.)</para> 17.791 </listitem> 17.792 - <listitem><para>Update to the new tip revision, using <command 17.793 + <listitem><para id="x_411">Update to the new tip revision, using <command 17.794 role="hg-cmd">hg update <option 17.795 role="hg-opt-update">-C</option></command> to override 17.796 the patches you have pushed.</para> 17.797 </listitem> 17.798 - <listitem><para>Merge all patches using <command>hg qpush -m 17.799 + <listitem><para id="x_412">Merge all patches using <command>hg qpush -m 17.800 -a</command>. The <option 17.801 role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 17.802 <command role="hg-ext-mq">qpush</command> tells MQ to 17.803 @@ -878,7 +878,7 @@ 17.804 apply.</para> 17.805 </listitem></orderedlist> 17.806 17.807 - <para>During the <command role="hg-cmd">hg qpush <option 17.808 + <para id="x_413">During the <command role="hg-cmd">hg qpush <option 17.809 role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>, 17.810 each patch in the <filename role="special">series</filename> 17.811 file is applied normally. If a patch applies with fuzz or 17.812 @@ -888,10 +888,10 @@ 17.813 Mercurial's normal merge machinery, so it may pop up a GUI merge 17.814 tool to help you to resolve problems.</para> 17.815 17.816 - <para>When you finish resolving the effects of a patch, MQ 17.817 + <para id="x_414">When you finish resolving the effects of a patch, MQ 17.818 refreshes your patch based on the result of the merge.</para> 17.819 17.820 - <para>At the end of this process, your repository will have one 17.821 + <para id="x_415">At the end of this process, your repository will have one 17.822 extra head from the old patch queue, and a copy of the old patch 17.823 queue will be in <filename role="special" 17.824 class="directory">.hg/patches.N</filename>. You can remove the 17.825 @@ -905,26 +905,26 @@ 17.826 <sect1> 17.827 <title>Identifying patches</title> 17.828 17.829 - <para>MQ commands that work with patches let you refer to a patch 17.830 + <para id="x_416">MQ commands that work with patches let you refer to a patch 17.831 either by using its name or by a number. By name is obvious 17.832 enough; pass the name <filename>foo.patch</filename> to <command 17.833 role="hg-ext-mq">qpush</command>, for example, and it will 17.834 push patches until <filename>foo.patch</filename> is 17.835 applied.</para> 17.836 17.837 - <para>As a shortcut, you can refer to a patch using both a name 17.838 + <para id="x_417">As a shortcut, you can refer to a patch using both a name 17.839 and a numeric offset; <literal>foo.patch-2</literal> means 17.840 <quote>two patches before <literal>foo.patch</literal></quote>, 17.841 while <literal>bar.patch+4</literal> means <quote>four patches 17.842 after <literal>bar.patch</literal></quote>.</para> 17.843 17.844 - <para>Referring to a patch by index isn't much different. The 17.845 + <para id="x_418">Referring to a patch by index isn't much different. The 17.846 first patch printed in the output of <command 17.847 role="hg-ext-mq">qseries</command> is patch zero (yes, it's 17.848 one of those start-at-zero counting systems); the second is 17.849 patch one; and so on.</para> 17.850 17.851 - <para>MQ also makes it easy to work with patches when you are 17.852 + <para id="x_419">MQ also makes it easy to work with patches when you are 17.853 using normal Mercurial commands. Every command that accepts a 17.854 changeset ID will also accept the name of an applied patch. MQ 17.855 augments the tags normally in the repository with an eponymous 17.856 @@ -934,28 +934,28 @@ 17.857 the <quote>bottom-most</quote> and topmost applied patches, 17.858 respectively.</para> 17.859 17.860 - <para>These additions to Mercurial's normal tagging capabilities 17.861 + <para id="x_41a">These additions to Mercurial's normal tagging capabilities 17.862 make dealing with patches even more of a breeze.</para> 17.863 <itemizedlist> 17.864 - <listitem><para>Want to patchbomb a mailing list with your 17.865 + <listitem><para id="x_41b">Want to patchbomb a mailing list with your 17.866 latest series of changes?</para> 17.867 <programlisting>hg email qbase:qtip</programlisting> 17.868 - <para> (Don't know what <quote>patchbombing</quote> is? See 17.869 + <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See 17.870 section <xref linkend="sec:hgext:patchbomb"/>.)</para> 17.871 </listitem> 17.872 - <listitem><para>Need to see all of the patches since 17.873 + <listitem><para id="x_41d">Need to see all of the patches since 17.874 <literal>foo.patch</literal> that have touched files in a 17.875 subdirectory of your tree?</para> 17.876 <programlisting>hg log -r foo.patch:qtip subdir</programlisting> 17.877 </listitem> 17.878 </itemizedlist> 17.879 17.880 - <para>Because MQ makes the names of patches available to the rest 17.881 + <para id="x_41e">Because MQ makes the names of patches available to the rest 17.882 of Mercurial through its normal internal tag machinery, you 17.883 don't need to type in the entire name of a patch when you want 17.884 to identify it by name.</para> 17.885 17.886 - <para>Another nice consequence of representing patch names as tags 17.887 + <para id="x_41f">Another nice consequence of representing patch names as tags 17.888 is that when you run the <command role="hg-cmd">hg log</command> 17.889 command, it will display a patch's name as a tag, simply as part 17.890 of its normal output. This makes it easy to visually 17.891 @@ -970,12 +970,12 @@ 17.892 <sect1> 17.893 <title>Useful things to know about</title> 17.894 17.895 - <para>There are a number of aspects of MQ usage that don't fit 17.896 + <para id="x_420">There are a number of aspects of MQ usage that don't fit 17.897 tidily into sections of their own, but that are good to know. 17.898 Here they are, in one place.</para> 17.899 17.900 <itemizedlist> 17.901 - <listitem><para>Normally, when you <command 17.902 + <listitem><para id="x_421">Normally, when you <command 17.903 role="hg-ext-mq">qpop</command> a patch and <command 17.904 role="hg-ext-mq">qpush</command> it again, the changeset 17.905 that represents the patch after the pop/push will have a 17.906 @@ -984,7 +984,7 @@ 17.907 linkend="sec:mqref:cmd:qpush"/> for 17.908 information as to why this is.</para> 17.909 </listitem> 17.910 - <listitem><para>It's not a good idea to <command 17.911 + <listitem><para id="x_422">It's not a good idea to <command 17.912 role="hg-cmd">hg merge</command> changes from another 17.913 branch with a patch changeset, at least if you want to 17.914 maintain the <quote>patchiness</quote> of that changeset and 17.915 @@ -997,13 +997,13 @@ 17.916 <sect1 id="sec:mq:repo"> 17.917 <title>Managing patches in a repository</title> 17.918 17.919 - <para>Because MQ's <filename role="special" 17.920 + <para id="x_423">Because MQ's <filename role="special" 17.921 class="directory">.hg/patches</filename> directory resides 17.922 outside a Mercurial repository's working directory, the 17.923 <quote>underlying</quote> Mercurial repository knows nothing 17.924 about the management or presence of patches.</para> 17.925 17.926 - <para>This presents the interesting possibility of managing the 17.927 + <para id="x_424">This presents the interesting possibility of managing the 17.928 contents of the patch directory as a Mercurial repository in its 17.929 own right. This can be a useful way to work. For example, you 17.930 can work on a patch for a while, <command 17.931 @@ -1012,7 +1012,7 @@ 17.932 patch. This lets you <quote>roll back</quote> to that version 17.933 of the patch later on.</para> 17.934 17.935 - <para>You can then share different versions of the same patch 17.936 + <para id="x_425">You can then share different versions of the same patch 17.937 stack among multiple underlying repositories. I use this when I 17.938 am developing a Linux kernel feature. I have a pristine copy of 17.939 my kernel sources for each of several CPU architectures, and a 17.940 @@ -1022,7 +1022,7 @@ 17.941 associated with that kernel tree, pop and push all of my 17.942 patches, and build and test that kernel.</para> 17.943 17.944 - <para>Managing patches in a repository makes it possible for 17.945 + <para id="x_426">Managing patches in a repository makes it possible for 17.946 multiple developers to work on the same patch series without 17.947 colliding with each other, all on top of an underlying source 17.948 base that they may or may not control.</para> 17.949 @@ -1030,7 +1030,7 @@ 17.950 <sect2> 17.951 <title>MQ support for patch repositories</title> 17.952 17.953 - <para>MQ helps you to work with the <filename role="special" 17.954 + <para id="x_427">MQ helps you to work with the <filename role="special" 17.955 class="directory">.hg/patches</filename> directory as a 17.956 repository; when you prepare a repository for working with 17.957 patches using <command role="hg-ext-mq">qinit</command>, you 17.958 @@ -1040,7 +1040,7 @@ 17.959 Mercurial repository.</para> 17.960 17.961 <note> 17.962 - <para> If you forget to use the <option 17.963 + <para id="x_428"> If you forget to use the <option 17.964 role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you 17.965 can simply go into the <filename role="special" 17.966 class="directory">.hg/patches</filename> directory at any 17.967 @@ -1049,25 +1049,25 @@ 17.968 role="special">status</filename> file to the <filename 17.969 role="special">.hgignore</filename> file, though</para> 17.970 17.971 - <para> (<command role="hg-cmd">hg qinit <option 17.972 + <para id="x_429"> (<command role="hg-cmd">hg qinit <option 17.973 role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command> 17.974 does this for you automatically); you 17.975 <emphasis>really</emphasis> don't want to manage the 17.976 <filename role="special">status</filename> file.</para> 17.977 </note> 17.978 17.979 - <para>As a convenience, if MQ notices that the <filename 17.980 + <para id="x_42a">As a convenience, if MQ notices that the <filename 17.981 class="directory">.hg/patches</filename> directory is a 17.982 repository, it will automatically <command role="hg-cmd">hg 17.983 add</command> every patch that you create and import.</para> 17.984 17.985 - <para>MQ provides a shortcut command, <command 17.986 + <para id="x_42b">MQ provides a shortcut command, <command 17.987 role="hg-ext-mq">qcommit</command>, that runs <command 17.988 role="hg-cmd">hg commit</command> in the <filename 17.989 role="special" class="directory">.hg/patches</filename> 17.990 directory. This saves some bothersome typing.</para> 17.991 17.992 - <para>Finally, as a convenience to manage the patch directory, 17.993 + <para id="x_42c">Finally, as a convenience to manage the patch directory, 17.994 you can define the alias <command>mq</command> on Unix 17.995 systems. For example, on Linux systems using the 17.996 <command>bash</command> shell, you can include the following 17.997 @@ -1076,17 +1076,17 @@ 17.998 17.999 <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting> 17.1000 17.1001 - <para>You can then issue commands of the form <command>mq 17.1002 + <para id="x_42d">You can then issue commands of the form <command>mq 17.1003 pull</command> from the main repository.</para> 17.1004 17.1005 </sect2> 17.1006 <sect2> 17.1007 <title>A few things to watch out for</title> 17.1008 17.1009 - <para>MQ's support for working with a repository full of patches 17.1010 + <para id="x_42e">MQ's support for working with a repository full of patches 17.1011 is limited in a few small respects.</para> 17.1012 17.1013 - <para>MQ cannot automatically detect changes that you make to 17.1014 + <para id="x_42f">MQ cannot automatically detect changes that you make to 17.1015 the patch directory. If you <command role="hg-cmd">hg 17.1016 pull</command>, manually edit, or <command role="hg-cmd">hg 17.1017 update</command> changes to patches or the <filename 17.1018 @@ -1104,11 +1104,11 @@ 17.1019 <sect1 id="sec:mq:tools"> 17.1020 <title>Third party tools for working with patches</title> 17.1021 17.1022 - <para>Once you've been working with patches for a while, you'll 17.1023 + <para id="x_430">Once you've been working with patches for a while, you'll 17.1024 find yourself hungry for tools that will help you to understand 17.1025 and manipulate the patches you're dealing with.</para> 17.1026 17.1027 - <para>The <command>diffstat</command> command 17.1028 + <para id="x_431">The <command>diffstat</command> command 17.1029 <citation>web:diffstat</citation> generates a histogram of the 17.1030 modifications made to each file in a patch. It provides a good 17.1031 way to <quote>get a sense of</quote> a patch&emdash;which files 17.1032 @@ -1122,7 +1122,7 @@ 17.1033 17.1034 &interaction.mq.tools.tools; 17.1035 17.1036 - <para>The <literal role="package">patchutils</literal> package 17.1037 + <para id="x_432">The <literal role="package">patchutils</literal> package 17.1038 <citation>web:patchutils</citation> is invaluable. It provides a 17.1039 set of small utilities that follow the <quote>Unix 17.1040 philosophy;</quote> each does one useful thing with a patch. 17.1041 @@ -1140,13 +1140,13 @@ 17.1042 <sect1> 17.1043 <title>Good ways to work with patches</title> 17.1044 17.1045 - <para>Whether you are working on a patch series to submit to a 17.1046 + <para id="x_433">Whether you are working on a patch series to submit to a 17.1047 free software or open source project, or a series that you 17.1048 intend to treat as a sequence of regular changesets when you're 17.1049 done, you can use some simple techniques to keep your work well 17.1050 organised.</para> 17.1051 17.1052 - <para>Give your patches descriptive names. A good name for a 17.1053 + <para id="x_434">Give your patches descriptive names. A good name for a 17.1054 patch might be <filename>rework-device-alloc.patch</filename>, 17.1055 because it will immediately give you a hint what the purpose of 17.1056 the patch is. Long names shouldn't be a problem; you won't be 17.1057 @@ -1158,7 +1158,7 @@ 17.1058 to work with, or if you are juggling a number of different tasks 17.1059 and your patches only get a fraction of your attention.</para> 17.1060 17.1061 - <para>Be aware of what patch you're working on. Use the <command 17.1062 + <para id="x_435">Be aware of what patch you're working on. Use the <command 17.1063 role="hg-ext-mq">qtop</command> command and skim over the text 17.1064 of your patches frequently&emdash;for example, using <command 17.1065 role="hg-cmd">hg tip <option 17.1066 @@ -1168,7 +1168,7 @@ 17.1067 one I intended, and it's often tricky to migrate changes into 17.1068 the right patch after making them in the wrong one.</para> 17.1069 17.1070 - <para>For this reason, it is very much worth investing a little 17.1071 + <para id="x_436">For this reason, it is very much worth investing a little 17.1072 time to learn how to use some of the third-party tools I 17.1073 described in section <xref linkend="sec:mq:tools"/>, 17.1074 particularly 17.1075 @@ -1184,28 +1184,28 @@ 17.1076 <sect2> 17.1077 <title>Manage <quote>trivial</quote> patches</title> 17.1078 17.1079 - <para>Because the overhead of dropping files into a new 17.1080 + <para id="x_437">Because the overhead of dropping files into a new 17.1081 Mercurial repository is so low, it makes a lot of sense to 17.1082 manage patches this way even if you simply want to make a few 17.1083 changes to a source tarball that you downloaded.</para> 17.1084 17.1085 - <para>Begin by downloading and unpacking the source tarball, and 17.1086 + <para id="x_438">Begin by downloading and unpacking the source tarball, and 17.1087 turning it into a Mercurial repository.</para> 17.1088 17.1089 &interaction.mq.tarball.download; 17.1090 17.1091 - <para>Continue by creating a patch stack and making your 17.1092 + <para id="x_439">Continue by creating a patch stack and making your 17.1093 changes.</para> 17.1094 17.1095 &interaction.mq.tarball.qinit; 17.1096 17.1097 - <para>Let's say a few weeks or months pass, and your package 17.1098 + <para id="x_43a">Let's say a few weeks or months pass, and your package 17.1099 author releases a new version. First, bring their changes 17.1100 into the repository.</para> 17.1101 17.1102 &interaction.mq.tarball.newsource; 17.1103 17.1104 - <para>The pipeline starting with <command role="hg-cmd">hg 17.1105 + <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg 17.1106 locate</command> above deletes all files in the working 17.1107 directory, so that <command role="hg-cmd">hg 17.1108 commit</command>'s <option 17.1109 @@ -1213,7 +1213,7 @@ 17.1110 actually tell which files have really been removed in the 17.1111 newer version of the source.</para> 17.1112 17.1113 - <para>Finally, you can apply your patches on top of the new 17.1114 + <para id="x_43c">Finally, you can apply your patches on top of the new 17.1115 tree.</para> 17.1116 17.1117 &interaction.mq.tarball.repush; 17.1118 @@ -1222,7 +1222,7 @@ 17.1119 <sect2 id="sec:mq:combine"> 17.1120 <title>Combining entire patches</title> 17.1121 17.1122 - <para>MQ provides a command, <command 17.1123 + <para id="x_43d">MQ provides a command, <command 17.1124 role="hg-ext-mq">qfold</command> that lets you combine 17.1125 entire patches. This <quote>folds</quote> the patches you 17.1126 name, in the order you name them, into the topmost applied 17.1127 @@ -1230,7 +1230,7 @@ 17.1128 description. The patches that you fold must be unapplied 17.1129 before you fold them.</para> 17.1130 17.1131 - <para>The order in which you fold patches matters. If your 17.1132 + <para id="x_43e">The order in which you fold patches matters. If your 17.1133 topmost applied patch is <literal>foo</literal>, and you 17.1134 <command role="hg-ext-mq">qfold</command> 17.1135 <literal>bar</literal> and <literal>quux</literal> into it, 17.1136 @@ -1243,11 +1243,11 @@ 17.1137 <sect2> 17.1138 <title>Merging part of one patch into another</title> 17.1139 17.1140 - <para>Merging <emphasis>part</emphasis> of one patch into 17.1141 + <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into 17.1142 another is more difficult than combining entire 17.1143 patches.</para> 17.1144 17.1145 - <para>If you want to move changes to entire files, you can use 17.1146 + <para id="x_440">If you want to move changes to entire files, you can use 17.1147 <command>filterdiff</command>'s <option 17.1148 role="cmd-opt-filterdiff">-i</option> and <option 17.1149 role="cmd-opt-filterdiff">-x</option> options to choose the 17.1150 @@ -1260,7 +1260,7 @@ 17.1151 <command role="hg-ext-mq">qrefresh</command> the patch to drop 17.1152 the duplicate hunks.</para> 17.1153 17.1154 - <para>If you have a patch that has multiple hunks modifying a 17.1155 + <para id="x_441">If you have a patch that has multiple hunks modifying a 17.1156 file, and you only want to move a few of those hunks, the job 17.1157 becomes more messy, but you can still partly automate it. Use 17.1158 <command>lsdiff -nvv</command> to print some metadata about 17.1159 @@ -1268,21 +1268,21 @@ 17.1160 17.1161 &interaction.mq.tools.lsdiff; 17.1162 17.1163 - <para>This command prints three different kinds of 17.1164 + <para id="x_442">This command prints three different kinds of 17.1165 number:</para> 17.1166 <itemizedlist> 17.1167 - <listitem><para>(in the first column) a <emphasis>file 17.1168 + <listitem><para id="x_443">(in the first column) a <emphasis>file 17.1169 number</emphasis> to identify each file modified in the 17.1170 patch;</para> 17.1171 </listitem> 17.1172 - <listitem><para>(on the next line, indented) the line number 17.1173 + <listitem><para id="x_444">(on the next line, indented) the line number 17.1174 within a modified file where a hunk starts; and</para> 17.1175 </listitem> 17.1176 - <listitem><para>(on the same line) a <emphasis>hunk 17.1177 + <listitem><para id="x_445">(on the same line) a <emphasis>hunk 17.1178 number</emphasis> to identify that hunk.</para> 17.1179 </listitem></itemizedlist> 17.1180 17.1181 - <para>You'll have to use some visual inspection, and reading of 17.1182 + <para id="x_446">You'll have to use some visual inspection, and reading of 17.1183 the patch, to identify the file and hunk numbers you'll want, 17.1184 but you can then pass them to to 17.1185 <command>filterdiff</command>'s <option 17.1186 @@ -1290,7 +1290,7 @@ 17.1187 role="cmd-opt-filterdiff">--hunks</option> options, to 17.1188 select exactly the file and hunk you want to extract.</para> 17.1189 17.1190 - <para>Once you have this hunk, you can concatenate it onto the 17.1191 + <para id="x_447">Once you have this hunk, you can concatenate it onto the 17.1192 end of your destination patch and continue with the remainder 17.1193 of section <xref linkend="sec:mq:combine"/>.</para> 17.1194 17.1195 @@ -1299,11 +1299,11 @@ 17.1196 <sect1> 17.1197 <title>Differences between quilt and MQ</title> 17.1198 17.1199 - <para>If you are already familiar with quilt, MQ provides a 17.1200 + <para id="x_448">If you are already familiar with quilt, MQ provides a 17.1201 similar command set. There are a few differences in the way 17.1202 that it works.</para> 17.1203 17.1204 - <para>You will already have noticed that most quilt commands have 17.1205 + <para id="x_449">You will already have noticed that most quilt commands have 17.1206 MQ counterparts that simply begin with a 17.1207 <quote><literal>q</literal></quote>. The exceptions are quilt's 17.1208 <literal>add</literal> and <literal>remove</literal> commands,
18.1 --- a/en/ch12-mq-collab.xml Thu Mar 19 20:54:12 2009 -0700 18.2 +++ b/en/ch12-mq-collab.xml Thu Mar 19 21:18:52 2009 -0700 18.3 @@ -4,18 +4,18 @@ 18.4 <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> 18.5 <title>Advanced uses of Mercurial Queues</title> 18.6 18.7 - <para>While it's easy to pick up straightforward uses of Mercurial 18.8 + <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial 18.9 Queues, use of a little discipline and some of MQ's less 18.10 frequently used capabilities makes it possible to work in 18.11 complicated development environments.</para> 18.12 18.13 - <para>In this chapter, I will use as an example a technique I have 18.14 + <para id="x_15e">In this chapter, I will use as an example a technique I have 18.15 used to manage the development of an Infiniband device driver for 18.16 the Linux kernel. The driver in question is large (at least as 18.17 drivers go), with 25,000 lines of code spread across 35 source 18.18 files. It is maintained by a small team of developers.</para> 18.19 18.20 - <para>While much of the material in this chapter is specific to 18.21 + <para id="x_15f">While much of the material in this chapter is specific to 18.22 Linux, the same principles apply to any code base for which you're 18.23 not the primary owner, and upon which you need to do a lot of 18.24 development.</para> 18.25 @@ -23,23 +23,23 @@ 18.26 <sect1> 18.27 <title>The problem of many targets</title> 18.28 18.29 - <para>The Linux kernel changes rapidly, and has never been 18.30 + <para id="x_160">The Linux kernel changes rapidly, and has never been 18.31 internally stable; developers frequently make drastic changes 18.32 between releases. This means that a version of the driver that 18.33 works well with a particular released version of the kernel will 18.34 not even <emphasis>compile</emphasis> correctly against, 18.35 typically, any other version.</para> 18.36 18.37 - <para>To maintain a driver, we have to keep a number of distinct 18.38 + <para id="x_161">To maintain a driver, we have to keep a number of distinct 18.39 versions of Linux in mind.</para> 18.40 <itemizedlist> 18.41 - <listitem><para>One target is the main Linux kernel development 18.42 + <listitem><para id="x_162">One target is the main Linux kernel development 18.43 tree. Maintenance of the code is in this case partly shared 18.44 by other developers in the kernel community, who make 18.45 <quote>drive-by</quote> modifications to the driver as they 18.46 develop and refine kernel subsystems.</para> 18.47 </listitem> 18.48 - <listitem><para>We also maintain a number of 18.49 + <listitem><para id="x_163">We also maintain a number of 18.50 <quote>backports</quote> to older versions of the Linux 18.51 kernel, to support the needs of customers who are running 18.52 older Linux distributions that do not incorporate our 18.53 @@ -47,7 +47,7 @@ 18.54 is to modify it to work in an older version of its target 18.55 environment than the version it was developed for.)</para> 18.56 </listitem> 18.57 - <listitem><para>Finally, we make software releases on a schedule 18.58 + <listitem><para id="x_164">Finally, we make software releases on a schedule 18.59 that is necessarily not aligned with those used by Linux 18.60 distributors and kernel developers, so that we can deliver 18.61 new features to customers without forcing them to upgrade 18.62 @@ -57,11 +57,11 @@ 18.63 <sect2> 18.64 <title>Tempting approaches that don't work well</title> 18.65 18.66 - <para>There are two <quote>standard</quote> ways to maintain a 18.67 + <para id="x_165">There are two <quote>standard</quote> ways to maintain a 18.68 piece of software that has to target many different 18.69 environments.</para> 18.70 18.71 - <para>The first is to maintain a number of branches, each 18.72 + <para id="x_166">The first is to maintain a number of branches, each 18.73 intended for a single target. The trouble with this approach 18.74 is that you must maintain iron discipline in the flow of 18.75 changes between repositories. A new feature or bug fix must 18.76 @@ -71,7 +71,7 @@ 18.77 backport change that is applied to a branch where it doesn't 18.78 belong will probably stop the driver from compiling.</para> 18.79 18.80 - <para>The second is to maintain a single source tree filled with 18.81 + <para id="x_167">The second is to maintain a single source tree filled with 18.82 conditional statements that turn chunks of code on or off 18.83 depending on the intended target. Because these 18.84 <quote>ifdefs</quote> are not allowed in the Linux kernel 18.85 @@ -80,7 +80,7 @@ 18.86 this fashion rapidly becomes a rat's nest of conditional 18.87 blocks that are difficult to understand and maintain.</para> 18.88 18.89 - <para>Neither of these approaches is well suited to a situation 18.90 + <para id="x_168">Neither of these approaches is well suited to a situation 18.91 where you don't <quote>own</quote> the canonical copy of a 18.92 source tree. In the case of a Linux driver that is 18.93 distributed with the standard kernel, Linus's tree contains 18.94 @@ -90,11 +90,11 @@ 18.95 finding out about it until after the changes show up in 18.96 Linus's tree.</para> 18.97 18.98 - <para>These approaches have the added weakness of making it 18.99 + <para id="x_169">These approaches have the added weakness of making it 18.100 difficult to generate well-formed patches to submit 18.101 upstream.</para> 18.102 18.103 - <para>In principle, Mercurial Queues seems like a good candidate 18.104 + <para id="x_16a">In principle, Mercurial Queues seems like a good candidate 18.105 to manage a development scenario such as the above. While 18.106 this is indeed the case, MQ contains a few added features that 18.107 make the job more pleasant.</para> 18.108 @@ -104,7 +104,7 @@ 18.109 <sect1> 18.110 <title>Conditionally applying patches with guards</title> 18.111 18.112 - <para>Perhaps the best way to maintain sanity with so many targets 18.113 + <para id="x_16b">Perhaps the best way to maintain sanity with so many targets 18.114 is to be able to choose specific patches to apply for a given 18.115 situation. MQ provides a feature called <quote>guards</quote> 18.116 (which originates with quilt's <literal>guards</literal> 18.117 @@ -113,18 +113,18 @@ 18.118 18.119 &interaction.mq.guards.init; 18.120 18.121 - <para>This gives us a tiny repository that contains two patches 18.122 + <para id="x_16c">This gives us a tiny repository that contains two patches 18.123 that don't have any dependencies on each other, because they 18.124 touch different files.</para> 18.125 18.126 - <para>The idea behind conditional application is that you can 18.127 + <para id="x_16d">The idea behind conditional application is that you can 18.128 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 18.129 which is simply a text string of your choosing, then tell MQ to 18.130 select specific guards to use when applying patches. MQ will 18.131 then either apply, or skip over, a guarded patch, depending on 18.132 the guards that you have selected.</para> 18.133 18.134 - <para>A patch can have an arbitrary number of guards; each one is 18.135 + <para id="x_16e">A patch can have an arbitrary number of guards; each one is 18.136 <emphasis>positive</emphasis> (<quote>apply this patch if this 18.137 guard is selected</quote>) or <emphasis>negative</emphasis> 18.138 (<quote>skip this patch if this guard is selected</quote>). A 18.139 @@ -134,26 +134,26 @@ 18.140 <sect1> 18.141 <title>Controlling the guards on a patch</title> 18.142 18.143 - <para>The <command role="hg-ext-mq">qguard</command> command lets 18.144 + <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets 18.145 you determine which guards should apply to a patch, or display 18.146 the guards that are already in effect. Without any arguments, it 18.147 displays the guards on the current topmost patch.</para> 18.148 18.149 &interaction.mq.guards.qguard; 18.150 18.151 - <para>To set a positive guard on a patch, prefix the name of the 18.152 + <para id="x_170">To set a positive guard on a patch, prefix the name of the 18.153 guard with a <quote><literal>+</literal></quote>.</para> 18.154 18.155 &interaction.mq.guards.qguard.pos; 18.156 18.157 - <para>To set a negative guard 18.158 + <para id="x_171">To set a negative guard 18.159 on a patch, prefix the name of the guard with a 18.160 <quote><literal>-</literal></quote>.</para> 18.161 18.162 &interaction.mq.guards.qguard.neg; 18.163 18.164 <note> 18.165 - <para> The <command role="hg-ext-mq">qguard</command> command 18.166 + <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command 18.167 <emphasis>sets</emphasis> the guards on a patch; it doesn't 18.168 <emphasis>modify</emphasis> them. What this means is that if 18.169 you run <command role="hg-cmd">hg qguard +a +b</command> on a 18.170 @@ -162,7 +162,7 @@ 18.171 be set on it afterwards is <literal>+c</literal>.</para> 18.172 </note> 18.173 18.174 - <para>Mercurial stores guards in the <filename 18.175 + <para id="x_173">Mercurial stores guards in the <filename 18.176 role="special">series</filename> file; the form in which they 18.177 are stored is easy both to understand and to edit by hand. (In 18.178 other words, you don't have to use the <command 18.179 @@ -176,31 +176,31 @@ 18.180 <sect1> 18.181 <title>Selecting the guards to use</title> 18.182 18.183 - <para>The <command role="hg-ext-mq">qselect</command> command 18.184 + <para id="x_174">The <command role="hg-ext-mq">qselect</command> command 18.185 determines which guards are active at a given time. The effect 18.186 of this is to determine which patches MQ will apply the next 18.187 time you run <command role="hg-ext-mq">qpush</command>. It has 18.188 no other effect; in particular, it doesn't do anything to 18.189 patches that are already applied.</para> 18.190 18.191 - <para>With no arguments, the <command 18.192 + <para id="x_175">With no arguments, the <command 18.193 role="hg-ext-mq">qselect</command> command lists the guards 18.194 currently in effect, one per line of output. Each argument is 18.195 treated as the name of a guard to apply.</para> 18.196 18.197 &interaction.mq.guards.qselect.foo; 18.198 18.199 - <para>In case you're interested, the currently selected guards are 18.200 + <para id="x_176">In case you're interested, the currently selected guards are 18.201 stored in the <filename role="special">guards</filename> file.</para> 18.202 18.203 &interaction.mq.guards.qselect.cat; 18.204 18.205 - <para>We can see the effect the selected guards have when we run 18.206 + <para id="x_177">We can see the effect the selected guards have when we run 18.207 <command role="hg-ext-mq">qpush</command>.</para> 18.208 18.209 &interaction.mq.guards.qselect.qpush; 18.210 18.211 - <para>A guard cannot start with a 18.212 + <para id="x_178">A guard cannot start with a 18.213 <quote><literal>+</literal></quote> or 18.214 <quote><literal>-</literal></quote> character. The name of a 18.215 guard must not contain white space, but most other characters 18.216 @@ -209,12 +209,12 @@ 18.217 18.218 &interaction.mq.guards.qselect.error; 18.219 18.220 - <para>Changing the selected guards changes the patches that are 18.221 + <para id="x_179">Changing the selected guards changes the patches that are 18.222 applied.</para> 18.223 18.224 &interaction.mq.guards.qselect.quux; 18.225 18.226 - <para>You can see in the example below that negative guards take 18.227 + <para id="x_17a">You can see in the example below that negative guards take 18.228 precedence over positive guards.</para> 18.229 18.230 &interaction.mq.guards.qselect.foobar; 18.231 @@ -223,19 +223,19 @@ 18.232 <sect1> 18.233 <title>MQ's rules for applying patches</title> 18.234 18.235 - <para>The rules that MQ uses when deciding whether to apply a 18.236 + <para id="x_17b">The rules that MQ uses when deciding whether to apply a 18.237 patch are as follows.</para> 18.238 <itemizedlist> 18.239 - <listitem><para>A patch that has no guards is always 18.240 + <listitem><para id="x_17c">A patch that has no guards is always 18.241 applied.</para> 18.242 </listitem> 18.243 - <listitem><para>If the patch has any negative guard that matches 18.244 + <listitem><para id="x_17d">If the patch has any negative guard that matches 18.245 any currently selected guard, the patch is skipped.</para> 18.246 </listitem> 18.247 - <listitem><para>If the patch has any positive guard that matches 18.248 + <listitem><para id="x_17e">If the patch has any positive guard that matches 18.249 any currently selected guard, the patch is applied.</para> 18.250 </listitem> 18.251 - <listitem><para>If the patch has positive or negative guards, 18.252 + <listitem><para id="x_17f">If the patch has positive or negative guards, 18.253 but none matches any currently selected guard, the patch is 18.254 skipped.</para> 18.255 </listitem></itemizedlist> 18.256 @@ -244,14 +244,14 @@ 18.257 <sect1> 18.258 <title>Trimming the work environment</title> 18.259 18.260 - <para>In working on the device driver I mentioned earlier, I don't 18.261 + <para id="x_180">In working on the device driver I mentioned earlier, I don't 18.262 apply the patches to a normal Linux kernel tree. Instead, I use 18.263 a repository that contains only a snapshot of the source files 18.264 and headers that are relevant to Infiniband development. This 18.265 repository is 1% the size of a kernel repository, so it's easier 18.266 to work with.</para> 18.267 18.268 - <para>I then choose a <quote>base</quote> version on top of which 18.269 + <para id="x_181">I then choose a <quote>base</quote> version on top of which 18.270 the patches are applied. This is a snapshot of the Linux kernel 18.271 tree as of a revision of my choosing. When I take the snapshot, 18.272 I record the changeset ID from the kernel repository in the 18.273 @@ -260,7 +260,7 @@ 18.274 kernel tree, I can apply my patches on top of either my tiny 18.275 repository or a normal kernel tree.</para> 18.276 18.277 - <para>Normally, the base tree atop which the patches apply should 18.278 + <para id="x_182">Normally, the base tree atop which the patches apply should 18.279 be a snapshot of a very recent upstream tree. This best 18.280 facilitates the development of patches that can easily be 18.281 submitted upstream with few or no modifications.</para> 18.282 @@ -270,17 +270,17 @@ 18.283 <title>Dividing up the <filename role="special">series</filename> 18.284 file</title> 18.285 18.286 - <para>I categorise the patches in the <filename 18.287 + <para id="x_183">I categorise the patches in the <filename 18.288 role="special">series</filename> file into a number of logical 18.289 groups. Each section of like patches begins with a block of 18.290 comments that describes the purpose of the patches that 18.291 follow.</para> 18.292 18.293 - <para>The sequence of patch groups that I maintain follows. The 18.294 + <para id="x_184">The sequence of patch groups that I maintain follows. The 18.295 ordering of these groups is important; I'll describe why after I 18.296 introduce the groups.</para> 18.297 <itemizedlist> 18.298 - <listitem><para>The <quote>accepted</quote> group. Patches that 18.299 + <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that 18.300 the development team has submitted to the maintainer of the 18.301 Infiniband subsystem, and which he has accepted, but which 18.302 are not present in the snapshot that the tiny repository is 18.303 @@ -288,12 +288,12 @@ 18.304 present only to transform the tree into a similar state as 18.305 it is in the upstream maintainer's repository.</para> 18.306 </listitem> 18.307 - <listitem><para>The <quote>rework</quote> group. Patches that I 18.308 + <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I 18.309 have submitted, but that the upstream maintainer has 18.310 requested modifications to before he will accept 18.311 them.</para> 18.312 </listitem> 18.313 - <listitem><para>The <quote>pending</quote> group. Patches that 18.314 + <listitem><para id="x_187">The <quote>pending</quote> group. Patches that 18.315 I have not yet submitted to the upstream maintainer, but 18.316 which we have finished working on. These will be <quote>read 18.317 only</quote> for a while. If the upstream maintainer 18.318 @@ -302,15 +302,15 @@ 18.319 modify any, I'll move them to the beginning of the 18.320 <quote>rework</quote> group.</para> 18.321 </listitem> 18.322 - <listitem><para>The <quote>in progress</quote> group. Patches 18.323 + <listitem><para id="x_188">The <quote>in progress</quote> group. Patches 18.324 that are actively being developed, and should not be 18.325 submitted anywhere yet.</para> 18.326 </listitem> 18.327 - <listitem><para>The <quote>backport</quote> group. Patches that 18.328 + <listitem><para id="x_189">The <quote>backport</quote> group. Patches that 18.329 adapt the source tree to older versions of the kernel 18.330 tree.</para> 18.331 </listitem> 18.332 - <listitem><para>The <quote>do not ship</quote> group. Patches 18.333 + <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches 18.334 that for some reason should never be submitted upstream. 18.335 For example, one such patch might change embedded driver 18.336 identification strings to make it easier to distinguish, in 18.337 @@ -318,7 +318,7 @@ 18.338 a version shipped by a distribution vendor.</para> 18.339 </listitem></itemizedlist> 18.340 18.341 - <para>Now to return to the reasons for ordering groups of patches 18.342 + <para id="x_18b">Now to return to the reasons for ordering groups of patches 18.343 in this way. We would like the lowest patches in the stack to 18.344 be as stable as possible, so that we will not need to rework 18.345 higher patches due to changes in context. Putting patches that 18.346 @@ -326,12 +326,12 @@ 18.347 role="special">series</filename> file serves this 18.348 purpose.</para> 18.349 18.350 - <para>We would also like the patches that we know we'll need to 18.351 + <para id="x_18c">We would also like the patches that we know we'll need to 18.352 modify to be applied on top of a source tree that resembles the 18.353 upstream tree as closely as possible. This is why we keep 18.354 accepted patches around for a while.</para> 18.355 18.356 - <para>The <quote>backport</quote> and <quote>do not ship</quote> 18.357 + <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> 18.358 patches float at the end of the <filename 18.359 role="special">series</filename> file. The backport patches 18.360 must be applied on top of all other patches, and the <quote>do 18.361 @@ -342,36 +342,36 @@ 18.362 <sect1> 18.363 <title>Maintaining the patch series</title> 18.364 18.365 - <para>In my work, I use a number of guards to control which 18.366 + <para id="x_18e">In my work, I use a number of guards to control which 18.367 patches are to be applied.</para> 18.368 18.369 <itemizedlist> 18.370 - <listitem><para><quote>Accepted</quote> patches are guarded with 18.371 + <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with 18.372 <literal>accepted</literal>. I enable this guard most of 18.373 the time. When I'm applying the patches on top of a tree 18.374 where the patches are already present, I can turn this patch 18.375 off, and the patches that follow it will apply 18.376 cleanly.</para> 18.377 </listitem> 18.378 - <listitem><para>Patches that are <quote>finished</quote>, but 18.379 + <listitem><para id="x_190">Patches that are <quote>finished</quote>, but 18.380 not yet submitted, have no guards. If I'm applying the 18.381 patch stack to a copy of the upstream tree, I don't need to 18.382 enable any guards in order to get a reasonably safe source 18.383 tree.</para> 18.384 </listitem> 18.385 - <listitem><para>Those patches that need reworking before being 18.386 + <listitem><para id="x_191">Those patches that need reworking before being 18.387 resubmitted are guarded with 18.388 <literal>rework</literal>.</para> 18.389 </listitem> 18.390 - <listitem><para>For those patches that are still under 18.391 + <listitem><para id="x_192">For those patches that are still under 18.392 development, I use <literal>devel</literal>.</para> 18.393 </listitem> 18.394 - <listitem><para>A backport patch may have several guards, one 18.395 + <listitem><para id="x_193">A backport patch may have several guards, one 18.396 for each version of the kernel to which it applies. For 18.397 example, a patch that backports a piece of code to 2.6.9 18.398 will have a <literal>2.6.9</literal> guard.</para> 18.399 </listitem></itemizedlist> 18.400 - <para>This variety of guards gives me considerable flexibility in 18.401 + <para id="x_194">This variety of guards gives me considerable flexibility in 18.402 determining what kind of source tree I want to end up with. For 18.403 most situations, the selection of appropriate guards is 18.404 automated during the build process, but I can manually tune the 18.405 @@ -380,13 +380,13 @@ 18.406 <sect2> 18.407 <title>The art of writing backport patches</title> 18.408 18.409 - <para>Using MQ, writing a backport patch is a simple process. 18.410 + <para id="x_195">Using MQ, writing a backport patch is a simple process. 18.411 All such a patch has to do is modify a piece of code that uses 18.412 a kernel feature not present in the older version of the 18.413 kernel, so that the driver continues to work correctly under 18.414 that older version.</para> 18.415 18.416 - <para>A useful goal when writing a good backport patch is to 18.417 + <para id="x_196">A useful goal when writing a good backport patch is to 18.418 make your code look as if it was written for the older version 18.419 of the kernel you're targeting. The less obtrusive the patch, 18.420 the easier it will be to understand and maintain. If you're 18.421 @@ -399,7 +399,7 @@ 18.422 unconditional changes, and control their application using 18.423 guards.</para> 18.424 18.425 - <para>There are two reasons to divide backport patches into a 18.426 + <para id="x_197">There are two reasons to divide backport patches into a 18.427 distinct group, away from the <quote>regular</quote> patches 18.428 whose effects they modify. The first is that intermingling the 18.429 two makes it more difficult to use a tool like the <literal 18.430 @@ -419,12 +419,12 @@ 18.431 <sect2> 18.432 <title>Organising patches in directories</title> 18.433 18.434 - <para>If you're working on a substantial project with MQ, it's 18.435 + <para id="x_198">If you're working on a substantial project with MQ, it's 18.436 not difficult to accumulate a large number of patches. For 18.437 example, I have one patch repository that contains over 250 18.438 patches.</para> 18.439 18.440 - <para>If you can group these patches into separate logical 18.441 + <para id="x_199">If you can group these patches into separate logical 18.442 categories, you can if you like store them in different 18.443 directories; MQ has no problems with patch names that contain 18.444 path separators.</para> 18.445 @@ -433,7 +433,7 @@ 18.446 <sect2 id="mq-collab:tips:interdiff"> 18.447 <title>Viewing the history of a patch</title> 18.448 18.449 - <para>If you're developing a set of patches over a long time, 18.450 + <para id="x_19a">If you're developing a set of patches over a long time, 18.451 it's a good idea to maintain them in a repository, as 18.452 discussed in section <xref linkend="sec:mq:repo"/>. If you do 18.453 so, you'll quickly 18.454 @@ -445,7 +445,7 @@ 18.455 time stamps and directory names when it updates a 18.456 patch.</para> 18.457 18.458 - <para>However, you can use the <literal 18.459 + <para id="x_19b">However, you can use the <literal 18.460 role="hg-ext">extdiff</literal> extension, which is bundled 18.461 with Mercurial, to turn a diff of two versions of a patch into 18.462 something readable. To do this, you will need a third-party 18.463 @@ -456,14 +456,14 @@ 18.464 of the same diff, it generates a diff that represents the diff 18.465 from the first to the second version.</para> 18.466 18.467 - <para>You can enable the <literal 18.468 + <para id="x_19c">You can enable the <literal 18.469 role="hg-ext">extdiff</literal> extension in the usual way, 18.470 by adding a line to the <literal 18.471 role="rc-extensions">extensions</literal> section of your 18.472 <filename role="special">~/.hgrc</filename>.</para> 18.473 <programlisting>[extensions] 18.474 extdiff =</programlisting> 18.475 - <para>The <command>interdiff</command> command expects to be 18.476 + <para id="x_19d">The <command>interdiff</command> command expects to be 18.477 passed the names of two files, but the <literal 18.478 role="hg-ext">extdiff</literal> extension passes the program 18.479 it runs a pair of directories, each of which can contain an 18.480 @@ -475,18 +475,18 @@ 18.481 source code repository that accompanies this book. <!-- 18.482 &example.hg-interdiff; --></para> 18.483 18.484 - <para>With the <filename role="special">hg-interdiff</filename> 18.485 + <para id="x_19e">With the <filename role="special">hg-interdiff</filename> 18.486 program in your shell's search path, you can run it as 18.487 follows, from inside an MQ patch directory:</para> 18.488 <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> 18.489 - <para>Since you'll probably want to use this long-winded command 18.490 + <para id="x_19f">Since you'll probably want to use this long-winded command 18.491 a lot, you can get <literal role="hg-ext">hgext</literal> to 18.492 make it available as a normal Mercurial command, again by 18.493 editing your <filename 18.494 role="special">~/.hgrc</filename>.</para> 18.495 <programlisting>[extdiff] 18.496 cmd.interdiff = hg-interdiff</programlisting> 18.497 - <para>This directs <literal role="hg-ext">hgext</literal> to 18.498 + <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to 18.499 make an <literal>interdiff</literal> command available, so you 18.500 can now shorten the previous invocation of <command 18.501 role="hg-ext-extdiff">extdiff</command> to something a 18.502 @@ -494,7 +494,7 @@ 18.503 <programlisting>hg interdiff -r A:B my-change.patch</programlisting> 18.504 18.505 <note> 18.506 - <para> The <command>interdiff</command> command works well 18.507 + <para id="x_1a1"> The <command>interdiff</command> command works well 18.508 only if the underlying files against which versions of a 18.509 patch are generated remain the same. If you create a patch, 18.510 modify the underlying files, and then regenerate the patch, 18.511 @@ -502,7 +502,7 @@ 18.512 output.</para> 18.513 </note> 18.514 18.515 - <para>The <literal role="hg-ext">extdiff</literal> extension is 18.516 + <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is 18.517 useful for more than merely improving the presentation of MQ 18.518 patches. To read more about it, go to section <xref 18.519 linkend="sec:hgext:extdiff"/>.</para>
19.1 --- a/en/ch13-hgext.xml Thu Mar 19 20:54:12 2009 -0700 19.2 +++ b/en/ch13-hgext.xml Thu Mar 19 21:18:52 2009 -0700 19.3 @@ -4,24 +4,24 @@ 19.4 <?dbhtml filename="adding-functionality-with-extensions.html"?> 19.5 <title>Adding functionality with extensions</title> 19.6 19.7 - <para>While the core of Mercurial is quite complete from a 19.8 + <para id="x_4fe">While the core of Mercurial is quite complete from a 19.9 functionality standpoint, it's deliberately shorn of fancy 19.10 features. This approach of preserving simplicity keeps the 19.11 software easy to deal with for both maintainers and users.</para> 19.12 19.13 - <para>However, Mercurial doesn't box you in with an inflexible 19.14 + <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 19.15 command set: you can add features to it as 19.16 <emphasis>extensions</emphasis> (sometimes known as 19.17 <emphasis>plugins</emphasis>). We've already discussed a few of 19.18 these extensions in earlier chapters.</para> 19.19 <itemizedlist> 19.20 - <listitem><para>Section <xref linkend="sec:tour-merge:fetch"/> 19.21 + <listitem><para id="x_500">Section <xref linkend="sec:tour-merge:fetch"/> 19.22 covers the <literal role="hg-ext">fetch</literal> extension; 19.23 this combines pulling new changes and merging them with local 19.24 changes into a single command, <command 19.25 role="hg-ext-fetch">fetch</command>.</para> 19.26 </listitem> 19.27 - <listitem><para>In chapter <xref linkend="chap:hook"/>, we covered 19.28 + <listitem><para id="x_501">In chapter <xref linkend="chap:hook"/>, we covered 19.29 several extensions that are useful for hook-related 19.30 functionality: <literal role="hg-ext">acl</literal> adds 19.31 access control lists; <literal 19.32 @@ -30,7 +30,7 @@ 19.33 role="hg-ext">notify</literal> sends notification emails on 19.34 new changes.</para> 19.35 </listitem> 19.36 - <listitem><para>The Mercurial Queues patch management extension is 19.37 + <listitem><para id="x_502">The Mercurial Queues patch management extension is 19.38 so invaluable that it merits two chapters and an appendix all 19.39 to itself. Chapter <xref linkend="chap:mq"/> covers the 19.40 basics; chapter <xref 19.41 @@ -40,12 +40,12 @@ 19.42 command.</para> 19.43 </listitem></itemizedlist> 19.44 19.45 - <para>In this chapter, we'll cover some of the other extensions that 19.46 + <para id="x_503">In this chapter, we'll cover some of the other extensions that 19.47 are available for Mercurial, and briefly touch on some of the 19.48 machinery you'll need to know about if you want to write an 19.49 extension of your own.</para> 19.50 <itemizedlist> 19.51 - <listitem><para>In section <xref linkend="sec:hgext:inotify"/>, 19.52 + <listitem><para id="x_504">In section <xref linkend="sec:hgext:inotify"/>, 19.53 we'll discuss the possibility of <emphasis>huge</emphasis> 19.54 performance improvements using the <literal 19.55 role="hg-ext">inotify</literal> extension.</para> 19.56 @@ -55,11 +55,11 @@ 19.57 <title>Improve performance with the <literal 19.58 role="hg-ext">inotify</literal> extension</title> 19.59 19.60 - <para>Are you interested in having some of the most common 19.61 + <para id="x_505">Are you interested in having some of the most common 19.62 Mercurial operations run as much as a hundred times faster? 19.63 Read on!</para> 19.64 19.65 - <para>Mercurial has great performance under normal circumstances. 19.66 + <para id="x_506">Mercurial has great performance under normal circumstances. 19.67 For example, when you run the <command role="hg-cmd">hg 19.68 status</command> command, Mercurial has to scan almost every 19.69 directory and file in your repository so that it can display 19.70 @@ -69,7 +69,7 @@ 19.71 machinery to avoid doing an expensive comparison operation on 19.72 files that obviously haven't changed.</para> 19.73 19.74 - <para>Because obtaining file status is crucial to good 19.75 + <para id="x_507">Because obtaining file status is crucial to good 19.76 performance, the authors of Mercurial have optimised this code 19.77 to within an inch of its life. However, there's no avoiding the 19.78 fact that when you run <command role="hg-cmd">hg 19.79 @@ -79,20 +79,20 @@ 19.80 checked. For a sufficiently large repository, this can take a 19.81 long time.</para> 19.82 19.83 - <para>To put a number on the magnitude of this effect, I created a 19.84 + <para id="x_508">To put a number on the magnitude of this effect, I created a 19.85 repository containing 150,000 managed files. I timed <command 19.86 role="hg-cmd">hg status</command> as taking ten seconds to 19.87 run, even when <emphasis>none</emphasis> of those files had been 19.88 modified.</para> 19.89 19.90 - <para>Many modern operating systems contain a file notification 19.91 + <para id="x_509">Many modern operating systems contain a file notification 19.92 facility. If a program signs up to an appropriate service, the 19.93 operating system will notify it every time a file of interest is 19.94 created, modified, or deleted. On Linux systems, the kernel 19.95 component that does this is called 19.96 <literal>inotify</literal>.</para> 19.97 19.98 - <para>Mercurial's <literal role="hg-ext">inotify</literal> 19.99 + <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 19.100 extension talks to the kernel's <literal>inotify</literal> 19.101 component to optimise <command role="hg-cmd">hg status</command> 19.102 commands. The extension has two components. A daemon sits in 19.103 @@ -105,29 +105,29 @@ 19.104 with a result instantaneously, avoiding the need to scan every 19.105 directory and file in the repository.</para> 19.106 19.107 - <para>Recall the ten seconds that I measured plain Mercurial as 19.108 + <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 19.109 taking to run <command role="hg-cmd">hg status</command> on a 19.110 150,000 file repository. With the <literal 19.111 role="hg-ext">inotify</literal> extension enabled, the time 19.112 dropped to 0.1 seconds, a factor of <emphasis>one 19.113 hundred</emphasis> faster.</para> 19.114 19.115 - <para>Before we continue, please pay attention to some 19.116 + <para id="x_50c">Before we continue, please pay attention to some 19.117 caveats.</para> 19.118 <itemizedlist> 19.119 - <listitem><para>The <literal role="hg-ext">inotify</literal> 19.120 + <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 19.121 extension is Linux-specific. Because it interfaces directly 19.122 to the Linux kernel's <literal>inotify</literal> subsystem, 19.123 it does not work on other operating systems.</para> 19.124 </listitem> 19.125 - <listitem><para>It should work on any Linux distribution that 19.126 + <listitem><para id="x_50e">It should work on any Linux distribution that 19.127 was released after early 2005. Older distributions are 19.128 likely to have a kernel that lacks 19.129 <literal>inotify</literal>, or a version of 19.130 <literal>glibc</literal> that does not have the necessary 19.131 interfacing support.</para> 19.132 </listitem> 19.133 - <listitem><para>Not all filesystems are suitable for use with 19.134 + <listitem><para id="x_50f">Not all filesystems are suitable for use with 19.135 the <literal role="hg-ext">inotify</literal> extension. 19.136 Network filesystems such as NFS are a non-starter, for 19.137 example, particularly if you're running Mercurial on several 19.138 @@ -138,40 +138,40 @@ 19.139 fine.</para> 19.140 </listitem></itemizedlist> 19.141 19.142 - <para>The <literal role="hg-ext">inotify</literal> extension is 19.143 + <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 19.144 not yet shipped with Mercurial as of May 2007, so it's a little 19.145 more involved to set up than other extensions. But the 19.146 performance improvement is worth it!</para> 19.147 19.148 - <para>The extension currently comes in two parts: a set of patches 19.149 + <para id="x_511">The extension currently comes in two parts: a set of patches 19.150 to the Mercurial source code, and a library of Python bindings 19.151 to the <literal>inotify</literal> subsystem.</para> 19.152 <note> 19.153 - <para> There are <emphasis>two</emphasis> Python 19.154 + <para id="x_512"> There are <emphasis>two</emphasis> Python 19.155 <literal>inotify</literal> binding libraries. One of them is 19.156 called <literal>pyinotify</literal>, and is packaged by some 19.157 Linux distributions as <literal>python-inotify</literal>. 19.158 This is <emphasis>not</emphasis> the one you'll need, as it is 19.159 too buggy and inefficient to be practical.</para> 19.160 </note> 19.161 - <para>To get going, it's best to already have a functioning copy 19.162 + <para id="x_513">To get going, it's best to already have a functioning copy 19.163 of Mercurial installed.</para> 19.164 <note> 19.165 - <para> If you follow the instructions below, you'll be 19.166 + <para id="x_514"> If you follow the instructions below, you'll be 19.167 <emphasis>replacing</emphasis> and overwriting any existing 19.168 installation of Mercurial that you might already have, using 19.169 the latest <quote>bleeding edge</quote> Mercurial code. Don't 19.170 say you weren't warned!</para> 19.171 </note> 19.172 <orderedlist> 19.173 - <listitem><para>Clone the Python <literal>inotify</literal> 19.174 + <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 19.175 binding repository. Build and install it.</para> 19.176 <programlisting>hg clone http://hg.kublai.com/python/inotify 19.177 cd inotify 19.178 python setup.py build --force 19.179 sudo python setup.py install --skip-build</programlisting> 19.180 </listitem> 19.181 - <listitem><para>Clone the <filename 19.182 + <listitem><para id="x_516">Clone the <filename 19.183 class="directory">crew</filename> Mercurial repository. 19.184 Clone the <literal role="hg-ext">inotify</literal> patch 19.185 repository so that Mercurial Queues will be able to apply 19.186 @@ -181,13 +181,13 @@ 19.187 hg clone crew inotify 19.188 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 19.189 </listitem> 19.190 - <listitem><para>Make sure that you have the Mercurial Queues 19.191 + <listitem><para id="x_517">Make sure that you have the Mercurial Queues 19.192 extension, <literal role="hg-ext">mq</literal>, enabled. If 19.193 you've never used MQ, read section <xref 19.194 linkend="sec:mq:start"/> to get started 19.195 quickly.</para> 19.196 </listitem> 19.197 - <listitem><para>Go into the <filename 19.198 + <listitem><para id="x_518">Go into the <filename 19.199 class="directory">inotify</filename> repo, and apply all 19.200 of the <literal role="hg-ext">inotify</literal> patches 19.201 using the <option role="hg-ext-mq-cmd-qpush-opt">hg 19.202 @@ -196,28 +196,28 @@ 19.203 <programlisting>cd inotify 19.204 hg qpush -a</programlisting> 19.205 </listitem> 19.206 - <listitem><para> If you get an error message from <command 19.207 + <listitem><para id="x_519"> If you get an error message from <command 19.208 role="hg-ext-mq">qpush</command>, you should not continue. 19.209 Instead, ask for help.</para> 19.210 </listitem> 19.211 - <listitem><para>Build and install the patched version of 19.212 + <listitem><para id="x_51a">Build and install the patched version of 19.213 Mercurial.</para> 19.214 <programlisting>python setup.py build --force 19.215 sudo python setup.py install --skip-build</programlisting> 19.216 </listitem> 19.217 </orderedlist> 19.218 - <para>Once you've build a suitably patched version of Mercurial, 19.219 + <para id="x_51b">Once you've build a suitably patched version of Mercurial, 19.220 all you need to do to enable the <literal 19.221 role="hg-ext">inotify</literal> extension is add an entry to 19.222 your <filename role="special">~/.hgrc</filename>.</para> 19.223 <programlisting>[extensions] inotify =</programlisting> 19.224 - <para>When the <literal role="hg-ext">inotify</literal> extension 19.225 + <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 19.226 is enabled, Mercurial will automatically and transparently start 19.227 the status daemon the first time you run a command that needs 19.228 status in a repository. It runs one status daemon per 19.229 repository.</para> 19.230 19.231 - <para>The status daemon is started silently, and runs in the 19.232 + <para id="x_51d">The status daemon is started silently, and runs in the 19.233 background. If you look at a list of running processes after 19.234 you've enabled the <literal role="hg-ext">inotify</literal> 19.235 extension and run a few commands in different repositories, 19.236 @@ -225,7 +225,7 @@ 19.237 around, waiting for updates from the kernel and queries from 19.238 Mercurial.</para> 19.239 19.240 - <para>The first time you run a Mercurial command in a repository 19.241 + <para id="x_51e">The first time you run a Mercurial command in a repository 19.242 when you have the <literal role="hg-ext">inotify</literal> 19.243 extension enabled, it will run with about the same performance 19.244 as a normal Mercurial command. This is because the status 19.245 @@ -239,14 +239,14 @@ 19.246 status operations almost instantaneous on repositories of all 19.247 sizes!</para> 19.248 19.249 - <para>If you like, you can manually start a status daemon using 19.250 + <para id="x_51f">If you like, you can manually start a status daemon using 19.251 the <command role="hg-ext-inotify">inserve</command> command. 19.252 This gives you slightly finer control over how the daemon ought 19.253 to run. This command will of course only be available when the 19.254 <literal role="hg-ext">inotify</literal> extension is 19.255 enabled.</para> 19.256 19.257 - <para>When you're using the <literal 19.258 + <para id="x_520">When you're using the <literal 19.259 role="hg-ext">inotify</literal> extension, you should notice 19.260 <emphasis>no difference at all</emphasis> in Mercurial's 19.261 behaviour, with the sole exception of status-related commands 19.262 @@ -260,24 +260,24 @@ 19.263 <title>Flexible diff support with the <literal 19.264 role="hg-ext">extdiff</literal> extension</title> 19.265 19.266 - <para>Mercurial's built-in <command role="hg-cmd">hg 19.267 + <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 19.268 diff</command> command outputs plaintext unified diffs.</para> 19.269 19.270 &interaction.extdiff.diff; 19.271 19.272 - <para>If you would like to use an external tool to display 19.273 + <para id="x_522">If you would like to use an external tool to display 19.274 modifications, you'll want to use the <literal 19.275 role="hg-ext">extdiff</literal> extension. This will let you 19.276 use, for example, a graphical diff tool.</para> 19.277 19.278 - <para>The <literal role="hg-ext">extdiff</literal> extension is 19.279 + <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 19.280 bundled with Mercurial, so it's easy to set up. In the <literal 19.281 role="rc-extensions">extensions</literal> section of your 19.282 <filename role="special">~/.hgrc</filename>, simply add a 19.283 one-line entry to enable the extension.</para> 19.284 <programlisting>[extensions] 19.285 extdiff =</programlisting> 19.286 - <para>This introduces a command named <command 19.287 + <para id="x_524">This introduces a command named <command 19.288 role="hg-ext-extdiff">extdiff</command>, which by default uses 19.289 your system's <command>diff</command> command to generate a 19.290 unified diff in the same form as the built-in <command 19.291 @@ -285,12 +285,12 @@ 19.292 19.293 &interaction.extdiff.extdiff; 19.294 19.295 - <para>The result won't be exactly the same as with the built-in 19.296 + <para id="x_525">The result won't be exactly the same as with the built-in 19.297 <command role="hg-cmd">hg diff</command> variations, because the 19.298 output of <command>diff</command> varies from one system to 19.299 another, even when passed the same options.</para> 19.300 19.301 - <para>As the <quote><literal>making snapshot</literal></quote> 19.302 + <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 19.303 lines of output above imply, the <command 19.304 role="hg-ext-extdiff">extdiff</command> command works by 19.305 creating two snapshots of your source tree. The first snapshot 19.306 @@ -303,7 +303,7 @@ 19.307 directories and files that have changed between the two 19.308 revisions.</para> 19.309 19.310 - <para>Snapshot directory names have the same base name as your 19.311 + <para id="x_527">Snapshot directory names have the same base name as your 19.312 repository. If your repository path is <filename 19.313 class="directory">/quux/bar/foo</filename>, then <filename 19.314 class="directory">foo</filename> will be the name of each 19.315 @@ -319,7 +319,7 @@ 19.316 that the diff has the snapshot directory names embedded in its 19.317 header.</para> 19.318 19.319 - <para>The <command role="hg-ext-extdiff">extdiff</command> command 19.320 + <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 19.321 accepts two important options. The <option 19.322 role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 19.323 lets you choose a program to view differences with, instead of 19.324 @@ -336,7 +336,7 @@ 19.325 and arguments to specify the revisions you want, the files you 19.326 want, and so on.</para> 19.327 19.328 - <para>As an example, here's how to run the normal system 19.329 + <para id="x_529">As an example, here's how to run the normal system 19.330 <command>diff</command> command, getting it to generate context 19.331 diffs (using the <option role="cmd-opt-diff">-c</option> option) 19.332 instead of unified diffs, and five lines of context instead of 19.333 @@ -345,11 +345,11 @@ 19.334 19.335 &interaction.extdiff.extdiff-ctx; 19.336 19.337 - <para>Launching a visual diff tool is just as easy. Here's how to 19.338 + <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 19.339 launch the <command>kdiff3</command> viewer.</para> 19.340 <programlisting>hg extdiff -p kdiff3 -o</programlisting> 19.341 19.342 - <para>If your diff viewing command can't deal with directories, 19.343 + <para id="x_52b">If your diff viewing command can't deal with directories, 19.344 you can easily work around this with a little scripting. For an 19.345 example of such scripting in action with the <literal 19.346 role="hg-ext">mq</literal> extension and the 19.347 @@ -359,14 +359,14 @@ 19.348 <sect2> 19.349 <title>Defining command aliases</title> 19.350 19.351 - <para>It can be cumbersome to remember the options to both the 19.352 + <para id="x_52c">It can be cumbersome to remember the options to both the 19.353 <command role="hg-ext-extdiff">extdiff</command> command and 19.354 the diff viewer you want to use, so the <literal 19.355 role="hg-ext">extdiff</literal> extension lets you define 19.356 <emphasis>new</emphasis> commands that will invoke your diff 19.357 viewer with exactly the right options.</para> 19.358 19.359 - <para>All you need to do is edit your <filename 19.360 + <para id="x_52d">All you need to do is edit your <filename 19.361 role="special">~/.hgrc</filename>, and add a section named 19.362 <literal role="rc-extdiff">extdiff</literal>. Inside this 19.363 section, you can define multiple commands. Here's how to add 19.364 @@ -376,7 +376,7 @@ 19.365 will run <command>kdiff3</command> for you.</para> 19.366 <programlisting>[extdiff] 19.367 cmd.kdiff3 =</programlisting> 19.368 - <para>If you leave the right hand side of the definition empty, 19.369 + <para id="x_52e">If you leave the right hand side of the definition empty, 19.370 as above, the <literal role="hg-ext">extdiff</literal> 19.371 extension uses the name of the command you defined as the name 19.372 of the external program to run. But these names don't have to 19.373 @@ -386,7 +386,7 @@ 19.374 <programlisting>[extdiff] 19.375 cmd.wibble = kdiff3</programlisting> 19.376 19.377 - <para>You can also specify the default options that you want to 19.378 + <para id="x_52f">You can also specify the default options that you want to 19.379 invoke your diff viewing program with. The prefix to use is 19.380 <quote><literal>opts.</literal></quote>, followed by the name 19.381 of the command to which the options apply. This example 19.382 @@ -403,14 +403,14 @@ 19.383 <title>Cherrypicking changes with the <literal 19.384 role="hg-ext">transplant</literal> extension</title> 19.385 19.386 - <para>Need to have a long chat with Brendan about this.</para> 19.387 + <para id="x_530">Need to have a long chat with Brendan about this.</para> 19.388 19.389 </sect1> 19.390 <sect1 id="sec:hgext:patchbomb"> 19.391 <title>Send changes via email with the <literal 19.392 role="hg-ext">patchbomb</literal> extension</title> 19.393 19.394 - <para>Many projects have a culture of <quote>change 19.395 + <para id="x_531">Many projects have a culture of <quote>change 19.396 review</quote>, in which people send their modifications to a 19.397 mailing list for others to read and comment on before they 19.398 commit the final version to a shared repository. Some projects 19.399 @@ -418,7 +418,7 @@ 19.400 other people to a repository to which those others don't have 19.401 access.</para> 19.402 19.403 - <para>Mercurial makes it easy to send changes over email for 19.404 + <para id="x_532">Mercurial makes it easy to send changes over email for 19.405 review or application, via its <literal 19.406 role="hg-ext">patchbomb</literal> extension. The extension is 19.407 so named because changes are formatted as patches, and it's usual 19.408 @@ -426,17 +426,17 @@ 19.409 of changes by email is thus much like <quote>bombing</quote> the 19.410 recipient's inbox, hence <quote>patchbomb</quote>.</para> 19.411 19.412 - <para>As usual, the basic configuration of the <literal 19.413 + <para id="x_533">As usual, the basic configuration of the <literal 19.414 role="hg-ext">patchbomb</literal> extension takes just one or 19.415 two lines in your <filename role="special"> 19.416 /.hgrc</filename>.</para> 19.417 <programlisting>[extensions] 19.418 patchbomb =</programlisting> 19.419 - <para>Once you've enabled the extension, you will have a new 19.420 + <para id="x_534">Once you've enabled the extension, you will have a new 19.421 command available, named <command 19.422 role="hg-ext-patchbomb">email</command>.</para> 19.423 19.424 - <para>The safest and best way to invoke the <command 19.425 + <para id="x_535">The safest and best way to invoke the <command 19.426 role="hg-ext-patchbomb">email</command> command is to 19.427 <emphasis>always</emphasis> run it first with the <option 19.428 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 19.429 @@ -447,12 +447,12 @@ 19.430 role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 19.431 removed.</para> 19.432 19.433 - <para>The <command role="hg-ext-patchbomb">email</command> command 19.434 + <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 19.435 accepts the same kind of revision syntax as every other 19.436 Mercurial command. For example, this command will send every 19.437 revision between 7 and <literal>tip</literal>, inclusive.</para> 19.438 <programlisting>hg email -n 7:tip</programlisting> 19.439 - <para>You can also specify a <emphasis>repository</emphasis> to 19.440 + <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 19.441 compare with. If you provide a repository but no revisions, the 19.442 <command role="hg-ext-patchbomb">email</command> command will 19.443 send all revisions in the local repository that are not present 19.444 @@ -461,7 +461,7 @@ 19.445 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 19.446 this will constrain the revisions sent.</para> 19.447 19.448 - <para>It's perfectly safe to run the <command 19.449 + <para id="x_538">It's perfectly safe to run the <command 19.450 role="hg-ext-patchbomb">email</command> command without the 19.451 names of the people you want to send to: if you do this, it will 19.452 just prompt you for those values interactively. (If you're 19.453 @@ -469,12 +469,12 @@ 19.454 <literal>readline</literal>-style editing capabilities when 19.455 entering those headers, too, which is useful.)</para> 19.456 19.457 - <para>When you are sending just one revision, the <command 19.458 + <para id="x_539">When you are sending just one revision, the <command 19.459 role="hg-ext-patchbomb">email</command> command will by 19.460 default use the first line of the changeset description as the 19.461 subject of the single email message it sends.</para> 19.462 19.463 - <para>If you send multiple revisions, the <command 19.464 + <para id="x_53a">If you send multiple revisions, the <command 19.465 role="hg-ext-patchbomb">email</command> command will usually 19.466 send one message per changeset. It will preface the series with 19.467 an introductory message, in which you should describe the 19.468 @@ -483,25 +483,25 @@ 19.469 <sect2> 19.470 <title>Changing the behaviour of patchbombs</title> 19.471 19.472 - <para>Not every project has exactly the same conventions for 19.473 + <para id="x_53b">Not every project has exactly the same conventions for 19.474 sending changes in email; the <literal 19.475 role="hg-ext">patchbomb</literal> extension tries to 19.476 accommodate a number of variations through command line 19.477 options.</para> 19.478 <itemizedlist> 19.479 - <listitem><para>You can write a subject for the introductory 19.480 + <listitem><para id="x_53c">You can write a subject for the introductory 19.481 message on the command line using the <option 19.482 role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 19.483 option. This takes one argument, the text of the subject 19.484 to use.</para> 19.485 </listitem> 19.486 - <listitem><para>To change the email address from which the 19.487 + <listitem><para id="x_53d">To change the email address from which the 19.488 messages originate, use the <option 19.489 role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 19.490 option. This takes one argument, the email address to 19.491 use.</para> 19.492 </listitem> 19.493 - <listitem><para>The default behaviour is to send unified diffs 19.494 + <listitem><para id="x_53e">The default behaviour is to send unified diffs 19.495 (see section <xref linkend="sec:mq:patch"/> for a 19.496 description of the 19.497 format), one per message. You can send a binary bundle 19.498 @@ -509,13 +509,13 @@ 19.499 role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 19.500 option.</para> 19.501 </listitem> 19.502 - <listitem><para>Unified diffs are normally prefaced with a 19.503 + <listitem><para id="x_53f">Unified diffs are normally prefaced with a 19.504 metadata header. You can omit this, and send unadorned 19.505 diffs, with the <option 19.506 role="hg-ext-patchbomb-cmd-email-opt">hg 19.507 --plain</option> option.</para> 19.508 </listitem> 19.509 - <listitem><para>Diffs are normally sent <quote>inline</quote>, 19.510 + <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 19.511 in the same body part as the description of a patch. This 19.512 makes it easiest for the largest number of readers to 19.513 quote and respond to parts of a diff, as some mail clients 19.514 @@ -525,14 +525,14 @@ 19.515 role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 19.516 option.</para> 19.517 </listitem> 19.518 - <listitem><para>Instead of sending mail messages, you can 19.519 + <listitem><para id="x_541">Instead of sending mail messages, you can 19.520 write them to an <literal>mbox</literal>-format mail 19.521 folder using the <option 19.522 role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 19.523 option. That option takes one argument, the name of the 19.524 file to write to.</para> 19.525 </listitem> 19.526 - <listitem><para>If you would like to add a 19.527 + <listitem><para id="x_542">If you would like to add a 19.528 <command>diffstat</command>-format summary to each patch, 19.529 and one to the introductory message, use the <option 19.530 role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>