hgbook
changeset 987:f0110009e946
french translation : sync with original files (en/ch05 to en/ch14 and appD)
author | Frédéric Bouquet <youshe.jaalon@gmail.com> |
---|---|
date | Wed Sep 09 16:07:36 2009 +0200 (2009-09-09) |
parents | c075fb0481c0 |
children | 72de97557f11 |
files | fr/appD-license.xml fr/ch05-daily.xml fr/ch06-collab.xml fr/ch07-filenames.xml fr/ch08-branch.xml fr/ch09-undo.xml fr/ch10-hook.xml fr/ch11-template.xml fr/ch12-mq.xml fr/ch13-mq-collab.xml fr/ch14-hgext.xml |
line diff
1.1 --- a/fr/appD-license.xml Wed Sep 09 15:25:09 2009 +0200 1.2 +++ b/fr/appD-license.xml Wed Sep 09 16:07:36 2009 +0200 1.3 @@ -1,185 +1,179 @@ 1.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 1.6 -<chapter> 1.7 -<title>Open Publication License</title> 1.8 -<para>\label{cha:opl}</para> 1.9 +<appendix id="cha:opl"> 1.10 + <?dbhtml filename="open-publication-license.html"?> 1.11 + <title>Open Publication License</title> 1.12 1.13 -<para>Version 1.0, 8 June 1999</para> 1.14 + <para id="x_638">Version 1.0, 8 June 1999</para> 1.15 1.16 -<sect1> 1.17 -<title>Requirements on both unmodified and modified versions</title> 1.18 + <sect1> 1.19 + <title>Requirements on both unmodified and modified 1.20 + versions</title> 1.21 1.22 -<para>The Open Publication works may be reproduced and distributed in whole 1.23 -or in part, in any medium physical or electronic, provided that the 1.24 -terms of this license are adhered to, and that this license or an 1.25 -incorporation of it by reference (with any options elected by the 1.26 -author(s) and/or publisher) is displayed in the reproduction.</para> 1.27 + <para id="x_639">The Open Publication works may be reproduced and distributed 1.28 + in whole or in part, in any medium physical or electronic, 1.29 + provided that the terms of this license are adhered to, and that 1.30 + this license or an incorporation of it by reference (with any 1.31 + options elected by the author(s) and/or publisher) is displayed 1.32 + in the reproduction.</para> 1.33 1.34 -<para>Proper form for an incorporation by reference is as follows:</para> 1.35 + <para id="x_63a">Proper form for an incorporation by reference is as 1.36 + follows:</para> 1.37 1.38 -<blockquote> 1.39 -<para> Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or designee</emphasis>. This 1.40 - material may be distributed only subject to the terms and conditions 1.41 - set forth in the Open Publication License, v<emphasis>x.y</emphasis> or later (the 1.42 - latest version is presently available at 1.43 - <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para> 1.44 -</blockquote> 1.45 + <blockquote> 1.46 + <para id="x_63b"> Copyright (c) <emphasis>year</emphasis> by 1.47 + <emphasis>author's name or designee</emphasis>. This material 1.48 + may be distributed only subject to the terms and conditions 1.49 + set forth in the Open Publication License, 1.50 + v<emphasis>x.y</emphasis> or later (the latest version is 1.51 + presently available at <ulink 1.52 + url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para> 1.53 + </blockquote> 1.54 1.55 -<para>The reference must be immediately followed with any options elected by 1.56 -the author(s) and/or publisher of the document (see 1.57 -section <xref linkend="sec:opl:options"/>).</para> 1.58 + <para id="x_63c">The reference must be immediately followed with any options 1.59 + elected by the author(s) and/or publisher of the document (see 1.60 + <xref linkend="sec:opl:options"/>).</para> 1.61 1.62 -<para>Commercial redistribution of Open Publication-licensed material is 1.63 -permitted.</para> 1.64 + <para id="x_63d">Commercial redistribution of Open Publication-licensed 1.65 + material is permitted.</para> 1.66 1.67 -<para>Any publication in standard (paper) book form shall require the 1.68 -citation of the original publisher and author. The publisher and 1.69 -author's names shall appear on all outer surfaces of the book. On all 1.70 -outer surfaces of the book the original publisher's name shall be as 1.71 -large as the title of the work and cited as possessive with respect to 1.72 -the title.</para> 1.73 + <para id="x_63e">Any publication in standard (paper) book form shall require 1.74 + the citation of the original publisher and author. The publisher 1.75 + and author's names shall appear on all outer surfaces of the 1.76 + book. On all outer surfaces of the book the original publisher's 1.77 + name shall be as large as the title of the work and cited as 1.78 + possessive with respect to the title.</para> 1.79 1.80 -</sect1> 1.81 -<sect1> 1.82 -<title>Copyright</title> 1.83 + </sect1> 1.84 + <sect1> 1.85 + <title>Copyright</title> 1.86 1.87 -<para>The copyright to each Open Publication is owned by its author(s) or 1.88 -designee. 1.89 -</para> 1.90 + <para id="x_63f">The copyright to each Open Publication is owned by its 1.91 + author(s) or designee.</para> 1.92 1.93 -</sect1> 1.94 -<sect1> 1.95 -<title>Scope of license</title> 1.96 + </sect1> 1.97 + <sect1> 1.98 + <title>Scope of license</title> 1.99 1.100 -<para>The following license terms apply to all Open Publication works, 1.101 -unless otherwise explicitly stated in the document. 1.102 -</para> 1.103 + <para id="x_640">The following license terms apply to all Open Publication 1.104 + works, unless otherwise explicitly stated in the 1.105 + document.</para> 1.106 1.107 -<para>Mere aggregation of Open Publication works or a portion of an Open 1.108 -Publication work with other works or programs on the same media shall 1.109 -not cause this license to apply to those other works. The aggregate 1.110 -work shall contain a notice specifying the inclusion of the Open 1.111 -Publication material and appropriate copyright notice. 1.112 -</para> 1.113 + <para id="x_641">Mere aggregation of Open Publication works or a portion of 1.114 + an Open Publication work with other works or programs on the 1.115 + same media shall not cause this license to apply to those other 1.116 + works. The aggregate work shall contain a notice specifying the 1.117 + inclusion of the Open Publication material and appropriate 1.118 + copyright notice.</para> 1.119 1.120 -<para><emphasis role="bold">Severability</emphasis>. If any part of this license is found to be 1.121 -unenforceable in any jurisdiction, the remaining portions of the 1.122 -license remain in force. 1.123 -</para> 1.124 + <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part 1.125 + of this license is found to be unenforceable in any 1.126 + jurisdiction, the remaining portions of the license remain in 1.127 + force.</para> 1.128 1.129 -<para><emphasis role="bold">No warranty</emphasis>. Open Publication works are licensed and provided 1.130 -<quote>as is</quote> without warranty of any kind, express or implied, including, 1.131 -but not limited to, the implied warranties of merchantability and 1.132 -fitness for a particular purpose or a warranty of non-infringement. 1.133 -</para> 1.134 + <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open 1.135 + Publication works are licensed and provided <quote>as is</quote> 1.136 + without warranty of any kind, express or implied, including, but 1.137 + not limited to, the implied warranties of merchantability and 1.138 + fitness for a particular purpose or a warranty of 1.139 + non-infringement.</para> 1.140 1.141 -</sect1> 1.142 -<sect1> 1.143 -<title>Requirements on modified works</title> 1.144 + </sect1> 1.145 + <sect1> 1.146 + <title>Requirements on modified works</title> 1.147 1.148 -<para>All modified versions of documents covered by this license, including 1.149 -translations, anthologies, compilations and partial documents, must 1.150 -meet the following requirements: 1.151 -</para> 1.152 + <para id="x_644">All modified versions of documents covered by this license, 1.153 + including translations, anthologies, compilations and partial 1.154 + documents, must meet the following requirements:</para> 1.155 1.156 -<orderedlist> 1.157 -<listitem><para>The modified version must be labeled as such. 1.158 -</para> 1.159 -</listitem> 1.160 -<listitem><para>The person making the modifications must be identified and the 1.161 - modifications dated. 1.162 -</para> 1.163 -</listitem> 1.164 -<listitem><para>Acknowledgement of the original author and publisher if 1.165 - applicable must be retained according to normal academic citation 1.166 - practices. 1.167 -</para> 1.168 -</listitem> 1.169 -<listitem><para>The location of the original unmodified document must be 1.170 - identified. 1.171 -</para> 1.172 -</listitem> 1.173 -<listitem><para>The original author's (or authors') name(s) may not be used to 1.174 - assert or imply endorsement of the resulting document without the 1.175 - original author's (or authors') permission. 1.176 -</para> 1.177 -</listitem></orderedlist> 1.178 + <orderedlist> 1.179 + <listitem><para id="x_645">The modified version must be labeled as 1.180 + such.</para> 1.181 + </listitem> 1.182 + <listitem><para id="x_646">The person making the modifications must be 1.183 + identified and the modifications dated.</para> 1.184 + </listitem> 1.185 + <listitem><para id="x_647">Acknowledgement of the original author and 1.186 + publisher if applicable must be retained according to normal 1.187 + academic citation practices.</para> 1.188 + </listitem> 1.189 + <listitem><para id="x_648">The location of the original unmodified document 1.190 + must be identified.</para> 1.191 + </listitem> 1.192 + <listitem><para id="x_649">The original author's (or authors') name(s) may 1.193 + not be used to assert or imply endorsement of the resulting 1.194 + document without the original author's (or authors') 1.195 + permission.</para> 1.196 + </listitem></orderedlist> 1.197 1.198 -</sect1> 1.199 -<sect1> 1.200 -<title>Good-practice recommendations</title> 1.201 + </sect1> 1.202 + <sect1> 1.203 + <title>Good-practice recommendations</title> 1.204 1.205 -<para>In addition to the requirements of this license, it is requested from 1.206 -and strongly recommended of redistributors that: 1.207 -</para> 1.208 + <para id="x_64a">In addition to the requirements of this license, it is 1.209 + requested from and strongly recommended of redistributors 1.210 + that:</para> 1.211 1.212 -<orderedlist> 1.213 -<listitem><para>If you are distributing Open Publication works on hardcopy or 1.214 - CD-ROM, you provide email notification to the authors of your intent 1.215 - to redistribute at least thirty days before your manuscript or media 1.216 - freeze, to give the authors time to provide updated documents. This 1.217 - notification should describe modifications, if any, made to the 1.218 - document. 1.219 -</para> 1.220 -</listitem> 1.221 -<listitem><para>All substantive modifications (including deletions) be either 1.222 - clearly marked up in the document or else described in an attachment 1.223 - to the document. 1.224 -</para> 1.225 -</listitem> 1.226 -<listitem><para>Finally, while it is not mandatory under this license, it is 1.227 - considered good form to offer a free copy of any hardcopy and CD-ROM 1.228 - expression of an Open Publication-licensed work to its author(s). 1.229 -</para> 1.230 -</listitem></orderedlist> 1.231 + <orderedlist> 1.232 + <listitem><para id="x_64b">If you are distributing Open Publication works 1.233 + on hardcopy or CD-ROM, you provide email notification to the 1.234 + authors of your intent to redistribute at least thirty days 1.235 + before your manuscript or media freeze, to give the authors 1.236 + time to provide updated documents. This notification should 1.237 + describe modifications, if any, made to the document.</para> 1.238 + </listitem> 1.239 + <listitem><para id="x_64c">All substantive modifications (including 1.240 + deletions) be either clearly marked up in the document or 1.241 + else described in an attachment to the document.</para> 1.242 + </listitem> 1.243 + <listitem><para id="x_64d">Finally, while it is not mandatory under this 1.244 + license, it is considered good form to offer a free copy of 1.245 + any hardcopy and CD-ROM expression of an Open 1.246 + Publication-licensed work to its author(s).</para> 1.247 + </listitem></orderedlist> 1.248 1.249 -</sect1> 1.250 -<sect1> 1.251 -<title>License options</title> 1.252 -<para>\label{sec:opl:options} 1.253 -</para> 1.254 + </sect1> 1.255 + <sect1 id="sec:opl:options"> 1.256 + <title>License options</title> 1.257 1.258 -<para>The author(s) and/or publisher of an Open Publication-licensed 1.259 -document may elect certain options by appending language to the 1.260 -reference to or copy of the license. These options are considered part 1.261 -of the license instance and must be included with the license (or its 1.262 -incorporation by reference) in derived works. 1.263 -</para> 1.264 + <para id="x_64e">The author(s) and/or publisher of an Open 1.265 + Publication-licensed document may elect certain options by 1.266 + appending language to the reference to or copy of the license. 1.267 + These options are considered part of the license instance and 1.268 + must be included with the license (or its incorporation by 1.269 + reference) in derived works.</para> 1.270 1.271 -<orderedlist> 1.272 -<listitem><para>To prohibit distribution of substantively modified versions 1.273 - without the explicit permission of the author(s). <quote>Substantive 1.274 - modification</quote> is defined as a change to the semantic content of the 1.275 - document, and excludes mere changes in format or typographical 1.276 - corrections. 1.277 -</para> 1.278 -</listitem> 1.279 -<listitem><para> To accomplish this, add the phrase <quote>Distribution of substantively 1.280 - modified versions of this document is prohibited without the 1.281 - explicit permission of the copyright holder.</quote> to the license 1.282 - reference or copy. 1.283 -</para> 1.284 -</listitem> 1.285 -</para> 1.286 -</listitem> 1.287 -<listitem><para>To prohibit any publication of this work or derivative works in 1.288 - whole or in part in standard (paper) book form for commercial 1.289 - purposes is prohibited unless prior permission is obtained from the 1.290 - copyright holder. 1.291 -</para> 1.292 -</listitem> 1.293 -<listitem><para> To accomplish this, add the phrase <quote>Distribution of the work or 1.294 - derivative of the work in any standard (paper) book form is 1.295 - prohibited unless prior permission is obtained from the copyright 1.296 - holder.</quote> to the license reference or copy. 1.297 -</para> 1.298 -</listitem></orderedlist> 1.299 + <orderedlist> 1.300 + <listitem><para id="x_64f">To prohibit distribution of substantively 1.301 + modified versions without the explicit permission of the 1.302 + author(s). <quote>Substantive modification</quote> is 1.303 + defined as a change to the semantic content of the document, 1.304 + and excludes mere changes in format or typographical 1.305 + corrections.</para> 1.306 + </listitem> 1.307 + <listitem><para id="x_650"> To accomplish this, add the phrase 1.308 + <quote>Distribution of substantively modified versions of 1.309 + this document is prohibited without the explicit 1.310 + permission of the copyright holder.</quote> to the license 1.311 + reference or copy.</para> 1.312 + </listitem> 1.313 + <listitem><para id="x_651">To prohibit any publication of this work or 1.314 + derivative works in whole or in part in standard (paper) 1.315 + book form for commercial purposes is prohibited unless prior 1.316 + permission is obtained from the copyright holder.</para> 1.317 + </listitem> 1.318 + <listitem><para id="x_652">To accomplish this, add the phrase 1.319 + <quote>Distribution of the work or derivative of the work in 1.320 + any standard (paper) book form is prohibited unless prior 1.321 + permission is obtained from the copyright holder.</quote> 1.322 + to the license reference or copy.</para> 1.323 + </listitem></orderedlist> 1.324 1.325 -</sect1> 1.326 -</chapter> 1.327 + </sect1> 1.328 +</appendix> 1.329 1.330 <!-- 1.331 local variables: 1.332 -sgml-parent-document: ("00book.xml" "book" "chapter") 1.333 +sgml-parent-document: ("00book.xml" "book" "appendix") 1.334 end: 1.335 ---> 1.336 \ No newline at end of file 1.337 +-->
2.1 --- a/fr/ch05-daily.xml Wed Sep 09 15:25:09 2009 +0200 2.2 +++ b/fr/ch05-daily.xml Wed Sep 09 16:07:36 2009 +0200 2.3 @@ -1,474 +1,840 @@ 2.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 2.5 2.6 -<chapter> 2.7 -<title>Mercurial in daily use</title> 2.8 -<para>\label{chap:daily}</para> 2.9 - 2.10 -<sect1> 2.11 -<title>Telling Mercurial which files to track</title> 2.12 - 2.13 -<para>Mercurial does not work with files in your repository unless you tell 2.14 -it to manage them. The <command role="hg-cmd">hg status</command> command will tell you which 2.15 -files Mercurial doesn't know about; it uses a <quote><literal>?</literal></quote> to 2.16 -display such files.</para> 2.17 - 2.18 -<para>To tell Mercurial to track a file, use the <command role="hg-cmd">hg add</command> command. Once 2.19 -you have added a file, the entry in the output of <command role="hg-cmd">hg status</command> for 2.20 -that file changes from <quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>. 2.21 -<!-- &interaction.daily.files.add; --></para> 2.22 - 2.23 -<para>After you run a <command role="hg-cmd">hg commit</command>, the files that you added before the 2.24 -commit will no longer be listed in the output of <command role="hg-cmd">hg status</command>. The 2.25 -reason for this is that <command role="hg-cmd">hg status</command> only tells you about 2.26 -<quote>interesting</quote> files&emdash;those that you have modified or told Mercurial 2.27 -to do something with&emdash;by default. If you have a repository that 2.28 -contains thousands of files, you will rarely want to know about files 2.29 -that Mercurial is tracking, but that have not changed. (You can still 2.30 -get this information; we'll return to this later.)</para> 2.31 - 2.32 -<para>Once you add a file, Mercurial doesn't do anything with it 2.33 -immediately. Instead, it will take a snapshot of the file's state the 2.34 -next time you perform a commit. It will then continue to track the 2.35 -changes you make to the file every time you commit, until you remove 2.36 -the file.</para> 2.37 - 2.38 -<sect2> 2.39 -<title>Explicit versus implicit file naming</title> 2.40 - 2.41 -<para>A useful behaviour that Mercurial has is that if you pass the name of 2.42 -a directory to a command, every Mercurial command will treat this as 2.43 -<quote>I want to operate on every file in this directory and its 2.44 -subdirectories</quote>. 2.45 -<!-- &interaction.daily.files.add-dir; --> 2.46 -Notice in this example that Mercurial printed the names of the files 2.47 -it added, whereas it didn't do so when we added the file named 2.48 -<filename>a</filename> in the earlier example.</para> 2.49 - 2.50 -<para>What's going on is that in the former case, we explicitly named the 2.51 -file to add on the command line, so the assumption that Mercurial 2.52 -makes in such cases is that you know what you were doing, and it 2.53 -doesn't print any output.</para> 2.54 - 2.55 -<para>However, when we <emphasis>imply</emphasis> the names of files by giving the name of 2.56 -a directory, Mercurial takes the extra step of printing the name of 2.57 -each file that it does something with. This makes it more clear what 2.58 -is happening, and reduces the likelihood of a silent and nasty 2.59 -surprise. This behaviour is common to most Mercurial commands.</para> 2.60 - 2.61 -</sect2> 2.62 -<sect2> 2.63 -<title>Aside: Mercurial tracks files, not directories</title> 2.64 - 2.65 -<para>Mercurial does not track directory information. Instead, it tracks 2.66 -the path to a file. Before creating a file, it first creates any 2.67 -missing directory components of the path. After it deletes a file, it 2.68 -then deletes any empty directories that were in the deleted file's 2.69 -path. This sounds like a trivial distinction, but it has one minor 2.70 -practical consequence: it is not possible to represent a completely 2.71 -empty directory in Mercurial. 2.72 -</para> 2.73 - 2.74 -<para>Empty directories are rarely useful, and there are unintrusive 2.75 -workarounds that you can use to achieve an appropriate effect. The 2.76 -developers of Mercurial thus felt that the complexity that would be 2.77 -required to manage empty directories was not worth the limited benefit 2.78 -this feature would bring. 2.79 -</para> 2.80 - 2.81 -<para>If you need an empty directory in your repository, there are a few 2.82 -ways to achieve this. One is to create a directory, then <command role="hg-cmd">hg add</command> a 2.83 -<quote>hidden</quote> file to that directory. On Unix-like systems, any file 2.84 -name that begins with a period (<quote><literal>.</literal></quote>) is treated as hidden 2.85 -by most commands and GUI tools. This approach is illustrated in 2.86 -figure <xref linkend="ex:daily:hidden"/>. 2.87 -</para> 2.88 - 2.89 -<informalfigure> 2.90 -<para> <!-- &interaction.daily.files.hidden; --> 2.91 - <caption><para>Simulating an empty directory using a hidden file</para></caption> 2.92 - \label{ex:daily:hidden} 2.93 -</para> 2.94 -</informalfigure> 2.95 - 2.96 -<para>Another way to tackle a need for an empty directory is to simply 2.97 -create one in your automated build scripts before they will need it. 2.98 -</para> 2.99 - 2.100 -</sect2> 2.101 -</sect1> 2.102 -<sect1> 2.103 -<title>How to stop tracking a file</title> 2.104 - 2.105 -<para>Once you decide that a file no longer belongs in your repository, use 2.106 -the <command role="hg-cmd">hg remove</command> command; this deletes the file, and tells Mercurial 2.107 -to stop tracking it. A removed file is represented in the output of 2.108 -<command role="hg-cmd">hg status</command> with a <quote><literal>R</literal></quote>. 2.109 -<!-- &interaction.daily.files.remove; --> 2.110 -</para> 2.111 - 2.112 -<para>After you <command role="hg-cmd">hg remove</command> a file, Mercurial will no longer track 2.113 -changes to that file, even if you recreate a file with the same name 2.114 -in your working directory. If you do recreate a file with the same 2.115 -name and want Mercurial to track the new file, simply <command role="hg-cmd">hg add</command> it. 2.116 -Mercurial will know that the newly added file is not related to the 2.117 -old file of the same name. 2.118 -</para> 2.119 - 2.120 -<sect2> 2.121 -<title>Removing a file does not affect its history</title> 2.122 - 2.123 -<para>It is important to understand that removing a file has only two 2.124 -effects. 2.125 -</para> 2.126 -<itemizedlist> 2.127 -<listitem><para>It removes the current version of the file from the working 2.128 - directory. 2.129 -</para> 2.130 -</listitem> 2.131 -<listitem><para>It stops Mercurial from tracking changes to the file, from the 2.132 - time of the next commit. 2.133 -</para> 2.134 -</listitem></itemizedlist> 2.135 -<para>Removing a file <emphasis>does not</emphasis> in any way alter the <emphasis>history</emphasis> of 2.136 -the file. 2.137 -</para> 2.138 - 2.139 -<para>If you update the working directory to a changeset in which a file 2.140 -that you have removed was still tracked, it will reappear in the 2.141 -working directory, with the contents it had when you committed that 2.142 -changeset. If you then update the working directory to a later 2.143 -changeset, in which the file had been removed, Mercurial will once 2.144 -again remove the file from the working directory. 2.145 -</para> 2.146 - 2.147 -</sect2> 2.148 -<sect2> 2.149 -<title>Missing files</title> 2.150 - 2.151 -<para>Mercurial considers a file that you have deleted, but not used 2.152 -<command role="hg-cmd">hg remove</command> to delete, to be <emphasis>missing</emphasis>. A missing file is 2.153 -represented with <quote><literal>!</literal></quote> in the output of <command role="hg-cmd">hg status</command>. 2.154 -Mercurial commands will not generally do anything with missing files. 2.155 -<!-- &interaction.daily.files.missing; --> 2.156 -</para> 2.157 - 2.158 -<para>If your repository contains a file that <command role="hg-cmd">hg status</command> reports as 2.159 -missing, and you want the file to stay gone, you can run 2.160 -<command role="hg-cmd">hg remove <option role="hg-opt-remove">--after</option></command> at any time later on, to 2.161 -tell Mercurial that you really did mean to remove the file. 2.162 -<!-- &interaction.daily.files.remove-after; --> 2.163 -</para> 2.164 - 2.165 -<para>On the other hand, if you deleted the missing file by accident, use 2.166 -<command role="hg-cmd">hg revert <emphasis>filename</emphasis></command> to recover the file. It will 2.167 -reappear, in unmodified form. 2.168 -<!-- &interaction.daily.files.recover-missing; --> 2.169 -</para> 2.170 - 2.171 -<para>\subsection{Aside: why tell Mercurial explicitly to 2.172 - remove a file?} 2.173 -</para> 2.174 - 2.175 -<para>You might wonder why Mercurial requires you to explicitly tell it that 2.176 -you are deleting a file. Early during the development of Mercurial, 2.177 -it let you delete a file however you pleased; Mercurial would notice 2.178 -the absence of the file automatically when you next ran a 2.179 -<command role="hg-cmd">hg commit</command>, and stop tracking the file. In practice, this made it 2.180 -too easy to accidentally remove a file without noticing. 2.181 -</para> 2.182 - 2.183 -<para>\subsection{Useful shorthand&emdash;adding and removing files 2.184 - in one step} 2.185 -</para> 2.186 - 2.187 -<para>Mercurial offers a combination command, <command role="hg-cmd">hg addremove</command>, that adds 2.188 -untracked files and marks missing files as removed. 2.189 -<!-- &interaction.daily.files.addremove; --> 2.190 -The <command role="hg-cmd">hg commit</command> command also provides a <option role="hg-opt-commit">-A</option> option 2.191 -that performs this same add-and-remove, immediately followed by a 2.192 -commit. 2.193 -<!-- &interaction.daily.files.commit-addremove; --> 2.194 -</para> 2.195 - 2.196 -</sect2> 2.197 -</sect1> 2.198 -<sect1> 2.199 -<title>Copying files</title> 2.200 - 2.201 -<para>Mercurial provides a <command role="hg-cmd">hg copy</command> command that lets you make a new 2.202 -copy of a file. When you copy a file using this command, Mercurial 2.203 -makes a record of the fact that the new file is a copy of the original 2.204 -file. It treats these copied files specially when you merge your work 2.205 -with someone else's. 2.206 -</para> 2.207 - 2.208 -<sect2> 2.209 -<title>The results of copying during a merge</title> 2.210 - 2.211 -<para>What happens during a merge is that changes <quote>follow</quote> a copy. To 2.212 -best illustrate what this means, let's create an example. We'll start 2.213 -with the usual tiny repository that contains a single file. 2.214 -<!-- &interaction.daily.copy.init; --> 2.215 -We need to do some work in parallel, so that we'll have something to 2.216 -merge. So let's clone our repository. 2.217 -<!-- &interaction.daily.copy.clone; --> 2.218 -Back in our initial repository, let's use the <command role="hg-cmd">hg copy</command> command to 2.219 -make a copy of the first file we created. 2.220 -<!-- &interaction.daily.copy.copy; --> 2.221 -</para> 2.222 - 2.223 -<para>If we look at the output of the <command role="hg-cmd">hg status</command> command afterwards, the 2.224 -copied file looks just like a normal added file. 2.225 -<!-- &interaction.daily.copy.status; --> 2.226 -But if we pass the <option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command>, it 2.227 -prints another line of output: this is the file that our newly-added 2.228 -file was copied <emphasis>from</emphasis>. 2.229 -<!-- &interaction.daily.copy.status-copy; --> 2.230 -</para> 2.231 - 2.232 -<para>Now, back in the repository we cloned, let's make a change in 2.233 -parallel. We'll add a line of content to the original file that we 2.234 -created. 2.235 -<!-- &interaction.daily.copy.other; --> 2.236 -Now we have a modified <filename>file</filename> in this repository. When we 2.237 -pull the changes from the first repository, and merge the two heads, 2.238 -Mercurial will propagate the changes that we made locally to 2.239 -<filename>file</filename> into its copy, <filename>new-file</filename>. 2.240 -<!-- &interaction.daily.copy.merge; --> 2.241 -</para> 2.242 - 2.243 -</sect2> 2.244 -<sect2> 2.245 -<title>Why should changes follow copies?</title> 2.246 -<para>\label{sec:daily:why-copy} 2.247 -</para> 2.248 - 2.249 -<para>This behaviour, of changes to a file propagating out to copies of the 2.250 -file, might seem esoteric, but in most cases it's highly desirable. 2.251 -</para> 2.252 - 2.253 -<para>First of all, remember that this propagation <emphasis>only</emphasis> happens when 2.254 -you merge. So if you <command role="hg-cmd">hg copy</command> a file, and subsequently modify the 2.255 -original file during the normal course of your work, nothing will 2.256 -happen. 2.257 -</para> 2.258 - 2.259 -<para>The second thing to know is that modifications will only propagate 2.260 -across a copy as long as the repository that you're pulling changes 2.261 -from <emphasis>doesn't know</emphasis> about the copy. 2.262 -</para> 2.263 - 2.264 -<para>The reason that Mercurial does this is as follows. Let's say I make 2.265 -an important bug fix in a source file, and commit my changes. 2.266 -Meanwhile, you've decided to <command role="hg-cmd">hg copy</command> the file in your repository, 2.267 -without knowing about the bug or having seen the fix, and you have 2.268 -started hacking on your copy of the file. 2.269 -</para> 2.270 - 2.271 -<para>If you pulled and merged my changes, and Mercurial <emphasis>didn't</emphasis> 2.272 -propagate changes across copies, your source file would now contain 2.273 -the bug, and unless you remembered to propagate the bug fix by hand, 2.274 -the bug would <emphasis>remain</emphasis> in your copy of the file. 2.275 -</para> 2.276 - 2.277 -<para>By automatically propagating the change that fixed the bug from the 2.278 -original file to the copy, Mercurial prevents this class of problem. 2.279 -To my knowledge, Mercurial is the <emphasis>only</emphasis> revision control system 2.280 -that propagates changes across copies like this. 2.281 -</para> 2.282 - 2.283 -<para>Once your change history has a record that the copy and subsequent 2.284 -merge occurred, there's usually no further need to propagate changes 2.285 -from the original file to the copied file, and that's why Mercurial 2.286 -only propagates changes across copies until this point, and no 2.287 -further. 2.288 -</para> 2.289 - 2.290 -</sect2> 2.291 -<sect2> 2.292 -<title>How to make changes <emphasis>not</emphasis> follow a copy</title> 2.293 - 2.294 -<para>If, for some reason, you decide that this business of automatically 2.295 -propagating changes across copies is not for you, simply use your 2.296 -system's normal file copy command (on Unix-like systems, that's 2.297 -<command>cp</command>) to make a copy of a file, then <command role="hg-cmd">hg add</command> the new copy 2.298 -by hand. Before you do so, though, please do reread 2.299 -section <xref linkend="sec:daily:why-copy"/>, and make an informed decision that 2.300 -this behaviour is not appropriate to your specific case. 2.301 -</para> 2.302 - 2.303 -</sect2> 2.304 -<sect2> 2.305 -<title>Behaviour of the <command role="hg-cmd">hg copy</command> command</title> 2.306 - 2.307 -<para>When you use the <command role="hg-cmd">hg copy</command> command, Mercurial makes a copy of each 2.308 -source file as it currently stands in the working directory. This 2.309 -means that if you make some modifications to a file, then <command role="hg-cmd">hg copy</command> 2.310 -it without first having committed those changes, the new copy will 2.311 -also contain the modifications you have made up until that point. (I 2.312 -find this behaviour a little counterintuitive, which is why I mention 2.313 -it here.) 2.314 -</para> 2.315 - 2.316 -<para>The <command role="hg-cmd">hg copy</command> command acts similarly to the Unix <command>cp</command> 2.317 -command (you can use the <command role="hg-cmd">hg cp</command> alias if you prefer). The last 2.318 -argument is the <emphasis>destination</emphasis>, and all prior arguments are 2.319 -<emphasis>sources</emphasis>. If you pass it a single file as the source, and the 2.320 -destination does not exist, it creates a new file with that name. 2.321 -<!-- &interaction.daily.copy.simple; --> 2.322 -If the destination is a directory, Mercurial copies its sources into 2.323 -that directory. 2.324 -<!-- &interaction.daily.copy.dir-dest; --> 2.325 -Copying a directory is recursive, and preserves the directory 2.326 -structure of the source. 2.327 -<!-- &interaction.daily.copy.dir-src; --> 2.328 -If the source and destination are both directories, the source tree is 2.329 -recreated in the destination directory. 2.330 -<!-- &interaction.daily.copy.dir-src-dest; --> 2.331 -</para> 2.332 - 2.333 -<para>As with the <command role="hg-cmd">hg rename</command> command, if you copy a file manually and 2.334 -then want Mercurial to know that you've copied the file, simply use 2.335 -the <option role="hg-opt-copy">--after</option> option to <command role="hg-cmd">hg copy</command>. 2.336 -<!-- &interaction.daily.copy.after; --> 2.337 -</para> 2.338 - 2.339 -</sect2> 2.340 -</sect1> 2.341 -<sect1> 2.342 -<title>Renaming files</title> 2.343 - 2.344 -<para>It's rather more common to need to rename a file than to make a copy 2.345 -of it. The reason I discussed the <command role="hg-cmd">hg copy</command> command before talking 2.346 -about renaming files is that Mercurial treats a rename in essentially 2.347 -the same way as a copy. Therefore, knowing what Mercurial does when 2.348 -you copy a file tells you what to expect when you rename a file. 2.349 -</para> 2.350 - 2.351 -<para>When you use the <command role="hg-cmd">hg rename</command> command, Mercurial makes a copy of 2.352 -each source file, then deletes it and marks the file as removed. 2.353 -<!-- &interaction.daily.rename.rename; --> 2.354 -The <command role="hg-cmd">hg status</command> command shows the newly copied file as added, and 2.355 -the copied-from file as removed. 2.356 -<!-- &interaction.daily.rename.status; --> 2.357 -As with the results of a <command role="hg-cmd">hg copy</command>, we must use the 2.358 -<option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command> to see that the added file 2.359 -is really being tracked by Mercurial as a copy of the original, now 2.360 -removed, file. 2.361 -<!-- &interaction.daily.rename.status-copy; --> 2.362 -</para> 2.363 - 2.364 -<para>As with <command role="hg-cmd">hg remove</command> and <command role="hg-cmd">hg copy</command>, you can tell Mercurial about 2.365 -a rename after the fact using the <option role="hg-opt-rename">--after</option> option. In 2.366 -most other respects, the behaviour of the <command role="hg-cmd">hg rename</command> command, and 2.367 -the options it accepts, are similar to the <command role="hg-cmd">hg copy</command> command. 2.368 -</para> 2.369 - 2.370 -<sect2> 2.371 -<title>Renaming files and merging changes</title> 2.372 - 2.373 -<para>Since Mercurial's rename is implemented as copy-and-remove, the same 2.374 -propagation of changes happens when you merge after a rename as after 2.375 -a copy. 2.376 -</para> 2.377 - 2.378 -<para>If I modify a file, and you rename it to a new name, and then we merge 2.379 -our respective changes, my modifications to the file under its 2.380 -original name will be propagated into the file under its new name. 2.381 -(This is something you might expect to <quote>simply work,</quote> but not all 2.382 -revision control systems actually do this.) 2.383 -</para> 2.384 - 2.385 -<para>Whereas having changes follow a copy is a feature where you can 2.386 -perhaps nod and say <quote>yes, that might be useful,</quote> it should be clear 2.387 -that having them follow a rename is definitely important. Without 2.388 -this facility, it would simply be too easy for changes to become 2.389 -orphaned when files are renamed. 2.390 -</para> 2.391 - 2.392 -</sect2> 2.393 -<sect2> 2.394 -<title>Divergent renames and merging</title> 2.395 - 2.396 -<para>The case of diverging names occurs when two developers start with a 2.397 -file&emdash;let's call it <filename>foo</filename>&emdash;in their respective 2.398 -repositories. 2.399 -</para> 2.400 - 2.401 -<para><!-- &interaction.rename.divergent.clone; --> 2.402 -Anne renames the file to <filename>bar</filename>. 2.403 -<!-- &interaction.rename.divergent.rename.anne; --> 2.404 -Meanwhile, Bob renames it to <filename>quux</filename>. 2.405 -<!-- &interaction.rename.divergent.rename.bob; --> 2.406 -</para> 2.407 - 2.408 -<para>I like to think of this as a conflict because each developer has 2.409 -expressed different intentions about what the file ought to be named. 2.410 -</para> 2.411 - 2.412 -<para>What do you think should happen when they merge their work? 2.413 -Mercurial's actual behaviour is that it always preserves <emphasis>both</emphasis> 2.414 -names when it merges changesets that contain divergent renames. 2.415 -<!-- &interaction.rename.divergent.merge; --> 2.416 -</para> 2.417 - 2.418 -<para>Notice that Mercurial does warn about the divergent renames, but it 2.419 -leaves it up to you to do something about the divergence after the merge. 2.420 -</para> 2.421 - 2.422 -</sect2> 2.423 -<sect2> 2.424 -<title>Convergent renames and merging</title> 2.425 - 2.426 -<para>Another kind of rename conflict occurs when two people choose to 2.427 -rename different <emphasis>source</emphasis> files to the same <emphasis>destination</emphasis>. 2.428 -In this case, Mercurial runs its normal merge machinery, and lets you 2.429 -guide it to a suitable resolution. 2.430 -</para> 2.431 - 2.432 -</sect2> 2.433 -<sect2> 2.434 -<title>Other name-related corner cases</title> 2.435 - 2.436 -<para>Mercurial has a longstanding bug in which it fails to handle a merge 2.437 -where one side has a file with a given name, while another has a 2.438 -directory with the same name. This is documented as <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue 29</ulink>. 2.439 -<!-- &interaction.issue29.go; --> 2.440 -</para> 2.441 - 2.442 -</sect2> 2.443 -</sect1> 2.444 -<sect1> 2.445 -<title>Recovering from mistakes</title> 2.446 - 2.447 -<para>Mercurial has some useful commands that will help you to recover from 2.448 -some common mistakes. 2.449 -</para> 2.450 - 2.451 -<para>The <command role="hg-cmd">hg revert</command> command lets you undo changes that you have made to 2.452 -your working directory. For example, if you <command role="hg-cmd">hg add</command> a file by 2.453 -accident, just run <command role="hg-cmd">hg revert</command> with the name of the file you added, 2.454 -and while the file won't be touched in any way, it won't be tracked 2.455 -for adding by Mercurial any longer, either. You can also use 2.456 -<command role="hg-cmd">hg revert</command> to get rid of erroneous changes to a file. 2.457 -</para> 2.458 - 2.459 -<para>It's useful to remember that the <command role="hg-cmd">hg revert</command> command is useful for 2.460 -changes that you have not yet committed. Once you've committed a 2.461 -change, if you decide it was a mistake, you can still do something 2.462 -about it, though your options may be more limited. 2.463 -</para> 2.464 - 2.465 -<para>For more information about the <command role="hg-cmd">hg revert</command> command, and details 2.466 -about how to deal with changes you have already committed, see 2.467 -chapter <xref linkend="chap:undo"/>. 2.468 -</para> 2.469 - 2.470 -</sect1> 2.471 +<chapter id="chap:daily"> 2.472 + <?dbhtml filename="mercurial-in-daily-use.html"?> 2.473 + <title>Mercurial in daily use</title> 2.474 + 2.475 + <sect1> 2.476 + <title>Telling Mercurial which files to track</title> 2.477 + 2.478 + <para id="x_1a3">Mercurial does not work with files in your repository unless 2.479 + you tell it to manage them. The <command role="hg-cmd">hg 2.480 + status</command> command will tell you which files Mercurial 2.481 + doesn't know about; it uses a 2.482 + <quote><literal>?</literal></quote> to display such 2.483 + files.</para> 2.484 + 2.485 + <para id="x_1a4">To tell Mercurial to track a file, use the <command 2.486 + role="hg-cmd">hg add</command> command. Once you have added a 2.487 + file, the entry in the output of <command role="hg-cmd">hg 2.488 + status</command> for that file changes from 2.489 + <quote><literal>?</literal></quote> to 2.490 + <quote><literal>A</literal></quote>.</para> 2.491 + 2.492 + &interaction.daily.files.add; 2.493 + 2.494 + <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>, 2.495 + the files that you added before the commit will no longer be 2.496 + listed in the output of <command role="hg-cmd">hg 2.497 + status</command>. The reason for this is that by default, <command 2.498 + role="hg-cmd">hg status</command> only tells you about 2.499 + <quote>interesting</quote> files&emdash;those that you have (for 2.500 + example) modified, removed, or renamed. If you have a repository 2.501 + that contains thousands of files, you will rarely want to know 2.502 + about files that Mercurial is tracking, but that have not 2.503 + changed. (You can still get this information; we'll return to 2.504 + this later.)</para> 2.505 + 2.506 + <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it 2.507 + immediately. Instead, it will take a snapshot of the file's 2.508 + state the next time you perform a commit. It will then continue 2.509 + to track the changes you make to the file every time you commit, 2.510 + until you remove the file.</para> 2.511 + 2.512 + <sect2> 2.513 + <title>Explicit versus implicit file naming</title> 2.514 + 2.515 + <para id="x_1a7">A useful behavior that Mercurial has is that if you pass 2.516 + the name of a directory to a command, every Mercurial command 2.517 + will treat this as <quote>I want to operate on every file in 2.518 + this directory and its subdirectories</quote>.</para> 2.519 + 2.520 + &interaction.daily.files.add-dir; 2.521 + 2.522 + <para id="x_1a8">Notice in this example that Mercurial printed 2.523 + the names of the files it added, whereas it didn't do so when 2.524 + we added the file named <filename>myfile.txt</filename> in the 2.525 + earlier example.</para> 2.526 + 2.527 + <para id="x_1a9">What's going on is that in the former case, we explicitly 2.528 + named the file to add on the command line. The assumption 2.529 + that Mercurial makes in such cases is that we know what we 2.530 + are doing, and it doesn't print any output.</para> 2.531 + 2.532 + <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of 2.533 + files by giving the name of a directory, Mercurial takes the 2.534 + extra step of printing the name of each file that it does 2.535 + something with. This makes it more clear what is happening, 2.536 + and reduces the likelihood of a silent and nasty surprise. 2.537 + This behavior is common to most Mercurial commands.</para> 2.538 + </sect2> 2.539 + 2.540 + <sect2> 2.541 + <title>Mercurial tracks files, not directories</title> 2.542 + 2.543 + <para id="x_1ab">Mercurial does not track directory information. Instead, 2.544 + it tracks the path to a file. Before creating a file, it 2.545 + first creates any missing directory components of the path. 2.546 + After it deletes a file, it then deletes any empty directories 2.547 + that were in the deleted file's path. This sounds like a 2.548 + trivial distinction, but it has one minor practical 2.549 + consequence: it is not possible to represent a completely 2.550 + empty directory in Mercurial.</para> 2.551 + 2.552 + <para id="x_1ac">Empty directories are rarely useful, and there are 2.553 + unintrusive workarounds that you can use to achieve an 2.554 + appropriate effect. The developers of Mercurial thus felt 2.555 + that the complexity that would be required to manage empty 2.556 + directories was not worth the limited benefit this feature 2.557 + would bring.</para> 2.558 + 2.559 + <para id="x_1ad">If you need an empty directory in your repository, there 2.560 + are a few ways to achieve this. One is to create a directory, 2.561 + then <command role="hg-cmd">hg add</command> a 2.562 + <quote>hidden</quote> file to that directory. On Unix-like 2.563 + systems, any file name that begins with a period 2.564 + (<quote><literal>.</literal></quote>) is treated as hidden by 2.565 + most commands and GUI tools. This approach is illustrated 2.566 + below.</para> 2.567 + 2.568 +&interaction.daily.files.hidden; 2.569 + 2.570 + <para id="x_1ae">Another way to tackle a need for an empty directory is to 2.571 + simply create one in your automated build scripts before they 2.572 + will need it.</para> 2.573 + </sect2> 2.574 + </sect1> 2.575 + 2.576 + <sect1> 2.577 + <title>How to stop tracking a file</title> 2.578 + 2.579 + <para id="x_1af">Once you decide that a file no longer belongs in 2.580 + your repository, use the <command role="hg-cmd">hg 2.581 + remove</command> command. This deletes the file, and tells 2.582 + Mercurial to stop tracking it (which will occur at the next 2.583 + commit). A removed file is represented in the output of 2.584 + <command role="hg-cmd">hg status</command> with a 2.585 + <quote><literal>R</literal></quote>.</para> 2.586 + 2.587 + &interaction.daily.files.remove; 2.588 + 2.589 + <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file, 2.590 + Mercurial will no longer track changes to that file, even if you 2.591 + recreate a file with the same name in your working directory. 2.592 + If you do recreate a file with the same name and want Mercurial 2.593 + to track the new file, simply <command role="hg-cmd">hg 2.594 + add</command> it. Mercurial will know that the newly added 2.595 + file is not related to the old file of the same name.</para> 2.596 + 2.597 + <sect2> 2.598 + <title>Removing a file does not affect its history</title> 2.599 + 2.600 + <para id="x_1b1">It is important to understand that removing a file has 2.601 + only two effects.</para> 2.602 + <itemizedlist> 2.603 + <listitem><para id="x_1b2">It removes the current version of the file 2.604 + from the working directory.</para> 2.605 + </listitem> 2.606 + <listitem><para id="x_1b3">It stops Mercurial from tracking changes to 2.607 + the file, from the time of the next commit.</para> 2.608 + </listitem></itemizedlist> 2.609 + <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way 2.610 + alter the <emphasis>history</emphasis> of the file.</para> 2.611 + 2.612 + <para id="x_1b5">If you update the working directory to a 2.613 + changeset that was committed when it was still tracking a file 2.614 + that you later removed, the file will reappear in the working 2.615 + directory, with the contents it had when you committed that 2.616 + changeset. If you then update the working directory to a 2.617 + later changeset, in which the file had been removed, Mercurial 2.618 + will once again remove the file from the working 2.619 + directory.</para> 2.620 + </sect2> 2.621 + 2.622 + <sect2> 2.623 + <title>Missing files</title> 2.624 + 2.625 + <para id="x_1b6">Mercurial considers a file that you have deleted, but not 2.626 + used <command role="hg-cmd">hg remove</command> to delete, to 2.627 + be <emphasis>missing</emphasis>. A missing file is 2.628 + represented with <quote><literal>!</literal></quote> in the 2.629 + output of <command role="hg-cmd">hg status</command>. 2.630 + Mercurial commands will not generally do anything with missing 2.631 + files.</para> 2.632 + 2.633 + &interaction.daily.files.missing; 2.634 + 2.635 + <para id="x_1b7">If your repository contains a file that <command 2.636 + role="hg-cmd">hg status</command> reports as missing, and 2.637 + you want the file to stay gone, you can run <command 2.638 + role="hg-cmd">hg remove <option 2.639 + role="hg-opt-remove">--after</option></command> at any 2.640 + time later on, to tell Mercurial that you really did mean to 2.641 + remove the file.</para> 2.642 + 2.643 + &interaction.daily.files.remove-after; 2.644 + 2.645 + <para id="x_1b8">On the other hand, if you deleted the missing file by 2.646 + accident, give <command role="hg-cmd">hg revert</command> the 2.647 + name of the file to recover. It will reappear, in unmodified 2.648 + form.</para> 2.649 + 2.650 + &interaction.daily.files.recover-missing; 2.651 + </sect2> 2.652 + 2.653 + <sect2> 2.654 + <title>Aside: why tell Mercurial explicitly to remove a 2.655 + file?</title> 2.656 + 2.657 + <para id="x_1b9">You might wonder why Mercurial requires you to explicitly 2.658 + tell it that you are deleting a file. Early during the 2.659 + development of Mercurial, it let you delete a file however you 2.660 + pleased; Mercurial would notice the absence of the file 2.661 + automatically when you next ran a <command role="hg-cmd">hg 2.662 + commit</command>, and stop tracking the file. In practice, 2.663 + this made it too easy to accidentally remove a file without 2.664 + noticing.</para> 2.665 + </sect2> 2.666 + 2.667 + <sect2> 2.668 + <title>Useful shorthand&emdash;adding and removing files in one 2.669 + step</title> 2.670 + 2.671 + <para id="x_1ba">Mercurial offers a combination command, <command 2.672 + role="hg-cmd">hg addremove</command>, that adds untracked 2.673 + files and marks missing files as removed.</para> 2.674 + 2.675 + &interaction.daily.files.addremove; 2.676 + 2.677 + <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command 2.678 + also provides a <option role="hg-opt-commit">-A</option> 2.679 + option that performs this same add-and-remove, immediately 2.680 + followed by a commit.</para> 2.681 + 2.682 + &interaction.daily.files.commit-addremove; 2.683 + </sect2> 2.684 + </sect1> 2.685 + 2.686 + <sect1 id="chap:daily.copy"> 2.687 + <title>Copying files</title> 2.688 + 2.689 + <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg 2.690 + copy</command> command that lets you make a new copy of a 2.691 + file. When you copy a file using this command, Mercurial makes 2.692 + a record of the fact that the new file is a copy of the original 2.693 + file. It treats these copied files specially when you merge 2.694 + your work with someone else's.</para> 2.695 + 2.696 + <sect2> 2.697 + <title>The results of copying during a merge</title> 2.698 + 2.699 + <para id="x_1bd">What happens during a merge is that changes 2.700 + <quote>follow</quote> a copy. To best illustrate what this 2.701 + means, let's create an example. We'll start with the usual 2.702 + tiny repository that contains a single file.</para> 2.703 + 2.704 + &interaction.daily.copy.init; 2.705 + 2.706 + <para id="x_1be">We need to do some work in 2.707 + parallel, so that we'll have something to merge. So let's 2.708 + clone our repository.</para> 2.709 + 2.710 + &interaction.daily.copy.clone; 2.711 + 2.712 + <para id="x_1bf">Back in our initial repository, let's use the <command 2.713 + role="hg-cmd">hg copy</command> command to make a copy of 2.714 + the first file we created.</para> 2.715 + 2.716 + &interaction.daily.copy.copy; 2.717 + 2.718 + <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg 2.719 + status</command> command afterwards, the copied file looks 2.720 + just like a normal added file.</para> 2.721 + 2.722 + &interaction.daily.copy.status; 2.723 + 2.724 + <para id="x_1c1">But if we pass the <option 2.725 + role="hg-opt-status">-C</option> option to <command 2.726 + role="hg-cmd">hg status</command>, it prints another line of 2.727 + output: this is the file that our newly-added file was copied 2.728 + <emphasis>from</emphasis>.</para> 2.729 + 2.730 + &interaction.daily.copy.status-copy; 2.731 + 2.732 + <para id="x_1c2">Now, back in the repository we cloned, let's make a change 2.733 + in parallel. We'll add a line of content to the original file 2.734 + that we created.</para> 2.735 + 2.736 + &interaction.daily.copy.other; 2.737 + 2.738 + <para id="x_1c3">Now we have a modified <filename>file</filename> in this 2.739 + repository. When we pull the changes from the first 2.740 + repository, and merge the two heads, Mercurial will propagate 2.741 + the changes that we made locally to <filename>file</filename> 2.742 + into its copy, <filename>new-file</filename>.</para> 2.743 + 2.744 + &interaction.daily.copy.merge; 2.745 + </sect2> 2.746 + 2.747 + <sect2 id="sec:daily:why-copy"> 2.748 + <title>Why should changes follow copies?</title> 2.749 + 2.750 + <para id="x_1c4">This behavior&emdash;of changes to a file 2.751 + propagating out to copies of the file&emdash;might seem 2.752 + esoteric, but in most cases it's highly desirable.</para> 2.753 + 2.754 + <para id="x_1c5">First of all, remember that this propagation 2.755 + <emphasis>only</emphasis> happens when you merge. So if you 2.756 + <command role="hg-cmd">hg copy</command> a file, and 2.757 + subsequently modify the original file during the normal course 2.758 + of your work, nothing will happen.</para> 2.759 + 2.760 + <para id="x_1c6">The second thing to know is that modifications will only 2.761 + propagate across a copy as long as the changeset that you're 2.762 + merging changes from <emphasis>hasn't yet seen</emphasis> 2.763 + the copy.</para> 2.764 + 2.765 + <para id="x_1c7">The reason that Mercurial does this is as follows. Let's 2.766 + say I make an important bug fix in a source file, and commit 2.767 + my changes. Meanwhile, you've decided to <command 2.768 + role="hg-cmd">hg copy</command> the file in your repository, 2.769 + without knowing about the bug or having seen the fix, and you 2.770 + have started hacking on your copy of the file.</para> 2.771 + 2.772 + <para id="x_1c8">If you pulled and merged my changes, and Mercurial 2.773 + <emphasis>didn't</emphasis> propagate changes across copies, 2.774 + your new source file would now contain the bug, and unless you 2.775 + knew to propagate the bug fix by hand, the bug would 2.776 + <emphasis>remain</emphasis> in your copy of the file.</para> 2.777 + 2.778 + <para id="x_1c9">By automatically propagating the change that fixed the bug 2.779 + from the original file to the copy, Mercurial prevents this 2.780 + class of problem. To my knowledge, Mercurial is the 2.781 + <emphasis>only</emphasis> revision control system that 2.782 + propagates changes across copies like this.</para> 2.783 + 2.784 + <para id="x_1ca">Once your change history has a record that the copy and 2.785 + subsequent merge occurred, there's usually no further need to 2.786 + propagate changes from the original file to the copied file, 2.787 + and that's why Mercurial only propagates changes across copies 2.788 + at the first merge, and not afterwards.</para> 2.789 + </sect2> 2.790 + 2.791 + <sect2> 2.792 + <title>How to make changes <emphasis>not</emphasis> follow a 2.793 + copy</title> 2.794 + 2.795 + <para id="x_1cb">If, for some reason, you decide that this business of 2.796 + automatically propagating changes across copies is not for 2.797 + you, simply use your system's normal file copy command (on 2.798 + Unix-like systems, that's <command>cp</command>) to make a 2.799 + copy of a file, then <command role="hg-cmd">hg add</command> 2.800 + the new copy by hand. Before you do so, though, please do 2.801 + reread <xref linkend="sec:daily:why-copy"/>, and make 2.802 + an informed 2.803 + decision that this behavior is not appropriate to your 2.804 + specific case.</para> 2.805 + 2.806 + </sect2> 2.807 + <sect2> 2.808 + <title>Behavior of the <command role="hg-cmd">hg copy</command> 2.809 + command</title> 2.810 + 2.811 + <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command> 2.812 + command, Mercurial makes a copy of each source file as it 2.813 + currently stands in the working directory. This means that if 2.814 + you make some modifications to a file, then <command 2.815 + role="hg-cmd">hg copy</command> it without first having 2.816 + committed those changes, the new copy will also contain the 2.817 + modifications you have made up until that point. (I find this 2.818 + behavior a little counterintuitive, which is why I mention it 2.819 + here.)</para> 2.820 + 2.821 + <para id="x_1cd">The <command role="hg-cmd">hg copy</command> 2.822 + command acts similarly to the Unix <command>cp</command> 2.823 + command (you can use the <command role="hg-cmd">hg 2.824 + cp</command> alias if you prefer). We must supply two or 2.825 + more arguments, of which the last is treated as the 2.826 + <emphasis>destination</emphasis>, and all others are 2.827 + <emphasis>sources</emphasis>.</para> 2.828 + 2.829 + <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a 2.830 + single file as the source, and the destination does not exist, 2.831 + it creates a new file with that name.</para> 2.832 + 2.833 + &interaction.daily.copy.simple; 2.834 + 2.835 + <para id="x_1ce">If the destination is a directory, Mercurial copies its 2.836 + sources into that directory.</para> 2.837 + 2.838 + &interaction.daily.copy.dir-dest; 2.839 + 2.840 + <para id="x_1cf">Copying a directory is 2.841 + recursive, and preserves the directory structure of the 2.842 + source.</para> 2.843 + 2.844 + &interaction.daily.copy.dir-src; 2.845 + 2.846 + <para id="x_1d0">If the source and destination are both directories, the 2.847 + source tree is recreated in the destination directory.</para> 2.848 + 2.849 + &interaction.daily.copy.dir-src-dest; 2.850 + 2.851 + <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command> 2.852 + command, if you copy a file manually and then want Mercurial 2.853 + to know that you've copied the file, simply use the <option 2.854 + role="hg-opt-copy">--after</option> option to <command 2.855 + role="hg-cmd">hg copy</command>.</para> 2.856 + 2.857 + &interaction.daily.copy.after; 2.858 + </sect2> 2.859 + </sect1> 2.860 + 2.861 + <sect1> 2.862 + <title>Renaming files</title> 2.863 + 2.864 + <para id="x_1d2">It's rather more common to need to rename a file than to 2.865 + make a copy of it. The reason I discussed the <command 2.866 + role="hg-cmd">hg copy</command> command before talking about 2.867 + renaming files is that Mercurial treats a rename in essentially 2.868 + the same way as a copy. Therefore, knowing what Mercurial does 2.869 + when you copy a file tells you what to expect when you rename a 2.870 + file.</para> 2.871 + 2.872 + <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command> 2.873 + command, Mercurial makes a copy of each source file, then 2.874 + deletes it and marks the file as removed.</para> 2.875 + 2.876 + &interaction.daily.rename.rename; 2.877 + 2.878 + <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows 2.879 + the newly copied file as added, and the copied-from file as 2.880 + removed.</para> 2.881 + 2.882 + &interaction.daily.rename.status; 2.883 + 2.884 + <para id="x_1d5">As with the results of a <command role="hg-cmd">hg 2.885 + copy</command>, we must use the <option 2.886 + role="hg-opt-status">-C</option> option to <command 2.887 + role="hg-cmd">hg status</command> to see that the added file 2.888 + is really being tracked by Mercurial as a copy of the original, 2.889 + now removed, file.</para> 2.890 + 2.891 + &interaction.daily.rename.status-copy; 2.892 + 2.893 + <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and 2.894 + <command role="hg-cmd">hg copy</command>, you can tell Mercurial 2.895 + about a rename after the fact using the <option 2.896 + role="hg-opt-rename">--after</option> option. In most other 2.897 + respects, the behavior of the <command role="hg-cmd">hg 2.898 + rename</command> command, and the options it accepts, are 2.899 + similar to the <command role="hg-cmd">hg copy</command> 2.900 + command.</para> 2.901 + 2.902 + <para id="x_686">If you're familiar with the Unix command line, you'll be 2.903 + glad to know that <command role="hg-cmd">hg rename</command> 2.904 + command can be invoked as <command role="hg-cmd">hg 2.905 + mv</command>.</para> 2.906 + 2.907 + <sect2> 2.908 + <title>Renaming files and merging changes</title> 2.909 + 2.910 + <para id="x_1d7">Since Mercurial's rename is implemented as 2.911 + copy-and-remove, the same propagation of changes happens when 2.912 + you merge after a rename as after a copy.</para> 2.913 + 2.914 + <para id="x_1d8">If I modify a file, and you rename it to a new name, and 2.915 + then we merge our respective changes, my modifications to the 2.916 + file under its original name will be propagated into the file 2.917 + under its new name. (This is something you might expect to 2.918 + <quote>simply work,</quote> but not all revision control 2.919 + systems actually do this.)</para> 2.920 + 2.921 + <para id="x_1d9">Whereas having changes follow a copy is a feature where 2.922 + you can perhaps nod and say <quote>yes, that might be 2.923 + useful,</quote> it should be clear that having them follow a 2.924 + rename is definitely important. Without this facility, it 2.925 + would simply be too easy for changes to become orphaned when 2.926 + files are renamed.</para> 2.927 + </sect2> 2.928 + 2.929 + <sect2> 2.930 + <title>Divergent renames and merging</title> 2.931 + 2.932 + <para id="x_1da">The case of diverging names occurs when two developers 2.933 + start with a file&emdash;let's call it 2.934 + <filename>foo</filename>&emdash;in their respective 2.935 + repositories.</para> 2.936 + 2.937 + &interaction.rename.divergent.clone; 2.938 + 2.939 + <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para> 2.940 + 2.941 + &interaction.rename.divergent.rename.anne; 2.942 + 2.943 + <para id="x_1dc">Meanwhile, Bob renames it to 2.944 + <filename>quux</filename>. (Remember that <command 2.945 + role="hg-cmd">hg mv</command> is an alias for <command 2.946 + role="hg-cmd">hg rename</command>.)</para> 2.947 + 2.948 + &interaction.rename.divergent.rename.bob; 2.949 + 2.950 + <para id="x_1dd">I like to think of this as a conflict because each 2.951 + developer has expressed different intentions about what the 2.952 + file ought to be named.</para> 2.953 + 2.954 + <para id="x_1de">What do you think should happen when they merge their 2.955 + work? Mercurial's actual behavior is that it always preserves 2.956 + <emphasis>both</emphasis> names when it merges changesets that 2.957 + contain divergent renames.</para> 2.958 + 2.959 + &interaction.rename.divergent.merge; 2.960 + 2.961 + <para id="x_1df">Notice that while Mercurial warns about the divergent 2.962 + renames, it leaves it up to you to do something about the 2.963 + divergence after the merge.</para> 2.964 + </sect2> 2.965 + 2.966 + <sect2> 2.967 + <title>Convergent renames and merging</title> 2.968 + 2.969 + <para id="x_1e0">Another kind of rename conflict occurs when two people 2.970 + choose to rename different <emphasis>source</emphasis> files 2.971 + to the same <emphasis>destination</emphasis>. In this case, 2.972 + Mercurial runs its normal merge machinery, and lets you guide 2.973 + it to a suitable resolution.</para> 2.974 + </sect2> 2.975 + 2.976 + <sect2> 2.977 + <title>Other name-related corner cases</title> 2.978 + 2.979 + <para id="x_1e1">Mercurial has a longstanding bug in which it fails to 2.980 + handle a merge where one side has a file with a given name, 2.981 + while another has a directory with the same name. This is 2.982 + documented as <ulink role="hg-bug" 2.983 + url="http://www.selenic.com/mercurial/bts/issue29">issue 2.984 + 29</ulink>.</para> 2.985 + 2.986 + &interaction.issue29.go; 2.987 + 2.988 + </sect2> 2.989 + </sect1> 2.990 + 2.991 + <sect1> 2.992 + <title>Recovering from mistakes</title> 2.993 + 2.994 + <para id="x_1e2">Mercurial has some useful commands that will help you to 2.995 + recover from some common mistakes.</para> 2.996 + 2.997 + <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets 2.998 + you undo changes that you have made to your working directory. 2.999 + For example, if you <command role="hg-cmd">hg add</command> a 2.1000 + file by accident, just run <command role="hg-cmd">hg 2.1001 + revert</command> with the name of the file you added, and 2.1002 + while the file won't be touched in any way, it won't be tracked 2.1003 + for adding by Mercurial any longer, either. You can also use 2.1004 + <command role="hg-cmd">hg revert</command> to get rid of 2.1005 + erroneous changes to a file.</para> 2.1006 + 2.1007 + <para id="x_1e4">It is helpful to remember that the <command 2.1008 + role="hg-cmd">hg revert</command> command is useful for 2.1009 + changes that you have not yet committed. Once you've committed 2.1010 + a change, if you decide it was a mistake, you can still do 2.1011 + something about it, though your options may be more 2.1012 + limited.</para> 2.1013 + 2.1014 + <para id="x_1e5">For more information about the <command 2.1015 + role="hg-cmd">hg revert</command> command, and details about 2.1016 + how to deal with changes you have already committed, see <xref 2.1017 + linkend="chap:undo"/>.</para> 2.1018 + </sect1> 2.1019 + 2.1020 + <sect1> 2.1021 + <title>Dealing with tricky merges</title> 2.1022 + 2.1023 + <para id="x_687">In a complicated or large project, it's not unusual for a 2.1024 + merge of two changesets to result in some headaches. Suppose 2.1025 + there's a big source file that's been extensively edited by each 2.1026 + side of a merge: this is almost inevitably going to result in 2.1027 + conflicts, some of which can take a few tries to sort 2.1028 + out.</para> 2.1029 + 2.1030 + <para id="x_688">Let's develop a simple case of this and see how to deal with 2.1031 + it. We'll start off with a repository containing one file, and 2.1032 + clone it twice.</para> 2.1033 + 2.1034 + &interaction.ch04-resolve.init; 2.1035 + 2.1036 + <para id="x_689">In one clone, we'll modify the file in one way.</para> 2.1037 + 2.1038 + &interaction.ch04-resolve.left; 2.1039 + 2.1040 + <para id="x_68a">In another, we'll modify the file differently.</para> 2.1041 + 2.1042 + &interaction.ch04-resolve.right; 2.1043 + 2.1044 + <para id="x_68b">Next, we'll pull each set of changes into our original 2.1045 + repo.</para> 2.1046 + 2.1047 + &interaction.ch04-resolve.pull; 2.1048 + 2.1049 + <para id="x_68c">We expect our repository to now contain two heads.</para> 2.1050 + 2.1051 + &interaction.ch04-resolve.heads; 2.1052 + 2.1053 + <para id="x_68d">Normally, if we run <command role="hg-cmd">hg 2.1054 + merge</command> at this point, it will drop us into a GUI that 2.1055 + will let us manually resolve the conflicting edits to 2.1056 + <filename>myfile.txt</filename>. However, to simplify things 2.1057 + for presentation here, we'd like the merge to fail immediately 2.1058 + instead. Here's one way we can do so.</para> 2.1059 + 2.1060 + &interaction.ch04-resolve.export; 2.1061 + 2.1062 + <para id="x_68e">We've told Mercurial's merge machinery to run the command 2.1063 + <command>false</command> (which, as we desire, fails 2.1064 + immediately) if it detects a merge that it can't sort out 2.1065 + automatically.</para> 2.1066 + 2.1067 + <para id="x_68f">If we now fire up <command role="hg-cmd">hg 2.1068 + merge</command>, it should grind to a halt and report a 2.1069 + failure.</para> 2.1070 + 2.1071 + &interaction.ch04-resolve.merge; 2.1072 + 2.1073 + <para id="x_690">Even if we don't notice that the merge failed, Mercurial 2.1074 + will prevent us from accidentally committing the result of a 2.1075 + failed merge.</para> 2.1076 + 2.1077 + &interaction.ch04-resolve.cifail; 2.1078 + 2.1079 + <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in 2.1080 + this case, it suggests that we use the unfamiliar <command 2.1081 + role="hg-cmd">hg resolve</command> command. As usual, 2.1082 + <command role="hg-cmd">hg help resolve</command> will print a 2.1083 + helpful synopsis.</para> 2.1084 + 2.1085 + <sect2> 2.1086 + <title>File resolution states</title> 2.1087 + 2.1088 + <para id="x_692">When a merge occurs, most files will usually remain 2.1089 + unmodified. For each file where Mercurial has to do 2.1090 + something, it tracks the state of the file.</para> 2.1091 + 2.1092 + <itemizedlist> 2.1093 + <listitem> 2.1094 + <para id="x_693">A <emphasis>resolved</emphasis> file has been 2.1095 + successfully merged, either automatically by Mercurial or 2.1096 + manually with human intervention.</para> 2.1097 + </listitem> 2.1098 + <listitem> 2.1099 + <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged 2.1100 + successfully, and needs more attention.</para> 2.1101 + </listitem> 2.1102 + </itemizedlist> 2.1103 + 2.1104 + <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the 2.1105 + unresolved state after a merge, it considers the merge to have 2.1106 + failed. Fortunately, we do not need to restart the entire 2.1107 + merge from scratch.</para> 2.1108 + 2.1109 + <para id="x_696">The <option role="hg-opt-resolve">--list</option> or 2.1110 + <option role="hg-opt-resolve">-l</option> option to <command 2.1111 + role="hg-cmd">hg resolve</command> prints out the state of 2.1112 + each merged file.</para> 2.1113 + 2.1114 + &interaction.ch04-resolve.list; 2.1115 + 2.1116 + <para id="x_697">In the output from <command role="hg-cmd">hg 2.1117 + resolve</command>, a resolved file is marked with 2.1118 + <literal>R</literal>, while an unresolved file is marked with 2.1119 + <literal>U</literal>. If any files are listed with 2.1120 + <literal>U</literal>, we know that an attempt to commit the 2.1121 + results of the merge will fail.</para> 2.1122 + </sect2> 2.1123 + 2.1124 + <sect2> 2.1125 + <title>Resolving a file merge</title> 2.1126 + 2.1127 + <para id="x_698">We have several options to move a file from the unresolved 2.1128 + into the resolved state. By far the most common is to rerun 2.1129 + <command role="hg-cmd">hg resolve</command>. If we pass the 2.1130 + names of individual files or directories, it will retry the 2.1131 + merges of any unresolved files present in those locations. We 2.1132 + can also pass the <option role="hg-opt-resolve">--all</option> 2.1133 + or <option role="hg-opt-resolve">-a</option> option, which 2.1134 + will retry the merges of <emphasis>all</emphasis> unresolved 2.1135 + files.</para> 2.1136 + 2.1137 + <para id="x_699">Mercurial also lets us modify the resolution state of a 2.1138 + file directly. We can manually mark a file as resolved using 2.1139 + the <option role="hg-opt-resolve">--mark</option> option, or 2.1140 + as unresolved using the <option 2.1141 + role="hg-opt-resolve">--unmark</option> option. This allows 2.1142 + us to clean up a particularly messy merge by hand, and to keep 2.1143 + track of our progress with each file as we go.</para> 2.1144 + </sect2> 2.1145 + </sect1> 2.1146 + 2.1147 + <sect1> 2.1148 + <title>More useful diffs</title> 2.1149 + 2.1150 + <para id="x_6c7">The default output of the <command role="hg-cmd">hg 2.1151 + diff</command> command is backwards compatible with the 2.1152 + regular <command>diff</command> command, but this has some 2.1153 + drawbacks.</para> 2.1154 + 2.1155 + <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg 2.1156 + rename</command> to rename a file.</para> 2.1157 + 2.1158 + &interaction.ch04-diff.rename.basic; 2.1159 + 2.1160 + <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above 2.1161 + obscures the fact that we simply renamed a file. The <command 2.1162 + role="hg-cmd">hg diff</command> command accepts an option, 2.1163 + <option>--git</option> or <option>-g</option>, to use a newer 2.1164 + diff format that displays such information in a more readable 2.1165 + form.</para> 2.1166 + 2.1167 + &interaction.ch04-diff.rename.git; 2.1168 + 2.1169 + <para id="x_6ca">This option also helps with a case that can otherwise be 2.1170 + confusing: a file that appears to be modified according to 2.1171 + <command role="hg-cmd">hg status</command>, but for which 2.1172 + <command role="hg-cmd">hg diff</command> prints nothing. This 2.1173 + situation can arise if we change the file's execute 2.1174 + permissions.</para> 2.1175 + 2.1176 + &interaction.ch04-diff.chmod; 2.1177 + 2.1178 + <para id="x_6cb">The normal <command>diff</command> command pays no attention 2.1179 + to file permissions, which is why <command role="hg-cmd">hg 2.1180 + diff</command> prints nothing by default. If we supply it 2.1181 + with the <option>-g</option> option, it tells us what really 2.1182 + happened.</para> 2.1183 + 2.1184 + &interaction.ch04-diff.chmod.git; 2.1185 + </sect1> 2.1186 + 2.1187 + <sect1> 2.1188 + <title>Which files to manage, and which to avoid</title> 2.1189 + 2.1190 + <para id="x_6cc">Revision control systems are generally best at managing text 2.1191 + files that are written by humans, such as source code, where the 2.1192 + files do not change much from one revision to the next. Some 2.1193 + centralized revision control systems can also deal tolerably 2.1194 + well with binary files, such as bitmap images.</para> 2.1195 + 2.1196 + <para id="x_6cd">For instance, a game development team will typically manage 2.1197 + both its source code and all of its binary assets (e.g. geometry 2.1198 + data, textures, map layouts) in a revision control 2.1199 + system.</para> 2.1200 + 2.1201 + <para id="x_6ce">Because it is usually impossible to merge two conflicting 2.1202 + modifications to a binary file, centralized systems often 2.1203 + provide a file locking mechanism that allow a user to say 2.1204 + <quote>I am the only person who can edit this 2.1205 + file</quote>.</para> 2.1206 + 2.1207 + <para id="x_6cf">Compared to a centralized system, a distributed revision 2.1208 + control system changes some of the factors that guide decisions 2.1209 + over which files to manage and how.</para> 2.1210 + 2.1211 + <para id="x_6d0">For instance, a distributed revision control system cannot, 2.1212 + by its nature, offer a file locking facility. There is thus no 2.1213 + built-in mechanism to prevent two people from making conflicting 2.1214 + changes to a binary file. If you have a team where several 2.1215 + people may be editing binary files frequently, it may not be a 2.1216 + good idea to use Mercurial&emdash;or any other distributed 2.1217 + revision control system&emdash;to manage those files.</para> 2.1218 + 2.1219 + <para id="x_6d1">When storing modifications to a file, Mercurial usually 2.1220 + saves only the differences between the previous and current 2.1221 + versions of the file. For most text files, this is extremely 2.1222 + efficient. However, some files (particularly binary files) are 2.1223 + laid out in such a way that even a small change to a file's 2.1224 + logical content results in many or most of the bytes inside the 2.1225 + file changing. For instance, compressed files are particularly 2.1226 + susceptible to this. If the differences between each successive 2.1227 + version of a file are always large, Mercurial will not be able 2.1228 + to store the file's revision history very efficiently. This can 2.1229 + affect both local storage needs and the amount of time it takes 2.1230 + to clone a repository.</para> 2.1231 + 2.1232 + <para id="x_6d2">To get an idea of how this could affect you in practice, 2.1233 + suppose you want to use Mercurial to manage an OpenOffice 2.1234 + document. OpenOffice stores documents on disk as compressed zip 2.1235 + files. Edit even a single letter of your document in OpenOffice, 2.1236 + and almost every byte in the entire file will change when you 2.1237 + save it. Now suppose that file is 2MB in size. Because most of 2.1238 + the file changes every time you save, Mercurial will have to 2.1239 + store all 2MB of the file every time you commit, even though 2.1240 + from your perspective, perhaps only a few words are changing 2.1241 + each time. A single frequently-edited file that is not friendly 2.1242 + to Mercurial's storage assumptions can easily have an outsized 2.1243 + effect on the size of the repository.</para> 2.1244 + 2.1245 + <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice 2.1246 + document you're working on, there is no useful way to merge your 2.1247 + work. In fact, there isn't even a good way to tell what the 2.1248 + differences are between your respective changes.</para> 2.1249 + 2.1250 + <para id="x_6d4">There are thus a few clear recommendations about specific 2.1251 + kinds of files to be very careful with.</para> 2.1252 + 2.1253 + <itemizedlist> 2.1254 + <listitem> 2.1255 + <para id="x_6d5">Files that are very large and incompressible, e.g. ISO 2.1256 + CD-ROM images, will by virtue of sheer size make clones over 2.1257 + a network very slow.</para> 2.1258 + </listitem> 2.1259 + <listitem> 2.1260 + <para id="x_6d6">Files that change a lot from one revision to the next 2.1261 + may be expensive to store if you edit them frequently, and 2.1262 + conflicts due to concurrent edits may be difficult to 2.1263 + resolve.</para> 2.1264 + </listitem> 2.1265 + </itemizedlist> 2.1266 + </sect1> 2.1267 + 2.1268 + <sect1> 2.1269 + <title>Backups and mirroring</title> 2.1270 + 2.1271 + <para id="x_6d7">Since Mercurial maintains a complete copy of history in each 2.1272 + clone, everyone who uses Mercurial to collaborate on a project 2.1273 + can potentially act as a source of backups in the event of a 2.1274 + catastrophe. If a central repository becomes unavailable, you 2.1275 + can construct a replacement simply by cloning a copy of the 2.1276 + repository from one contributor, and pulling any changes they 2.1277 + may not have seen from others.</para> 2.1278 + 2.1279 + <para id="x_6d8">It is simple to use Mercurial to perform off-site backups 2.1280 + and remote mirrors. Set up a periodic job (e.g. via the 2.1281 + <command>cron</command> command) on a remote server to pull 2.1282 + changes from your master repositories every hour. This will 2.1283 + only be tricky in the unlikely case that the number of master 2.1284 + repositories you maintain changes frequently, in which case 2.1285 + you'll need to do a little scripting to refresh the list of 2.1286 + repositories to back up.</para> 2.1287 + 2.1288 + <para id="x_6d9">If you perform traditional backups of your master 2.1289 + repositories to tape or disk, and you want to back up a 2.1290 + repository named <filename>myrepo</filename>, use <command>hg 2.1291 + clone -U myrepo myrepo.bak</command> to create a 2.1292 + clone of <filename>myrepo</filename> before you start your 2.1293 + backups. The <option>-U</option> option doesn't check out a 2.1294 + working directory after the clone completes, since that would be 2.1295 + superfluous and make the backup take longer.</para> 2.1296 + 2.1297 + <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead 2.1298 + of <filename>myrepo</filename>, you will be guaranteed to have a 2.1299 + consistent snapshot of your repository that won't be pushed to 2.1300 + by an insomniac developer in mid-backup.</para> 2.1301 + </sect1> 2.1302 </chapter> 2.1303 2.1304 <!-- 2.1305 local variables: 2.1306 sgml-parent-document: ("00book.xml" "book" "chapter") 2.1307 end: 2.1308 ---> 2.1309 \ No newline at end of file 2.1310 +-->
3.1 --- a/fr/ch06-collab.xml Wed Sep 09 15:25:09 2009 +0200 3.2 +++ b/fr/ch06-collab.xml Wed Sep 09 16:07:36 2009 +0200 3.3 @@ -1,1405 +1,1565 @@ 3.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 3.5 3.6 -<chapter> 3.7 -<title>Collaborating with other people</title> 3.8 -<para>\label{cha:collab}</para> 3.9 - 3.10 -<para>As a completely decentralised tool, Mercurial doesn't impose any 3.11 -policy on how people ought to work with each other. However, if 3.12 -you're new to distributed revision control, it helps to have some 3.13 -tools and examples in mind when you're thinking about possible 3.14 -workflow models.</para> 3.15 - 3.16 -<sect1> 3.17 -<title>Mercurial's web interface</title> 3.18 - 3.19 -<para>Mercurial has a powerful web interface that provides several 3.20 -useful capabilities.</para> 3.21 - 3.22 -<para>For interactive use, the web interface lets you browse a single 3.23 -repository or a collection of repositories. You can view the history 3.24 -of a repository, examine each change (comments and diffs), and view 3.25 -the contents of each directory and file.</para> 3.26 - 3.27 -<para>Also for human consumption, the web interface provides an RSS feed of 3.28 -the changes in a repository. This lets you <quote>subscribe</quote> to a 3.29 -repository using your favourite feed reader, and be automatically 3.30 -notified of activity in that repository as soon as it happens. I find 3.31 -this capability much more convenient than the model of subscribing to 3.32 -a mailing list to which notifications are sent, as it requires no 3.33 -additional configuration on the part of whoever is serving the 3.34 -repository.</para> 3.35 - 3.36 -<para>The web interface also lets remote users clone a repository, pull 3.37 -changes from it, and (when the server is configured to permit it) push 3.38 -changes back to it. Mercurial's HTTP tunneling protocol aggressively 3.39 -compresses data, so that it works efficiently even over low-bandwidth 3.40 -network connections.</para> 3.41 - 3.42 -<para>The easiest way to get started with the web interface is to use your 3.43 -web browser to visit an existing repository, such as the master 3.44 -Mercurial repository at 3.45 -<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para> 3.46 - 3.47 -<para>If you're interested in providing a web interface to your own 3.48 -repositories, Mercurial provides two ways to do this. The first is 3.49 -using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term 3.50 -<quote>lightweight</quote> serving. See section <xref linkend="sec:collab:serve"/> below for 3.51 -details of how to use this command. If you have a long-lived 3.52 -repository that you'd like to make permanently available, Mercurial 3.53 -has built-in support for the CGI (Common Gateway Interface) standard, 3.54 -which all common web servers support. See 3.55 -section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para> 3.56 - 3.57 -</sect1> 3.58 -<sect1> 3.59 -<title>Collaboration models</title> 3.60 - 3.61 -<para>With a suitably flexible tool, making decisions about workflow is much 3.62 -more of a social engineering challenge than a technical one. 3.63 -Mercurial imposes few limitations on how you can structure the flow of 3.64 -work in a project, so it's up to you and your group to set up and live 3.65 -with a model that matches your own particular needs. 3.66 -</para> 3.67 - 3.68 -<sect2> 3.69 -<title>Factors to keep in mind</title> 3.70 - 3.71 -<para>The most important aspect of any model that you must keep in mind is 3.72 -how well it matches the needs and capabilities of the people who will 3.73 -be using it. This might seem self-evident; even so, you still can't 3.74 -afford to forget it for a moment. 3.75 -</para> 3.76 - 3.77 -<para>I once put together a workflow model that seemed to make perfect sense 3.78 -to me, but that caused a considerable amount of consternation and 3.79 -strife within my development team. In spite of my attempts to explain 3.80 -why we needed a complex set of branches, and how changes ought to flow 3.81 -between them, a few team members revolted. Even though they were 3.82 -smart people, they didn't want to pay attention to the constraints we 3.83 -were operating under, or face the consequences of those constraints in 3.84 -the details of the model that I was advocating. 3.85 -</para> 3.86 - 3.87 -<para>Don't sweep foreseeable social or technical problems under the rug. 3.88 -Whatever scheme you put into effect, you should plan for mistakes and 3.89 -problem scenarios. Consider adding automated machinery to prevent, or 3.90 -quickly recover from, trouble that you can anticipate. As an example, 3.91 -if you intend to have a branch with not-for-release changes in it, 3.92 -you'd do well to think early about the possibility that someone might 3.93 -accidentally merge those changes into a release branch. You could 3.94 -avoid this particular problem by writing a hook that prevents changes 3.95 -from being merged from an inappropriate branch. 3.96 -</para> 3.97 - 3.98 -</sect2> 3.99 -<sect2> 3.100 -<title>Informal anarchy</title> 3.101 - 3.102 -<para>I wouldn't suggest an <quote>anything goes</quote> approach as something 3.103 -sustainable, but it's a model that's easy to grasp, and it works 3.104 -perfectly well in a few unusual situations. 3.105 -</para> 3.106 - 3.107 -<para>As one example, many projects have a loose-knit group of collaborators 3.108 -who rarely physically meet each other. Some groups like to overcome 3.109 -the isolation of working at a distance by organising occasional 3.110 -<quote>sprints</quote>. In a sprint, a number of people get together in a single 3.111 -location (a company's conference room, a hotel meeting room, that kind 3.112 -of place) and spend several days more or less locked in there, hacking 3.113 -intensely on a handful of projects. 3.114 -</para> 3.115 - 3.116 -<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since 3.117 -<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure. You 3.118 -can get started with <command role="hg-cmd">hg serve</command> in moments, by reading 3.119 -section <xref linkend="sec:collab:serve"/> below. Then simply tell the person 3.120 -next to you that you're running a server, send the URL to them in an 3.121 -instant message, and you immediately have a quick-turnaround way to 3.122 -work together. They can type your URL into their web browser and 3.123 -quickly review your changes; or they can pull a bugfix from you and 3.124 -verify it; or they can clone a branch containing a new feature and try 3.125 -it out. 3.126 -</para> 3.127 - 3.128 -<para>The charm, and the problem, with doing things in an ad hoc fashion 3.129 -like this is that only people who know about your changes, and where 3.130 -they are, can see them. Such an informal approach simply doesn't 3.131 -scale beyond a handful people, because each individual needs to know 3.132 -about $n$ different repositories to pull from. 3.133 -</para> 3.134 - 3.135 -</sect2> 3.136 -<sect2> 3.137 -<title>A single central repository</title> 3.138 - 3.139 -<para>For smaller projects migrating from a centralised revision control 3.140 -tool, perhaps the easiest way to get started is to have changes flow 3.141 -through a single shared central repository. This is also the 3.142 -most common <quote>building block</quote> for more ambitious workflow schemes. 3.143 -</para> 3.144 - 3.145 -<para>Contributors start by cloning a copy of this repository. They can 3.146 -pull changes from it whenever they need to, and some (perhaps all) 3.147 -developers have permission to push a change back when they're ready 3.148 -for other people to see it. 3.149 -</para> 3.150 - 3.151 -<para>Under this model, it can still often make sense for people to pull 3.152 -changes directly from each other, without going through the central 3.153 -repository. Consider a case in which I have a tentative bug fix, but 3.154 -I am worried that if I were to publish it to the central repository, 3.155 -it might subsequently break everyone else's trees as they pull it. To 3.156 -reduce the potential for damage, I can ask you to clone my repository 3.157 -into a temporary repository of your own and test it. This lets us put 3.158 -off publishing the potentially unsafe change until it has had a little 3.159 -testing. 3.160 -</para> 3.161 - 3.162 -<para>In this kind of scenario, people usually use the <command>ssh</command> 3.163 -protocol to securely push changes to the central repository, as 3.164 -documented in section <xref linkend="sec:collab:ssh"/>. It's also usual to 3.165 -publish a read-only copy of the repository over HTTP using CGI, as in 3.166 -section <xref linkend="sec:collab:cgi"/>. Publishing over HTTP satisfies the 3.167 -needs of people who don't have push access, and those who want to use 3.168 -web browsers to browse the repository's history. 3.169 -</para> 3.170 - 3.171 -</sect2> 3.172 -<sect2> 3.173 -<title>Working with multiple branches</title> 3.174 - 3.175 -<para>Projects of any significant size naturally tend to make progress on 3.176 -several fronts simultaneously. In the case of software, it's common 3.177 -for a project to go through periodic official releases. A release 3.178 -might then go into <quote>maintenance mode</quote> for a while after its first 3.179 -publication; maintenance releases tend to contain only bug fixes, not 3.180 -new features. In parallel with these maintenance releases, one or 3.181 -more future releases may be under development. People normally use 3.182 -the word <quote>branch</quote> to refer to one of these many slightly different 3.183 -directions in which development is proceeding. 3.184 -</para> 3.185 - 3.186 -<para>Mercurial is particularly well suited to managing a number of 3.187 -simultaneous, but not identical, branches. Each <quote>development 3.188 -direction</quote> can live in its own central repository, and you can merge 3.189 -changes from one to another as the need arises. Because repositories 3.190 -are independent of each other, unstable changes in a development 3.191 -branch will never affect a stable branch unless someone explicitly 3.192 -merges those changes in. 3.193 -</para> 3.194 - 3.195 -<para>Here's an example of how this can work in practice. Let's say you 3.196 -have one <quote>main branch</quote> on a central server. 3.197 -<!-- &interaction.branching.init; --> 3.198 -People clone it, make changes locally, test them, and push them back. 3.199 -</para> 3.200 - 3.201 -<para>Once the main branch reaches a release milestone, you can use the 3.202 -<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone 3.203 -revision. 3.204 -<!-- &interaction.branching.tag; --> 3.205 -Let's say some ongoing development occurs on the main branch. 3.206 -<!-- &interaction.branching.main; --> 3.207 -Using the tag that was recorded at the milestone, people who clone 3.208 -that repository at any time in the future can use <command role="hg-cmd">hg update</command> to 3.209 -get a copy of the working directory exactly as it was when that tagged 3.210 -revision was committed. 3.211 -<!-- &interaction.branching.update; --> 3.212 -</para> 3.213 - 3.214 -<para>In addition, immediately after the main branch is tagged, someone can 3.215 -then clone the main branch on the server to a new <quote>stable</quote> branch, 3.216 -also on the server. 3.217 -<!-- &interaction.branching.clone; --> 3.218 -</para> 3.219 - 3.220 -<para>Someone who needs to make a change to the stable branch can then clone 3.221 -<emphasis>that</emphasis> repository, make their changes, commit, and push their 3.222 -changes back there. 3.223 -<!-- &interaction.branching.stable; --> 3.224 -Because Mercurial repositories are independent, and Mercurial doesn't 3.225 -move changes around automatically, the stable and main branches are 3.226 -<emphasis>isolated</emphasis> from each other. The changes that you made on the 3.227 -main branch don't <quote>leak</quote> to the stable branch, and vice versa. 3.228 -</para> 3.229 - 3.230 -<para>You'll often want all of your bugfixes on the stable branch to show up 3.231 -on the main branch, too. Rather than rewrite a bugfix on the main 3.232 -branch, you can simply pull and merge changes from the stable to the 3.233 -main branch, and Mercurial will bring those bugfixes in for you. 3.234 -<!-- &interaction.branching.merge; --> 3.235 -The main branch will still contain changes that are not on the stable 3.236 -branch, but it will also contain all of the bugfixes from the stable 3.237 -branch. The stable branch remains unaffected by these changes. 3.238 -</para> 3.239 - 3.240 -</sect2> 3.241 -<sect2> 3.242 -<title>Feature branches</title> 3.243 - 3.244 -<para>For larger projects, an effective way to manage change is to break up 3.245 -a team into smaller groups. Each group has a shared branch of its 3.246 -own, cloned from a single <quote>master</quote> branch used by the entire 3.247 -project. People working on an individual branch are typically quite 3.248 -isolated from developments on other branches. 3.249 -</para> 3.250 - 3.251 -<informalfigure> 3.252 - 3.253 -<para> <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 3.254 - <caption><para>Feature branches</para></caption> 3.255 - \label{fig:collab:feature-branches} 3.256 -</para> 3.257 -</informalfigure> 3.258 - 3.259 -<para>When a particular feature is deemed to be in suitable shape, someone 3.260 -on that feature team pulls and merges from the master branch into the 3.261 -feature branch, then pushes back up to the master branch. 3.262 -</para> 3.263 - 3.264 -</sect2> 3.265 -<sect2> 3.266 -<title>The release train</title> 3.267 - 3.268 -<para>Some projects are organised on a <quote>train</quote> basis: a release is 3.269 -scheduled to happen every few months, and whatever features are ready 3.270 -when the <quote>train</quote> is ready to leave are allowed in. 3.271 -</para> 3.272 - 3.273 -<para>This model resembles working with feature branches. The difference is 3.274 -that when a feature branch misses a train, someone on the feature team 3.275 -pulls and merges the changes that went out on that train release into 3.276 -the feature branch, and the team continues its work on top of that 3.277 -release so that their feature can make the next release. 3.278 -</para> 3.279 - 3.280 -</sect2> 3.281 -<sect2> 3.282 -<title>The Linux kernel model</title> 3.283 - 3.284 -<para>The development of the Linux kernel has a shallow hierarchical 3.285 -structure, surrounded by a cloud of apparent chaos. Because most 3.286 -Linux developers use <command>git</command>, a distributed revision control 3.287 -tool with capabilities similar to Mercurial, it's useful to describe 3.288 -the way work flows in that environment; if you like the ideas, the 3.289 -approach translates well across tools. 3.290 -</para> 3.291 - 3.292 -<para>At the center of the community sits Linus Torvalds, the creator of 3.293 -Linux. He publishes a single source repository that is considered the 3.294 -<quote>authoritative</quote> current tree by the entire developer community. 3.295 -Anyone can clone Linus's tree, but he is very choosy about whose trees 3.296 -he pulls from. 3.297 -</para> 3.298 - 3.299 -<para>Linus has a number of <quote>trusted lieutenants</quote>. As a general rule, he 3.300 -pulls whatever changes they publish, in most cases without even 3.301 -reviewing those changes. Some of those lieutenants are generally 3.302 -agreed to be <quote>maintainers</quote>, responsible for specific subsystems 3.303 -within the kernel. If a random kernel hacker wants to make a change 3.304 -to a subsystem that they want to end up in Linus's tree, they must 3.305 -find out who the subsystem's maintainer is, and ask that maintainer to 3.306 -take their change. If the maintainer reviews their changes and agrees 3.307 -to take them, they'll pass them along to Linus in due course. 3.308 -</para> 3.309 - 3.310 -<para>Individual lieutenants have their own approaches to reviewing, 3.311 -accepting, and publishing changes; and for deciding when to feed them 3.312 -to Linus. In addition, there are several well known branches that 3.313 -people use for different purposes. For example, a few people maintain 3.314 -<quote>stable</quote> repositories of older versions of the kernel, to which they 3.315 -apply critical fixes as needed. Some maintainers publish multiple 3.316 -trees: one for experimental changes; one for changes that they are 3.317 -about to feed upstream; and so on. Others just publish a single 3.318 -tree. 3.319 -</para> 3.320 - 3.321 -<para>This model has two notable features. The first is that it's <quote>pull 3.322 -only</quote>. You have to ask, convince, or beg another developer to take a 3.323 -change from you, because there are almost no trees to which more than 3.324 -one person can push, and there's no way to push changes into a tree 3.325 -that someone else controls. 3.326 -</para> 3.327 - 3.328 -<para>The second is that it's based on reputation and acclaim. If you're an 3.329 -unknown, Linus will probably ignore changes from you without even 3.330 -responding. But a subsystem maintainer will probably review them, and 3.331 -will likely take them if they pass their criteria for suitability. 3.332 -The more <quote>good</quote> changes you contribute to a maintainer, the more 3.333 -likely they are to trust your judgment and accept your changes. If 3.334 -you're well-known and maintain a long-lived branch for something Linus 3.335 -hasn't yet accepted, people with similar interests may pull your 3.336 -changes regularly to keep up with your work. 3.337 -</para> 3.338 - 3.339 -<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote> 3.340 -boundaries. If you're a respected but specialised storage hacker, and 3.341 -you try to fix a networking bug, that change will receive a level of 3.342 -scrutiny from a network maintainer comparable to a change from a 3.343 -complete stranger. 3.344 -</para> 3.345 - 3.346 -<para>To people who come from more orderly project backgrounds, the 3.347 -comparatively chaotic Linux kernel development process often seems 3.348 -completely insane. It's subject to the whims of individuals; people 3.349 -make sweeping changes whenever they deem it appropriate; and the pace 3.350 -of development is astounding. And yet Linux is a highly successful, 3.351 -well-regarded piece of software. 3.352 -</para> 3.353 - 3.354 -</sect2> 3.355 -<sect2> 3.356 -<title>Pull-only versus shared-push collaboration</title> 3.357 - 3.358 -<para>A perpetual source of heat in the open source community is whether a 3.359 -development model in which people only ever pull changes from others 3.360 -is <quote>better than</quote> one in which multiple people can push changes to a 3.361 -shared repository. 3.362 -</para> 3.363 - 3.364 -<para>Typically, the backers of the shared-push model use tools that 3.365 -actively enforce this approach. If you're using a centralised 3.366 -revision control tool such as Subversion, there's no way to make a 3.367 -choice over which model you'll use: the tool gives you shared-push, 3.368 -and if you want to do anything else, you'll have to roll your own 3.369 -approach on top (such as applying a patch by hand). 3.370 -</para> 3.371 - 3.372 -<para>A good distributed revision control tool, such as Mercurial, will 3.373 -support both models. You and your collaborators can then structure 3.374 -how you work together based on your own needs and preferences, not on 3.375 -what contortions your tools force you into. 3.376 -</para> 3.377 - 3.378 -</sect2> 3.379 -<sect2> 3.380 -<title>Where collaboration meets branch management</title> 3.381 - 3.382 -<para>Once you and your team set up some shared repositories and start 3.383 -propagating changes back and forth between local and shared repos, you 3.384 -begin to face a related, but slightly different challenge: that of 3.385 -managing the multiple directions in which your team may be moving at 3.386 -once. Even though this subject is intimately related to how your team 3.387 -collaborates, it's dense enough to merit treatment of its own, in 3.388 -chapter <xref linkend="chap:branch"/>. 3.389 -</para> 3.390 - 3.391 -</sect2> 3.392 -</sect1> 3.393 -<sect1> 3.394 -<title>The technical side of sharing</title> 3.395 - 3.396 -<para>The remainder of this chapter is devoted to the question of serving 3.397 -data to your collaborators. 3.398 -</para> 3.399 - 3.400 -</sect1> 3.401 -<sect1> 3.402 -<title>Informal sharing with <command role="hg-cmd">hg serve</command></title> 3.403 -<para>\label{sec:collab:serve} 3.404 -</para> 3.405 - 3.406 -<para>Mercurial's <command role="hg-cmd">hg serve</command> command is wonderfully suited to small, 3.407 -tight-knit, and fast-paced group environments. It also provides a 3.408 -great way to get a feel for using Mercurial commands over a network. 3.409 -</para> 3.410 - 3.411 -<para>Run <command role="hg-cmd">hg serve</command> inside a repository, and in under a second it will 3.412 -bring up a specialised HTTP server; this will accept connections from 3.413 -any client, and serve up data for that repository until you terminate 3.414 -it. Anyone who knows the URL of the server you just started, and can 3.415 -talk to your computer over the network, can then use a web browser or 3.416 -Mercurial to read data from that repository. A URL for a 3.417 -<command role="hg-cmd">hg serve</command> instance running on a laptop is likely to look something 3.418 -like <literal>http://my-laptop.local:8000/</literal>. 3.419 -</para> 3.420 - 3.421 -<para>The <command role="hg-cmd">hg serve</command> command is <emphasis>not</emphasis> a general-purpose web server. 3.422 -It can do only two things: 3.423 -</para> 3.424 -<itemizedlist> 3.425 -<listitem><para>Allow people to browse the history of the repository it's 3.426 - serving, from their normal web browsers. 3.427 -</para> 3.428 -</listitem> 3.429 -<listitem><para>Speak Mercurial's wire protocol, so that people can 3.430 - <command role="hg-cmd">hg clone</command> or <command role="hg-cmd">hg pull</command> changes from that repository. 3.431 -</para> 3.432 -</listitem></itemizedlist> 3.433 -<para>In particular, <command role="hg-cmd">hg serve</command> won't allow remote users to <emphasis>modify</emphasis> 3.434 -your repository. It's intended for read-only use. 3.435 -</para> 3.436 - 3.437 -<para>If you're getting started with Mercurial, there's nothing to prevent 3.438 -you from using <command role="hg-cmd">hg serve</command> to serve up a repository on your own 3.439 -computer, then use commands like <command role="hg-cmd">hg clone</command>, <command role="hg-cmd">hg incoming</command>, and 3.440 -so on to talk to that server as if the repository was hosted remotely. 3.441 -This can help you to quickly get acquainted with using commands on 3.442 -network-hosted repositories. 3.443 -</para> 3.444 - 3.445 -<sect2> 3.446 -<title>A few things to keep in mind</title> 3.447 - 3.448 -<para>Because it provides unauthenticated read access to all clients, you 3.449 -should only use <command role="hg-cmd">hg serve</command> in an environment where you either don't 3.450 -care, or have complete control over, who can access your network and 3.451 -pull data from your repository. 3.452 -</para> 3.453 - 3.454 -<para>The <command role="hg-cmd">hg serve</command> command knows nothing about any firewall software 3.455 -you might have installed on your system or network. It cannot detect 3.456 -or control your firewall software. If other people are unable to talk 3.457 -to a running <command role="hg-cmd">hg serve</command> instance, the second thing you should do 3.458 -(<emphasis>after</emphasis> you make sure that they're using the correct URL) is 3.459 -check your firewall configuration. 3.460 -</para> 3.461 - 3.462 -<para>By default, <command role="hg-cmd">hg serve</command> listens for incoming connections on 3.463 -port 8000. If another process is already listening on the port you 3.464 -want to use, you can specify a different port to listen on using the 3.465 -<option role="hg-opt-serve">-p</option> option. 3.466 -</para> 3.467 - 3.468 -<para>Normally, when <command role="hg-cmd">hg serve</command> starts, it prints no output, which can be 3.469 -a bit unnerving. If you'd like to confirm that it is indeed running 3.470 -correctly, and find out what URL you should send to your 3.471 -collaborators, start it with the <option role="hg-opt-global">-v</option> option. 3.472 -</para> 3.473 - 3.474 -</sect2> 3.475 -</sect1> 3.476 -<sect1> 3.477 -<title>Using the Secure Shell (ssh) protocol</title> 3.478 -<para>\label{sec:collab:ssh} 3.479 -</para> 3.480 - 3.481 -<para>You can pull and push changes securely over a network connection using 3.482 -the Secure Shell (<literal>ssh</literal>) protocol. To use this successfully, 3.483 -you may have to do a little bit of configuration on the client or 3.484 -server sides. 3.485 -</para> 3.486 - 3.487 -<para>If you're not familiar with ssh, it's a network protocol that lets you 3.488 -securely communicate with another computer. To use it with Mercurial, 3.489 -you'll be setting up one or more user accounts on a server so that 3.490 -remote users can log in and execute commands. 3.491 -</para> 3.492 - 3.493 -<para>(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some of the 3.494 -material that follows to be elementary in nature.) 3.495 -</para> 3.496 - 3.497 -<sect2> 3.498 -<title>How to read and write ssh URLs</title> 3.499 - 3.500 -<para>An ssh URL tends to look like this: 3.501 -</para> 3.502 -<programlisting> 3.503 -<para> ssh://bos@hg.serpentine.com:22/hg/hgbook 3.504 -</para> 3.505 +<chapter id="cha:collab"> 3.506 + <?dbhtml filename="collaborating-with-other-people.html"?> 3.507 + <title>Collaborating with other people</title> 3.508 + 3.509 + <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 3.510 + any policy on how people ought to work with each other. However, 3.511 + if you're new to distributed revision control, it helps to have 3.512 + some tools and examples in mind when you're thinking about 3.513 + possible workflow models.</para> 3.514 + 3.515 + <sect1> 3.516 + <title>Mercurial's web interface</title> 3.517 + 3.518 + <para id="x_44b">Mercurial has a powerful web interface that provides several 3.519 + useful capabilities.</para> 3.520 + 3.521 + <para id="x_44c">For interactive use, the web interface lets you browse a 3.522 + single repository or a collection of repositories. You can view 3.523 + the history of a repository, examine each change (comments and 3.524 + diffs), and view the contents of each directory and file. You 3.525 + can even get a view of history that gives a graphical view of 3.526 + the relationships between individual changes and merges.</para> 3.527 + 3.528 + <para id="x_44d">Also for human consumption, the web interface provides 3.529 + Atom and RSS feeds of the changes in a repository. This lets you 3.530 + <quote>subscribe</quote> to a repository using your favorite 3.531 + feed reader, and be automatically notified of activity in that 3.532 + repository as soon as it happens. I find this capability much 3.533 + more convenient than the model of subscribing to a mailing list 3.534 + to which notifications are sent, as it requires no additional 3.535 + configuration on the part of whoever is serving the 3.536 + repository.</para> 3.537 + 3.538 + <para id="x_44e">The web interface also lets remote users clone a repository, 3.539 + pull changes from it, and (when the server is configured to 3.540 + permit it) push changes back to it. Mercurial's HTTP tunneling 3.541 + protocol aggressively compresses data, so that it works 3.542 + efficiently even over low-bandwidth network connections.</para> 3.543 + 3.544 + <para id="x_44f">The easiest way to get started with the web interface is to 3.545 + use your web browser to visit an existing repository, such as 3.546 + the master Mercurial repository at <ulink 3.547 + url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para> 3.548 + 3.549 + <para id="x_450">If you're interested in providing a web interface 3.550 + to your own repositories, there are several good ways to do 3.551 + this.</para> 3.552 + 3.553 + <para id="x_69d">The easiest and fastest way to get started in an informal 3.554 + environment is to use the <command role="hg-cmd">hg 3.555 + serve</command> command, which is best suited to short-term 3.556 + <quote>lightweight</quote> serving. See <xref 3.557 + linkend="sec:collab:serve"/> below for details of how to use 3.558 + this command.</para> 3.559 + 3.560 + <para id="x_69e">For longer-lived repositories that you'd like to 3.561 + have permanently available, there are several public hosting 3.562 + services available. Some are free to open source projects, 3.563 + while others offer paid commercial hosting. An up-to-date list 3.564 + is available at <ulink 3.565 + url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para> 3.566 + 3.567 + <para id="x_6a0">If you would prefer to host your own repositories, Mercurial 3.568 + has built-in support for several popular hosting technologies, 3.569 + most notably CGI (Common Gateway Interface), and WSGI (Web 3.570 + Services Gateway Interface). See <xref 3.571 + linkend="sec:collab:cgi"/> for details of CGI and WSGI 3.572 + configuration.</para> 3.573 + </sect1> 3.574 + 3.575 + <sect1> 3.576 + <title>Collaboration models</title> 3.577 + 3.578 + <para id="x_451">With a suitably flexible tool, making decisions about 3.579 + workflow is much more of a social engineering challenge than a 3.580 + technical one. Mercurial imposes few limitations on how you can 3.581 + structure the flow of work in a project, so it's up to you and 3.582 + your group to set up and live with a model that matches your own 3.583 + particular needs.</para> 3.584 + 3.585 + <sect2> 3.586 + <title>Factors to keep in mind</title> 3.587 + 3.588 + <para id="x_452">The most important aspect of any model that you must keep 3.589 + in mind is how well it matches the needs and capabilities of 3.590 + the people who will be using it. This might seem 3.591 + self-evident; even so, you still can't afford to forget it for 3.592 + a moment.</para> 3.593 + 3.594 + <para id="x_453">I once put together a workflow model that seemed to make 3.595 + perfect sense to me, but that caused a considerable amount of 3.596 + consternation and strife within my development team. In spite 3.597 + of my attempts to explain why we needed a complex set of 3.598 + branches, and how changes ought to flow between them, a few 3.599 + team members revolted. Even though they were smart people, 3.600 + they didn't want to pay attention to the constraints we were 3.601 + operating under, or face the consequences of those constraints 3.602 + in the details of the model that I was advocating.</para> 3.603 + 3.604 + <para id="x_454">Don't sweep foreseeable social or technical problems under 3.605 + the rug. Whatever scheme you put into effect, you should plan 3.606 + for mistakes and problem scenarios. Consider adding automated 3.607 + machinery to prevent, or quickly recover from, trouble that 3.608 + you can anticipate. As an example, if you intend to have a 3.609 + branch with not-for-release changes in it, you'd do well to 3.610 + think early about the possibility that someone might 3.611 + accidentally merge those changes into a release branch. You 3.612 + could avoid this particular problem by writing a hook that 3.613 + prevents changes from being merged from an inappropriate 3.614 + branch.</para> 3.615 + </sect2> 3.616 + 3.617 + <sect2> 3.618 + <title>Informal anarchy</title> 3.619 + 3.620 + <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 3.621 + approach as something sustainable, but it's a model that's 3.622 + easy to grasp, and it works perfectly well in a few unusual 3.623 + situations.</para> 3.624 + 3.625 + <para id="x_456">As one example, many projects have a loose-knit group of 3.626 + collaborators who rarely physically meet each other. Some 3.627 + groups like to overcome the isolation of working at a distance 3.628 + by organizing occasional <quote>sprints</quote>. In a sprint, 3.629 + a number of people get together in a single location (a 3.630 + company's conference room, a hotel meeting room, that kind of 3.631 + place) and spend several days more or less locked in there, 3.632 + hacking intensely on a handful of projects.</para> 3.633 + 3.634 + <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the 3.635 + <command role="hg-cmd">hg serve</command> command, since 3.636 + <command role="hg-cmd">hg serve</command> does not require any 3.637 + fancy server infrastructure. You can get started with 3.638 + <command role="hg-cmd">hg serve</command> in moments, by 3.639 + reading <xref linkend="sec:collab:serve"/> below. Then simply 3.640 + tell the person next to you that you're running a server, send 3.641 + the URL to them in an instant message, and you immediately 3.642 + have a quick-turnaround way to work together. They can type 3.643 + your URL into their web browser and quickly review your 3.644 + changes; or they can pull a bugfix from you and verify it; or 3.645 + they can clone a branch containing a new feature and try it 3.646 + out.</para> 3.647 + 3.648 + <para id="x_458">The charm, and the problem, with doing things 3.649 + in an ad hoc fashion like this is that only people who know 3.650 + about your changes, and where they are, can see them. Such an 3.651 + informal approach simply doesn't scale beyond a handful 3.652 + people, because each individual needs to know about 3.653 + <emphasis>n</emphasis> different repositories to pull 3.654 + from.</para> 3.655 + </sect2> 3.656 + 3.657 + <sect2> 3.658 + <title>A single central repository</title> 3.659 + 3.660 + <para id="x_459">For smaller projects migrating from a centralised revision 3.661 + control tool, perhaps the easiest way to get started is to 3.662 + have changes flow through a single shared central repository. 3.663 + This is also the most common <quote>building block</quote> for 3.664 + more ambitious workflow schemes.</para> 3.665 + 3.666 + <para id="x_45a">Contributors start by cloning a copy of this repository. 3.667 + They can pull changes from it whenever they need to, and some 3.668 + (perhaps all) developers have permission to push a change back 3.669 + when they're ready for other people to see it.</para> 3.670 + 3.671 + <para id="x_45b">Under this model, it can still often make sense for people 3.672 + to pull changes directly from each other, without going 3.673 + through the central repository. Consider a case in which I 3.674 + have a tentative bug fix, but I am worried that if I were to 3.675 + publish it to the central repository, it might subsequently 3.676 + break everyone else's trees as they pull it. To reduce the 3.677 + potential for damage, I can ask you to clone my repository 3.678 + into a temporary repository of your own and test it. This 3.679 + lets us put off publishing the potentially unsafe change until 3.680 + it has had a little testing.</para> 3.681 + 3.682 + <para id="x_45c">If a team is hosting its own repository in this 3.683 + kind of scenario, people will usually use the 3.684 + <command>ssh</command> protocol to securely push changes to 3.685 + the central repository, as documented in <xref 3.686 + linkend="sec:collab:ssh"/>. It's also usual to publish a 3.687 + read-only copy of the repository over HTTP, as in 3.688 + <xref linkend="sec:collab:cgi"/>. Publishing over HTTP 3.689 + satisfies the needs of people who don't have push access, and 3.690 + those who want to use web browsers to browse the repository's 3.691 + history.</para> 3.692 + </sect2> 3.693 + 3.694 + <sect2> 3.695 + <title>A hosted central repository</title> 3.696 + 3.697 + <para id="x_6a1">A wonderful thing about public hosting services like 3.698 + <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that 3.699 + not only do they handle the fiddly server configuration 3.700 + details, such as user accounts, authentication, and secure 3.701 + wire protocols, they provide additional infrastructure to make 3.702 + this model work well.</para> 3.703 + 3.704 + <para id="x_6a2">For instance, a well-engineered hosting service will let 3.705 + people clone their own copies of a repository with a single 3.706 + click. This lets people work in separate spaces and share 3.707 + their changes when they're ready.</para> 3.708 + 3.709 + <para id="x_6a3">In addition, a good hosting service will let people 3.710 + communicate with each other, for instance to say <quote>there 3.711 + are changes ready for you to review in this 3.712 + tree</quote>.</para> 3.713 + </sect2> 3.714 + 3.715 + <sect2> 3.716 + <title>Working with multiple branches</title> 3.717 + 3.718 + <para id="x_45d">Projects of any significant size naturally tend to make 3.719 + progress on several fronts simultaneously. In the case of 3.720 + software, it's common for a project to go through periodic 3.721 + official releases. A release might then go into 3.722 + <quote>maintenance mode</quote> for a while after its first 3.723 + publication; maintenance releases tend to contain only bug 3.724 + fixes, not new features. In parallel with these maintenance 3.725 + releases, one or more future releases may be under 3.726 + development. People normally use the word 3.727 + <quote>branch</quote> to refer to one of these many slightly 3.728 + different directions in which development is 3.729 + proceeding.</para> 3.730 + 3.731 + <para id="x_45e">Mercurial is particularly well suited to managing a number 3.732 + of simultaneous, but not identical, branches. Each 3.733 + <quote>development direction</quote> can live in its own 3.734 + central repository, and you can merge changes from one to 3.735 + another as the need arises. Because repositories are 3.736 + independent of each other, unstable changes in a development 3.737 + branch will never affect a stable branch unless someone 3.738 + explicitly merges those changes into the stable branch.</para> 3.739 + 3.740 + <para id="x_45f">Here's an example of how this can work in practice. Let's 3.741 + say you have one <quote>main branch</quote> on a central 3.742 + server.</para> 3.743 + 3.744 + &interaction.branching.init; 3.745 + 3.746 + <para id="x_460">People clone it, make changes locally, test them, and push 3.747 + them back.</para> 3.748 + 3.749 + <para id="x_461">Once the main branch reaches a release milestone, you can 3.750 + use the <command role="hg-cmd">hg tag</command> command to 3.751 + give a permanent name to the milestone revision.</para> 3.752 + 3.753 + &interaction.branching.tag; 3.754 + 3.755 + <para id="x_462">Let's say some ongoing 3.756 + development occurs on the main branch.</para> 3.757 + 3.758 + &interaction.branching.main; 3.759 + 3.760 + <para id="x_463">Using the tag that was recorded at the milestone, people 3.761 + who clone that repository at any time in the future can use 3.762 + <command role="hg-cmd">hg update</command> to get a copy of 3.763 + the working directory exactly as it was when that tagged 3.764 + revision was committed.</para> 3.765 + 3.766 + &interaction.branching.update; 3.767 + 3.768 + <para id="x_464">In addition, immediately after the main branch is tagged, 3.769 + we can then clone the main branch on the server to a new 3.770 + <quote>stable</quote> branch, also on the server.</para> 3.771 + 3.772 + &interaction.branching.clone; 3.773 + 3.774 + <para id="x_465">If we need to make a change to the stable 3.775 + branch, we can then clone <emphasis>that</emphasis> 3.776 + repository, make our changes, commit, and push our changes 3.777 + back there.</para> 3.778 + 3.779 + &interaction.branching.stable; 3.780 + 3.781 + <para id="x_466">Because Mercurial repositories are independent, and 3.782 + Mercurial doesn't move changes around automatically, the 3.783 + stable and main branches are <emphasis>isolated</emphasis> 3.784 + from each other. The changes that we made on the main branch 3.785 + don't <quote>leak</quote> to the stable branch, and vice 3.786 + versa.</para> 3.787 + 3.788 + <para id="x_467">We'll often want all of our bugfixes on the stable 3.789 + branch to show up on the main branch, too. Rather than 3.790 + rewrite a bugfix on the main branch, we can simply pull and 3.791 + merge changes from the stable to the main branch, and 3.792 + Mercurial will bring those bugfixes in for us.</para> 3.793 + 3.794 + &interaction.branching.merge; 3.795 + 3.796 + <para id="x_468">The main branch will still contain changes that 3.797 + are not on the stable branch, but it will also contain all of 3.798 + the bugfixes from the stable branch. The stable branch 3.799 + remains unaffected by these changes, since changes are only 3.800 + flowing from the stable to the main branch, and not the other 3.801 + way.</para> 3.802 + </sect2> 3.803 + 3.804 + <sect2> 3.805 + <title>Feature branches</title> 3.806 + 3.807 + <para id="x_469">For larger projects, an effective way to manage change is 3.808 + to break up a team into smaller groups. Each group has a 3.809 + shared branch of its own, cloned from a single 3.810 + <quote>master</quote> branch used by the entire project. 3.811 + People working on an individual branch are typically quite 3.812 + isolated from developments on other branches.</para> 3.813 + 3.814 + <figure id="fig:collab:feature-branches"> 3.815 + <title>Feature branches</title> 3.816 + <mediaobject> 3.817 + <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject> 3.818 + <textobject><phrase>XXX add text</phrase></textobject> 3.819 + </mediaobject> 3.820 + </figure> 3.821 + 3.822 + <para id="x_46b">When a particular feature is deemed to be in suitable 3.823 + shape, someone on that feature team pulls and merges from the 3.824 + master branch into the feature branch, then pushes back up to 3.825 + the master branch.</para> 3.826 + </sect2> 3.827 + 3.828 + <sect2> 3.829 + <title>The release train</title> 3.830 + 3.831 + <para id="x_46c">Some projects are organized on a <quote>train</quote> 3.832 + basis: a release is scheduled to happen every few months, and 3.833 + whatever features are ready when the <quote>train</quote> is 3.834 + ready to leave are allowed in.</para> 3.835 + 3.836 + <para id="x_46d">This model resembles working with feature branches. The 3.837 + difference is that when a feature branch misses a train, 3.838 + someone on the feature team pulls and merges the changes that 3.839 + went out on that train release into the feature branch, and 3.840 + the team continues its work on top of that release so that 3.841 + their feature can make the next release.</para> 3.842 + </sect2> 3.843 + 3.844 + <sect2> 3.845 + <title>The Linux kernel model</title> 3.846 + 3.847 + <para id="x_46e">The development of the Linux kernel has a shallow 3.848 + hierarchical structure, surrounded by a cloud of apparent 3.849 + chaos. Because most Linux developers use 3.850 + <command>git</command>, a distributed revision control tool 3.851 + with capabilities similar to Mercurial, it's useful to 3.852 + describe the way work flows in that environment; if you like 3.853 + the ideas, the approach translates well across tools.</para> 3.854 + 3.855 + <para id="x_46f">At the center of the community sits Linus Torvalds, the 3.856 + creator of Linux. He publishes a single source repository 3.857 + that is considered the <quote>authoritative</quote> current 3.858 + tree by the entire developer community. Anyone can clone 3.859 + Linus's tree, but he is very choosy about whose trees he pulls 3.860 + from.</para> 3.861 + 3.862 + <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 3.863 + As a general rule, he pulls whatever changes they publish, in 3.864 + most cases without even reviewing those changes. Some of 3.865 + those lieutenants are generally agreed to be 3.866 + <quote>maintainers</quote>, responsible for specific 3.867 + subsystems within the kernel. If a random kernel hacker wants 3.868 + to make a change to a subsystem that they want to end up in 3.869 + Linus's tree, they must find out who the subsystem's 3.870 + maintainer is, and ask that maintainer to take their change. 3.871 + If the maintainer reviews their changes and agrees to take 3.872 + them, they'll pass them along to Linus in due course.</para> 3.873 + 3.874 + <para id="x_471">Individual lieutenants have their own approaches to 3.875 + reviewing, accepting, and publishing changes; and for deciding 3.876 + when to feed them to Linus. In addition, there are several 3.877 + well known branches that people use for different purposes. 3.878 + For example, a few people maintain <quote>stable</quote> 3.879 + repositories of older versions of the kernel, to which they 3.880 + apply critical fixes as needed. Some maintainers publish 3.881 + multiple trees: one for experimental changes; one for changes 3.882 + that they are about to feed upstream; and so on. Others just 3.883 + publish a single tree.</para> 3.884 + 3.885 + <para id="x_472">This model has two notable features. The first is that 3.886 + it's <quote>pull only</quote>. You have to ask, convince, or 3.887 + beg another developer to take a change from you, because there 3.888 + are almost no trees to which more than one person can push, 3.889 + and there's no way to push changes into a tree that someone 3.890 + else controls.</para> 3.891 + 3.892 + <para id="x_473">The second is that it's based on reputation and acclaim. 3.893 + If you're an unknown, Linus will probably ignore changes from 3.894 + you without even responding. But a subsystem maintainer will 3.895 + probably review them, and will likely take them if they pass 3.896 + their criteria for suitability. The more <quote>good</quote> 3.897 + changes you contribute to a maintainer, the more likely they 3.898 + are to trust your judgment and accept your changes. If you're 3.899 + well-known and maintain a long-lived branch for something 3.900 + Linus hasn't yet accepted, people with similar interests may 3.901 + pull your changes regularly to keep up with your work.</para> 3.902 + 3.903 + <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 3.904 + or <quote>people</quote> boundaries. If you're a respected 3.905 + but specialised storage hacker, and you try to fix a 3.906 + networking bug, that change will receive a level of scrutiny 3.907 + from a network maintainer comparable to a change from a 3.908 + complete stranger.</para> 3.909 + 3.910 + <para id="x_475">To people who come from more orderly project backgrounds, 3.911 + the comparatively chaotic Linux kernel development process 3.912 + often seems completely insane. It's subject to the whims of 3.913 + individuals; people make sweeping changes whenever they deem 3.914 + it appropriate; and the pace of development is astounding. 3.915 + And yet Linux is a highly successful, well-regarded piece of 3.916 + software.</para> 3.917 + </sect2> 3.918 + 3.919 + <sect2> 3.920 + <title>Pull-only versus shared-push collaboration</title> 3.921 + 3.922 + <para id="x_476">A perpetual source of heat in the open source community is 3.923 + whether a development model in which people only ever pull 3.924 + changes from others is <quote>better than</quote> one in which 3.925 + multiple people can push changes to a shared 3.926 + repository.</para> 3.927 + 3.928 + <para id="x_477">Typically, the backers of the shared-push model use tools 3.929 + that actively enforce this approach. If you're using a 3.930 + centralised revision control tool such as Subversion, there's 3.931 + no way to make a choice over which model you'll use: the tool 3.932 + gives you shared-push, and if you want to do anything else, 3.933 + you'll have to roll your own approach on top (such as applying 3.934 + a patch by hand).</para> 3.935 + 3.936 + <para id="x_478">A good distributed revision control tool will 3.937 + support both models. You and your collaborators can then 3.938 + structure how you work together based on your own needs and 3.939 + preferences, not on what contortions your tools force you 3.940 + into.</para> 3.941 + </sect2> 3.942 + <sect2> 3.943 + <title>Where collaboration meets branch management</title> 3.944 + 3.945 + <para id="x_479">Once you and your team set up some shared 3.946 + repositories and start propagating changes back and forth 3.947 + between local and shared repos, you begin to face a related, 3.948 + but slightly different challenge: that of managing the 3.949 + multiple directions in which your team may be moving at once. 3.950 + Even though this subject is intimately related to how your 3.951 + team collaborates, it's dense enough to merit treatment of its 3.952 + own, in <xref linkend="chap:branch"/>.</para> 3.953 + </sect2> 3.954 + </sect1> 3.955 + 3.956 + <sect1> 3.957 + <title>The technical side of sharing</title> 3.958 + 3.959 + <para id="x_47a">The remainder of this chapter is devoted to the question of 3.960 + sharing changes with your collaborators.</para> 3.961 + </sect1> 3.962 + 3.963 + <sect1 id="sec:collab:serve"> 3.964 + <title>Informal sharing with <command role="hg-cmd">hg 3.965 + serve</command></title> 3.966 + 3.967 + <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 3.968 + command is wonderfully suited to small, tight-knit, and 3.969 + fast-paced group environments. It also provides a great way to 3.970 + get a feel for using Mercurial commands over a network.</para> 3.971 + 3.972 + <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 3.973 + repository, and in under a second it will bring up a specialised 3.974 + HTTP server; this will accept connections from any client, and 3.975 + serve up data for that repository until you terminate it. 3.976 + Anyone who knows the URL of the server you just started, and can 3.977 + talk to your computer over the network, can then use a web 3.978 + browser or Mercurial to read data from that repository. A URL 3.979 + for a <command role="hg-cmd">hg serve</command> instance running 3.980 + on a laptop is likely to look something like 3.981 + <literal>http://my-laptop.local:8000/</literal>.</para> 3.982 + 3.983 + <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 3.984 + <emphasis>not</emphasis> a general-purpose web server. It can do 3.985 + only two things:</para> 3.986 + <itemizedlist> 3.987 + <listitem><para id="x_47e">Allow people to browse the history of the 3.988 + repository it's serving, from their normal web 3.989 + browsers.</para> 3.990 + </listitem> 3.991 + <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 3.992 + can <command role="hg-cmd">hg clone</command> or <command 3.993 + role="hg-cmd">hg pull</command> changes from that 3.994 + repository.</para> 3.995 + </listitem></itemizedlist> 3.996 + <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 3.997 + won't allow remote users to <emphasis>modify</emphasis> your 3.998 + repository. It's intended for read-only use.</para> 3.999 + 3.1000 + <para id="x_481">If you're getting started with Mercurial, there's nothing to 3.1001 + prevent you from using <command role="hg-cmd">hg serve</command> 3.1002 + to serve up a repository on your own computer, then use commands 3.1003 + like <command role="hg-cmd">hg clone</command>, <command 3.1004 + role="hg-cmd">hg incoming</command>, and so on to talk to that 3.1005 + server as if the repository was hosted remotely. This can help 3.1006 + you to quickly get acquainted with using commands on 3.1007 + network-hosted repositories.</para> 3.1008 + 3.1009 + <sect2> 3.1010 + <title>A few things to keep in mind</title> 3.1011 + 3.1012 + <para id="x_482">Because it provides unauthenticated read access to all 3.1013 + clients, you should only use <command role="hg-cmd">hg 3.1014 + serve</command> in an environment where you either don't 3.1015 + care, or have complete control over, who can access your 3.1016 + network and pull data from your repository.</para> 3.1017 + 3.1018 + <para id="x_483">The <command role="hg-cmd">hg serve</command> command 3.1019 + knows nothing about any firewall software you might have 3.1020 + installed on your system or network. It cannot detect or 3.1021 + control your firewall software. If other people are unable to 3.1022 + talk to a running <command role="hg-cmd">hg serve</command> 3.1023 + instance, the second thing you should do 3.1024 + (<emphasis>after</emphasis> you make sure that they're using 3.1025 + the correct URL) is check your firewall configuration.</para> 3.1026 + 3.1027 + <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 3.1028 + listens for incoming connections on port 8000. If another 3.1029 + process is already listening on the port you want to use, you 3.1030 + can specify a different port to listen on using the <option 3.1031 + role="hg-opt-serve">-p</option> option.</para> 3.1032 + 3.1033 + <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 3.1034 + starts, it prints no output, which can be a bit unnerving. If 3.1035 + you'd like to confirm that it is indeed running correctly, and 3.1036 + find out what URL you should send to your collaborators, start 3.1037 + it with the <option role="hg-opt-global">-v</option> 3.1038 + option.</para> 3.1039 + </sect2> 3.1040 + </sect1> 3.1041 + 3.1042 + <sect1 id="sec:collab:ssh"> 3.1043 + <title>Using the Secure Shell (ssh) protocol</title> 3.1044 + 3.1045 + <para id="x_486">You can pull and push changes securely over a network 3.1046 + connection using the Secure Shell (<literal>ssh</literal>) 3.1047 + protocol. To use this successfully, you may have to do a little 3.1048 + bit of configuration on the client or server sides.</para> 3.1049 + 3.1050 + <para id="x_487">If you're not familiar with ssh, it's the name of 3.1051 + both a command and a network protocol that let you securely 3.1052 + communicate with another computer. To use it with Mercurial, 3.1053 + you'll be setting up one or more user accounts on a server so 3.1054 + that remote users can log in and execute commands.</para> 3.1055 + 3.1056 + <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 3.1057 + probably find some of the material that follows to be elementary 3.1058 + in nature.)</para> 3.1059 + 3.1060 + <sect2> 3.1061 + <title>How to read and write ssh URLs</title> 3.1062 + 3.1063 + <para id="x_489">An ssh URL tends to look like this:</para> 3.1064 + <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 3.1065 + <orderedlist> 3.1066 + <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 3.1067 + part tells Mercurial to use the ssh protocol.</para> 3.1068 + </listitem> 3.1069 + <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 3.1070 + component indicates what username to log into the server 3.1071 + as. You can leave this out if the remote username is the 3.1072 + same as your local username.</para> 3.1073 + </listitem> 3.1074 + <listitem><para id="x_48c">The 3.1075 + <quote><literal>hg.serpentine.com</literal></quote> gives 3.1076 + the hostname of the server to log into.</para> 3.1077 + </listitem> 3.1078 + <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 3.1079 + number to connect to the server on. The default port is 3.1080 + 22, so you only need to specify a colon and port number if 3.1081 + you're <emphasis>not</emphasis> using port 22.</para> 3.1082 + </listitem> 3.1083 + <listitem><para id="x_48e">The remainder of the URL is the local path to 3.1084 + the repository on the server.</para> 3.1085 + </listitem></orderedlist> 3.1086 + 3.1087 + <para id="x_48f">There's plenty of scope for confusion with the path 3.1088 + component of ssh URLs, as there is no standard way for tools 3.1089 + to interpret it. Some programs behave differently than others 3.1090 + when dealing with these paths. This isn't an ideal situation, 3.1091 + but it's unlikely to change. Please read the following 3.1092 + paragraphs carefully.</para> 3.1093 + 3.1094 + <para id="x_490">Mercurial treats the path to a repository on the server as 3.1095 + relative to the remote user's home directory. For example, if 3.1096 + user <literal>foo</literal> on the server has a home directory 3.1097 + of <filename class="directory">/home/foo</filename>, then an 3.1098 + ssh URL that contains a path component of <filename 3.1099 + class="directory">bar</filename> <emphasis>really</emphasis> 3.1100 + refers to the directory <filename 3.1101 + class="directory">/home/foo/bar</filename>.</para> 3.1102 + 3.1103 + <para id="x_491">If you want to specify a path relative to another user's 3.1104 + home directory, you can use a path that starts with a tilde 3.1105 + character followed by the user's name (let's call them 3.1106 + <literal>otheruser</literal>), like this.</para> 3.1107 + <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 3.1108 + 3.1109 + <para id="x_492">And if you really want to specify an 3.1110 + <emphasis>absolute</emphasis> path on the server, begin the 3.1111 + path component with two slashes, as in this example.</para> 3.1112 + <programlisting>ssh://server//absolute/path</programlisting> 3.1113 + </sect2> 3.1114 + 3.1115 + <sect2> 3.1116 + <title>Finding an ssh client for your system</title> 3.1117 + 3.1118 + <para id="x_493">Almost every Unix-like system comes with OpenSSH 3.1119 + preinstalled. If you're using such a system, run 3.1120 + <literal>which ssh</literal> to find out if the 3.1121 + <command>ssh</command> command is installed (it's usually in 3.1122 + <filename class="directory">/usr/bin</filename>). In the 3.1123 + unlikely event that it isn't present, take a look at your 3.1124 + system documentation to figure out how to install it.</para> 3.1125 + 3.1126 + <para id="x_494">On Windows, the TortoiseHg package is bundled 3.1127 + with a version of Simon Tatham's excellent 3.1128 + <command>plink</command> command, and you should not need to 3.1129 + do any further configuration.</para> 3.1130 + </sect2> 3.1131 + 3.1132 + <sect2> 3.1133 + <title>Generating a key pair</title> 3.1134 + 3.1135 + <para id="x_499">To avoid the need to repetitively type a 3.1136 + password every time you need to use your ssh client, I 3.1137 + recommend generating a key pair.</para> 3.1138 + 3.1139 + <tip> 3.1140 + <title>Key pairs are not mandatory</title> 3.1141 + 3.1142 + <para id="x_6a4">Mercurial knows nothing about ssh authentication or key 3.1143 + pairs. You can, if you like, safely ignore this section and 3.1144 + the one that follows until you grow tired of repeatedly 3.1145 + typing ssh passwords.</para> 3.1146 + </tip> 3.1147 + 3.1148 + <itemizedlist> 3.1149 + <listitem> 3.1150 + <para id="x_6a5">On a Unix-like system, the 3.1151 + <command>ssh-keygen</command> command will do the 3.1152 + trick.</para> 3.1153 + <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need 3.1154 + to download a command named <command>puttygen</command> 3.1155 + from <ulink 3.1156 + url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 3.1157 + PuTTY web site</ulink> to generate a key pair. See 3.1158 + <ulink 3.1159 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 3.1160 + <command>puttygen</command> documentation</ulink> for 3.1161 + details of how use the command.</para> 3.1162 + </listitem> 3.1163 + </itemizedlist> 3.1164 + 3.1165 + <para id="x_49a">When you generate a key pair, it's usually 3.1166 + <emphasis>highly</emphasis> advisable to protect it with a 3.1167 + passphrase. (The only time that you might not want to do this 3.1168 + is when you're using the ssh protocol for automated tasks on a 3.1169 + secure network.)</para> 3.1170 + 3.1171 + <para id="x_49b">Simply generating a key pair isn't enough, however. 3.1172 + You'll need to add the public key to the set of authorised 3.1173 + keys for whatever user you're logging in remotely as. For 3.1174 + servers using OpenSSH (the vast majority), this will mean 3.1175 + adding the public key to a list in a file called <filename 3.1176 + role="special">authorized_keys</filename> in their <filename 3.1177 + role="special" class="directory">.ssh</filename> 3.1178 + directory.</para> 3.1179 + 3.1180 + <para id="x_49c">On a Unix-like system, your public key will have a 3.1181 + <filename>.pub</filename> extension. If you're using 3.1182 + <command>puttygen</command> on Windows, you can save the 3.1183 + public key to a file of your choosing, or paste it from the 3.1184 + window it's displayed in straight into the <filename 3.1185 + role="special">authorized_keys</filename> file.</para> 3.1186 + </sect2> 3.1187 + <sect2> 3.1188 + <title>Using an authentication agent</title> 3.1189 + 3.1190 + <para id="x_49d">An authentication agent is a daemon that stores 3.1191 + passphrases in memory (so it will forget passphrases if you 3.1192 + log out and log back in again). An ssh client will notice if 3.1193 + it's running, and query it for a passphrase. If there's no 3.1194 + authentication agent running, or the agent doesn't store the 3.1195 + necessary passphrase, you'll have to type your passphrase 3.1196 + every time Mercurial tries to communicate with a server on 3.1197 + your behalf (e.g. whenever you pull or push changes).</para> 3.1198 + 3.1199 + <para id="x_49e">The downside of storing passphrases in an agent is that 3.1200 + it's possible for a well-prepared attacker to recover the 3.1201 + plain text of your passphrases, in some cases even if your 3.1202 + system has been power-cycled. You should make your own 3.1203 + judgment as to whether this is an acceptable risk. It 3.1204 + certainly saves a lot of repeated typing.</para> 3.1205 + 3.1206 + <itemizedlist> 3.1207 + <listitem> 3.1208 + <para id="x_49f">On Unix-like systems, the agent is called 3.1209 + <command>ssh-agent</command>, and it's often run 3.1210 + automatically for you when you log in. You'll need to use 3.1211 + the <command>ssh-add</command> command to add passphrases 3.1212 + to the agent's store.</para> 3.1213 + </listitem> 3.1214 + <listitem> 3.1215 + <para id="x_6a7">On Windows, if you're using TortoiseHg, the 3.1216 + <command>pageant</command> command acts as the agent. As 3.1217 + with <command>puttygen</command>, you'll need to <ulink 3.1218 + url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 3.1219 + <command>pageant</command></ulink> from the PuTTY web 3.1220 + site and read <ulink 3.1221 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 3.1222 + documentation</ulink>. The <command>pageant</command> 3.1223 + command adds an icon to your system tray that will let you 3.1224 + manage stored passphrases.</para> 3.1225 + </listitem> 3.1226 + </itemizedlist> 3.1227 + </sect2> 3.1228 + 3.1229 + <sect2> 3.1230 + <title>Configuring the server side properly</title> 3.1231 + 3.1232 + <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 3.1233 + a variety of things can go wrong. Add Mercurial 3.1234 + on top, and there's plenty more scope for head-scratching. 3.1235 + Most of these potential problems occur on the server side, not 3.1236 + the client side. The good news is that once you've gotten a 3.1237 + configuration working, it will usually continue to work 3.1238 + indefinitely.</para> 3.1239 + 3.1240 + <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 3.1241 + it's best to make sure that you can use the normal 3.1242 + <command>ssh</command> or <command>putty</command> command to 3.1243 + talk to the server first. If you run into problems with using 3.1244 + these commands directly, Mercurial surely won't work. Worse, 3.1245 + it will obscure the underlying problem. Any time you want to 3.1246 + debug ssh-related Mercurial problems, you should drop back to 3.1247 + making sure that plain ssh client commands work first, 3.1248 + <emphasis>before</emphasis> you worry about whether there's a 3.1249 + problem with Mercurial.</para> 3.1250 + 3.1251 + <para id="x_4a2">The first thing to be sure of on the server side is that 3.1252 + you can actually log in from another machine at all. If you 3.1253 + can't use <command>ssh</command> or <command>putty</command> 3.1254 + to log in, the error message you get may give you a few hints 3.1255 + as to what's wrong. The most common problems are as 3.1256 + follows.</para> 3.1257 + <itemizedlist> 3.1258 + <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 3.1259 + error, either there isn't an SSH daemon running on the 3.1260 + server at all, or it's inaccessible due to firewall 3.1261 + configuration.</para> 3.1262 + </listitem> 3.1263 + <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 3.1264 + error, you either have an incorrect address for the server 3.1265 + or a seriously locked down firewall that won't admit its 3.1266 + existence at all.</para> 3.1267 + </listitem> 3.1268 + <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 3.1269 + error, you may have mistyped the username on the server, 3.1270 + or you could have mistyped your key's passphrase or the 3.1271 + remote user's password.</para> 3.1272 + </listitem></itemizedlist> 3.1273 + <para id="x_4a6">In summary, if you're having trouble talking to the 3.1274 + server's ssh daemon, first make sure that one is running at 3.1275 + all. On many systems it will be installed, but disabled, by 3.1276 + default. Once you're done with this step, you should then 3.1277 + check that the server's firewall is configured to allow 3.1278 + incoming connections on the port the ssh daemon is listening 3.1279 + on (usually 22). Don't worry about more exotic possibilities 3.1280 + for misconfiguration until you've checked these two 3.1281 + first.</para> 3.1282 + 3.1283 + <para id="x_4a7">If you're using an authentication agent on the client side 3.1284 + to store passphrases for your keys, you ought to be able to 3.1285 + log into the server without being prompted for a passphrase or 3.1286 + a password. If you're prompted for a passphrase, there are a 3.1287 + few possible culprits.</para> 3.1288 + <itemizedlist> 3.1289 + <listitem><para id="x_4a8">You might have forgotten to use 3.1290 + <command>ssh-add</command> or <command>pageant</command> 3.1291 + to store the passphrase.</para> 3.1292 + </listitem> 3.1293 + <listitem><para id="x_4a9">You might have stored the passphrase for the 3.1294 + wrong key.</para> 3.1295 + </listitem></itemizedlist> 3.1296 + <para id="x_4aa">If you're being prompted for the remote user's password, 3.1297 + there are another few possible problems to check.</para> 3.1298 + <itemizedlist> 3.1299 + <listitem><para id="x_4ab">Either the user's home directory or their 3.1300 + <filename role="special" class="directory">.ssh</filename> 3.1301 + directory might have excessively liberal permissions. As 3.1302 + a result, the ssh daemon will not trust or read their 3.1303 + <filename role="special">authorized_keys</filename> file. 3.1304 + For example, a group-writable home or <filename 3.1305 + role="special" class="directory">.ssh</filename> 3.1306 + directory will often cause this symptom.</para> 3.1307 + </listitem> 3.1308 + <listitem><para id="x_4ac">The user's <filename 3.1309 + role="special">authorized_keys</filename> file may have 3.1310 + a problem. If anyone other than the user owns or can write 3.1311 + to that file, the ssh daemon will not trust or read 3.1312 + it.</para> 3.1313 + </listitem></itemizedlist> 3.1314 + 3.1315 + <para id="x_4ad">In the ideal world, you should be able to run the 3.1316 + following command successfully, and it should print exactly 3.1317 + one line of output, the current date and time.</para> 3.1318 + <programlisting>ssh myserver date</programlisting> 3.1319 + 3.1320 + <para id="x_4ae">If, on your server, you have login scripts that print 3.1321 + banners or other junk even when running non-interactive 3.1322 + commands like this, you should fix them before you continue, 3.1323 + so that they only print output if they're run interactively. 3.1324 + Otherwise these banners will at least clutter up Mercurial's 3.1325 + output. Worse, they could potentially cause problems with 3.1326 + running Mercurial commands remotely. Mercurial tries to 3.1327 + detect and ignore banners in non-interactive 3.1328 + <command>ssh</command> sessions, but it is not foolproof. (If 3.1329 + you're editing your login scripts on your server, the usual 3.1330 + way to see if a login script is running in an interactive 3.1331 + shell is to check the return code from the command 3.1332 + <literal>tty -s</literal>.)</para> 3.1333 + 3.1334 + <para id="x_4af">Once you've verified that plain old ssh is working with 3.1335 + your server, the next step is to ensure that Mercurial runs on 3.1336 + the server. The following command should run 3.1337 + successfully:</para> 3.1338 + 3.1339 + <programlisting>ssh myserver hg version</programlisting> 3.1340 + 3.1341 + <para id="x_4b0">If you see an error message instead of normal <command 3.1342 + role="hg-cmd">hg version</command> output, this is usually 3.1343 + because you haven't installed Mercurial to <filename 3.1344 + class="directory">/usr/bin</filename>. Don't worry if this 3.1345 + is the case; you don't need to do that. But you should check 3.1346 + for a few possible problems.</para> 3.1347 + <itemizedlist> 3.1348 + <listitem><para id="x_4b1">Is Mercurial really installed on the server at 3.1349 + all? I know this sounds trivial, but it's worth 3.1350 + checking!</para> 3.1351 + </listitem> 3.1352 + <listitem><para id="x_4b2">Maybe your shell's search path (usually set 3.1353 + via the <envar>PATH</envar> environment variable) is 3.1354 + simply misconfigured.</para> 3.1355 + </listitem> 3.1356 + <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 3.1357 + variable is only being set to point to the location of the 3.1358 + <command>hg</command> executable if the login session is 3.1359 + interactive. This can happen if you're setting the path 3.1360 + in the wrong shell login script. See your shell's 3.1361 + documentation for details.</para> 3.1362 + </listitem> 3.1363 + <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 3.1364 + variable may need to contain the path to the Mercurial 3.1365 + Python modules. It might not be set at all; it could be 3.1366 + incorrect; or it may be set only if the login is 3.1367 + interactive.</para> 3.1368 + </listitem></itemizedlist> 3.1369 + 3.1370 + <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 3.1371 + over an ssh connection, well done! You've got the server and 3.1372 + client sorted out. You should now be able to use Mercurial to 3.1373 + access repositories hosted by that username on that server. 3.1374 + If you run into problems with Mercurial and ssh at this point, 3.1375 + try using the <option role="hg-opt-global">--debug</option> 3.1376 + option to get a clearer picture of what's going on.</para> 3.1377 + </sect2> 3.1378 + <sect2> 3.1379 + <title>Using compression with ssh</title> 3.1380 + 3.1381 + <para id="x_4b6">Mercurial does not compress data when it uses the ssh 3.1382 + protocol, because the ssh protocol can transparently compress 3.1383 + data. However, the default behavior of ssh clients is 3.1384 + <emphasis>not</emphasis> to request compression.</para> 3.1385 + 3.1386 + <para id="x_4b7">Over any network other than a fast LAN (even a wireless 3.1387 + network), using compression is likely to significantly speed 3.1388 + up Mercurial's network operations. For example, over a WAN, 3.1389 + someone measured compression as reducing the amount of time 3.1390 + required to clone a particularly large repository from 51 3.1391 + minutes to 17 minutes.</para> 3.1392 + 3.1393 + <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 3.1394 + accept a <option role="cmd-opt-ssh">-C</option> option which 3.1395 + turns on compression. You can easily edit your <filename 3.1396 + role="special">~/.hgrc</filename> to enable compression for 3.1397 + all of Mercurial's uses of the ssh protocol. Here is how to 3.1398 + do so for regular <command>ssh</command> on Unix-like systems, 3.1399 + for example.</para> 3.1400 + <programlisting>[ui] 3.1401 +ssh = ssh -C</programlisting> 3.1402 + 3.1403 + <para id="x_4b9">If you use <command>ssh</command> on a 3.1404 + Unix-like system, you can configure it to always use 3.1405 + compression when talking to your server. To do this, edit 3.1406 + your <filename role="special">.ssh/config</filename> file 3.1407 + (which may not yet exist), as follows.</para> 3.1408 + 3.1409 + <programlisting>Host hg 3.1410 + Compression yes 3.1411 + HostName hg.example.com</programlisting> 3.1412 + 3.1413 + <para id="x_4ba">This defines a hostname alias, 3.1414 + <literal>hg</literal>. When you use that hostname on the 3.1415 + <command>ssh</command> command line or in a Mercurial 3.1416 + <literal>ssh</literal>-protocol URL, it will cause 3.1417 + <command>ssh</command> to connect to 3.1418 + <literal>hg.example.com</literal> and use compression. This 3.1419 + gives you both a shorter name to type and compression, each of 3.1420 + which is a good thing in its own right.</para> 3.1421 + </sect2> 3.1422 + </sect1> 3.1423 + 3.1424 + <sect1 id="sec:collab:cgi"> 3.1425 + <title>Serving over HTTP using CGI</title> 3.1426 + 3.1427 + <para id="x_6a8">The simplest way to host one or more repositories in a 3.1428 + permanent way is to use a web server and Mercurial's CGI 3.1429 + support.</para> 3.1430 + 3.1431 + <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 3.1432 + CGI interface can take anything from a few moments to several 3.1433 + hours.</para> 3.1434 + 3.1435 + <para id="x_4bc">We'll begin with the simplest of examples, and work our way 3.1436 + towards a more complex configuration. Even for the most basic 3.1437 + case, you're almost certainly going to need to read and modify 3.1438 + your web server's configuration.</para> 3.1439 + 3.1440 + <note> 3.1441 + <title>High pain tolerance required</title> 3.1442 + 3.1443 + <para id="x_4bd">Configuring a web server is a complex, fiddly, 3.1444 + and highly system-dependent activity. I can't possibly give 3.1445 + you instructions that will cover anything like all of the 3.1446 + cases you will encounter. Please use your discretion and 3.1447 + judgment in following the sections below. Be prepared to make 3.1448 + plenty of mistakes, and to spend a lot of time reading your 3.1449 + server's error logs.</para> 3.1450 + 3.1451 + <para id="x_6a9">If you don't have a strong stomach for tweaking 3.1452 + configurations over and over, or a compelling need to host 3.1453 + your own services, you might want to try one of the public 3.1454 + hosting services that I mentioned earlier.</para> 3.1455 + </note> 3.1456 + 3.1457 + <sect2> 3.1458 + <title>Web server configuration checklist</title> 3.1459 + 3.1460 + <para id="x_4be">Before you continue, do take a few moments to check a few 3.1461 + aspects of your system's setup.</para> 3.1462 + 3.1463 + <orderedlist> 3.1464 + <listitem><para id="x_4bf">Do you have a web server installed 3.1465 + at all? Mac OS X and some Linux distributions ship with 3.1466 + Apache, but many other systems may not have a web server 3.1467 + installed.</para> 3.1468 + </listitem> 3.1469 + <listitem><para id="x_4c0">If you have a web server installed, is it 3.1470 + actually running? On most systems, even if one is 3.1471 + present, it will be disabled by default.</para> 3.1472 + </listitem> 3.1473 + <listitem><para id="x_4c1">Is your server configured to allow you to run 3.1474 + CGI programs in the directory where you plan to do so? 3.1475 + Most servers default to explicitly disabling the ability 3.1476 + to run CGI programs.</para> 3.1477 + </listitem></orderedlist> 3.1478 + 3.1479 + <para id="x_4c2">If you don't have a web server installed, and don't have 3.1480 + substantial experience configuring Apache, you should consider 3.1481 + using the <literal>lighttpd</literal> web server instead of 3.1482 + Apache. Apache has a well-deserved reputation for baroque and 3.1483 + confusing configuration. While <literal>lighttpd</literal> is 3.1484 + less capable in some ways than Apache, most of these 3.1485 + capabilities are not relevant to serving Mercurial 3.1486 + repositories. And <literal>lighttpd</literal> is undeniably 3.1487 + <emphasis>much</emphasis> easier to get started with than 3.1488 + Apache.</para> 3.1489 + </sect2> 3.1490 + 3.1491 + <sect2> 3.1492 + <title>Basic CGI configuration</title> 3.1493 + 3.1494 + <para id="x_4c3">On Unix-like systems, it's common for users to have a 3.1495 + subdirectory named something like <filename 3.1496 + class="directory">public_html</filename> in their home 3.1497 + directory, from which they can serve up web pages. A file 3.1498 + named <filename>foo</filename> in this directory will be 3.1499 + accessible at a URL of the form 3.1500 + <literal>http://www.example.com/username/foo</literal>.</para> 3.1501 + 3.1502 + <para id="x_4c4">To get started, find the <filename 3.1503 + role="special">hgweb.cgi</filename> script that should be 3.1504 + present in your Mercurial installation. If you can't quickly 3.1505 + find a local copy on your system, simply download one from the 3.1506 + master Mercurial repository at <ulink 3.1507 + 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> 3.1508 + 3.1509 + <para id="x_4c5">You'll need to copy this script into your <filename 3.1510 + class="directory">public_html</filename> directory, and 3.1511 + ensure that it's executable.</para> 3.1512 + <programlisting>cp .../hgweb.cgi ~/public_html 3.1513 +chmod 755 ~/public_html/hgweb.cgi</programlisting> 3.1514 + <para id="x_4c6">The <literal>755</literal> argument to 3.1515 + <command>chmod</command> is a little more general than just 3.1516 + making the script executable: it ensures that the script is 3.1517 + executable by anyone, and that <quote>group</quote> and 3.1518 + <quote>other</quote> write permissions are 3.1519 + <emphasis>not</emphasis> set. If you were to leave those 3.1520 + write permissions enabled, Apache's <literal>suexec</literal> 3.1521 + subsystem would likely refuse to execute the script. In fact, 3.1522 + <literal>suexec</literal> also insists that the 3.1523 + <emphasis>directory</emphasis> in which the script resides 3.1524 + must not be writable by others.</para> 3.1525 + <programlisting>chmod 755 ~/public_html</programlisting> 3.1526 + 3.1527 + <sect3 id="sec:collab:wtf"> 3.1528 + <title>What could <emphasis>possibly</emphasis> go 3.1529 + wrong?</title> 3.1530 + 3.1531 + <para id="x_4c7">Once you've copied the CGI script into place, 3.1532 + go into a web browser, and try to open the URL 3.1533 + <literal>http://myhostname/~myuser/hgweb.cgi</literal>, 3.1534 + <emphasis>but</emphasis> brace yourself for instant failure. 3.1535 + There's a high probability that trying to visit this URL 3.1536 + will fail, and there are many possible reasons for this. In 3.1537 + fact, you're likely to stumble over almost every one of the 3.1538 + possible errors below, so please read carefully. The 3.1539 + following are all of the problems I ran into on a system 3.1540 + running Fedora 7, with a fresh installation of Apache, and a 3.1541 + user account that I created specially to perform this 3.1542 + exercise.</para> 3.1543 + 3.1544 + <para id="x_4c8">Your web server may have per-user directories disabled. 3.1545 + If you're using Apache, search your config file for a 3.1546 + <literal>UserDir</literal> directive. If there's none 3.1547 + present, per-user directories will be disabled. If one 3.1548 + exists, but its value is <literal>disabled</literal>, then 3.1549 + per-user directories will be disabled. Otherwise, the 3.1550 + string after <literal>UserDir</literal> gives the name of 3.1551 + the subdirectory that Apache will look in under your home 3.1552 + directory, for example <filename 3.1553 + class="directory">public_html</filename>.</para> 3.1554 + 3.1555 + <para id="x_4c9">Your file access permissions may be too restrictive. 3.1556 + The web server must be able to traverse your home directory 3.1557 + and directories under your <filename 3.1558 + class="directory">public_html</filename> directory, and 3.1559 + read files under the latter too. Here's a quick recipe to 3.1560 + help you to make your permissions more appropriate.</para> 3.1561 + <programlisting>chmod 755 ~ 3.1562 +find ~/public_html -type d -print0 | xargs -0r chmod 755 3.1563 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 3.1564 + 3.1565 + <para id="x_4ca">The other possibility with permissions is that you might 3.1566 + get a completely empty window when you try to load the 3.1567 + script. In this case, it's likely that your access 3.1568 + permissions are <emphasis>too permissive</emphasis>. Apache's 3.1569 + <literal>suexec</literal> subsystem won't execute a script 3.1570 + that's group- or world-writable, for example.</para> 3.1571 + 3.1572 + <para id="x_4cb">Your web server may be configured to disallow execution 3.1573 + of CGI programs in your per-user web directory. Here's 3.1574 + Apache's default per-user configuration from my Fedora 3.1575 + system.</para> 3.1576 + 3.1577 + &ch06-apache-config.lst; 3.1578 + 3.1579 + <para id="x_4cc">If you find a similar-looking 3.1580 + <literal>Directory</literal> group in your Apache 3.1581 + configuration, the directive to look at inside it is 3.1582 + <literal>Options</literal>. Add <literal>ExecCGI</literal> 3.1583 + to the end of this list if it's missing, and restart the web 3.1584 + server.</para> 3.1585 + 3.1586 + <para id="x_4cd">If you find that Apache serves you the text of the CGI 3.1587 + script instead of executing it, you may need to either 3.1588 + uncomment (if already present) or add a directive like 3.1589 + this.</para> 3.1590 + <programlisting>AddHandler cgi-script .cgi</programlisting> 3.1591 + 3.1592 + <para id="x_4ce">The next possibility is that you might be served with a 3.1593 + colourful Python backtrace claiming that it can't import a 3.1594 + <literal>mercurial</literal>-related module. This is 3.1595 + actually progress! The server is now capable of executing 3.1596 + your CGI script. This error is only likely to occur if 3.1597 + you're running a private installation of Mercurial, instead 3.1598 + of a system-wide version. Remember that the web server runs 3.1599 + the CGI program without any of the environment variables 3.1600 + that you take for granted in an interactive session. If 3.1601 + this error happens to you, edit your copy of <filename 3.1602 + role="special">hgweb.cgi</filename> and follow the 3.1603 + directions inside it to correctly set your 3.1604 + <envar>PYTHONPATH</envar> environment variable.</para> 3.1605 + 3.1606 + <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be 3.1607 + served with another colourful Python backtrace: this one 3.1608 + will complain that it can't find <filename 3.1609 + class="directory">/path/to/repository</filename>. Edit 3.1610 + your <filename role="special">hgweb.cgi</filename> script 3.1611 + and replace the <filename 3.1612 + class="directory">/path/to/repository</filename> string 3.1613 + with the complete path to the repository you want to serve 3.1614 + up.</para> 3.1615 + 3.1616 + <para id="x_4d0">At this point, when you try to reload the page, you 3.1617 + should be presented with a nice HTML view of your 3.1618 + repository's history. Whew!</para> 3.1619 + </sect3> 3.1620 + 3.1621 + <sect3> 3.1622 + <title>Configuring lighttpd</title> 3.1623 + 3.1624 + <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 3.1625 + the increasingly popular <literal>lighttpd</literal> web 3.1626 + server to serve the same repository as I described with 3.1627 + Apache above. I had already overcome all of the problems I 3.1628 + outlined with Apache, many of which are not server-specific. 3.1629 + As a result, I was fairly sure that my file and directory 3.1630 + permissions were good, and that my <filename 3.1631 + role="special">hgweb.cgi</filename> script was properly 3.1632 + edited.</para> 3.1633 + 3.1634 + <para id="x_4d2">Once I had Apache running, getting 3.1635 + <literal>lighttpd</literal> to serve the repository was a 3.1636 + snap (in other words, even if you're trying to use 3.1637 + <literal>lighttpd</literal>, you should read the Apache 3.1638 + section). I first had to edit the 3.1639 + <literal>mod_access</literal> section of its config file to 3.1640 + enable <literal>mod_cgi</literal> and 3.1641 + <literal>mod_userdir</literal>, both of which were disabled 3.1642 + by default on my system. I then added a few lines to the 3.1643 + end of the config file, to configure these modules.</para> 3.1644 + <programlisting>userdir.path = "public_html" 3.1645 +cgi.assign = (".cgi" => "" )</programlisting> 3.1646 + <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 3.1647 + immediately for me. If I had configured 3.1648 + <literal>lighttpd</literal> before Apache, I'd almost 3.1649 + certainly have run into many of the same system-level 3.1650 + configuration problems as I did with Apache. However, I 3.1651 + found <literal>lighttpd</literal> to be noticeably easier to 3.1652 + configure than Apache, even though I've used Apache for over 3.1653 + a decade, and this was my first exposure to 3.1654 + <literal>lighttpd</literal>.</para> 3.1655 + </sect3> 3.1656 + </sect2> 3.1657 + 3.1658 + <sect2> 3.1659 + <title>Sharing multiple repositories with one CGI script</title> 3.1660 + 3.1661 + <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 3.1662 + only lets you publish a single repository, which is an 3.1663 + annoying restriction. If you want to publish more than one 3.1664 + without wracking yourself with multiple copies of the same 3.1665 + script, each with different names, a better choice is to use 3.1666 + the <filename role="special">hgwebdir.cgi</filename> 3.1667 + script.</para> 3.1668 + 3.1669 + <para id="x_4d5">The procedure to configure <filename 3.1670 + role="special">hgwebdir.cgi</filename> is only a little more 3.1671 + involved than for <filename 3.1672 + role="special">hgweb.cgi</filename>. First, you must obtain 3.1673 + a copy of the script. If you don't have one handy, you can 3.1674 + download a copy from the master Mercurial repository at <ulink 3.1675 + 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> 3.1676 + 3.1677 + <para id="x_4d6">You'll need to copy this script into your <filename 3.1678 + class="directory">public_html</filename> directory, and 3.1679 + ensure that it's executable.</para> 3.1680 + 3.1681 + <programlisting>cp .../hgwebdir.cgi ~/public_html 3.1682 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 3.1683 + 3.1684 + <para id="x_4d7">With basic configuration out of the way, try to 3.1685 + visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal> 3.1686 + in your browser. It should 3.1687 + display an empty list of repositories. If you get a blank 3.1688 + window or error message, try walking through the list of 3.1689 + potential problems in <xref 3.1690 + linkend="sec:collab:wtf"/>.</para> 3.1691 + 3.1692 + <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 3.1693 + script relies on an external configuration file. By default, 3.1694 + it searches for a file named <filename 3.1695 + role="special">hgweb.config</filename> in the same directory 3.1696 + as itself. You'll need to create this file, and make it 3.1697 + world-readable. The format of the file is similar to a 3.1698 + Windows <quote>ini</quote> file, as understood by Python's 3.1699 + <literal>ConfigParser</literal> 3.1700 + <citation>web:configparser</citation> module.</para> 3.1701 + 3.1702 + <para id="x_4d9">The easiest way to configure <filename 3.1703 + role="special">hgwebdir.cgi</filename> is with a section 3.1704 + named <literal>collections</literal>. This will automatically 3.1705 + publish <emphasis>every</emphasis> repository under the 3.1706 + directories you name. The section should look like 3.1707 + this:</para> 3.1708 + <programlisting>[collections] 3.1709 +/my/root = /my/root</programlisting> 3.1710 + <para id="x_4da">Mercurial interprets this by looking at the directory name 3.1711 + on the <emphasis>right</emphasis> hand side of the 3.1712 + <quote><literal>=</literal></quote> sign; finding repositories 3.1713 + in that directory hierarchy; and using the text on the 3.1714 + <emphasis>left</emphasis> to strip off matching text from the 3.1715 + names it will actually list in the web interface. The 3.1716 + remaining component of a path after this stripping has 3.1717 + occurred is called a <quote>virtual path</quote>.</para> 3.1718 + 3.1719 + <para id="x_4db">Given the example above, if we have a 3.1720 + repository whose local path is <filename 3.1721 + class="directory">/my/root/this/repo</filename>, the CGI 3.1722 + script will strip the leading <filename 3.1723 + class="directory">/my/root</filename> from the name, and 3.1724 + publish the repository with a virtual path of <filename 3.1725 + class="directory">this/repo</filename>. If the base URL for 3.1726 + our CGI script is 3.1727 + <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the 3.1728 + complete URL for that repository will be 3.1729 + <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para> 3.1730 + 3.1731 + <para id="x_4dc">If we replace <filename 3.1732 + class="directory">/my/root</filename> on the left hand side 3.1733 + of this example with <filename 3.1734 + class="directory">/my</filename>, then <filename 3.1735 + role="special">hgwebdir.cgi</filename> will only strip off 3.1736 + <filename class="directory">/my</filename> from the repository 3.1737 + name, and will give us a virtual path of <filename 3.1738 + class="directory">root/this/repo</filename> instead of 3.1739 + <filename class="directory">this/repo</filename>.</para> 3.1740 + 3.1741 + <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 3.1742 + script will recursively search each directory listed in the 3.1743 + <literal>collections</literal> section of its configuration 3.1744 + file, but it will <literal>not</literal> recurse into the 3.1745 + repositories it finds.</para> 3.1746 + 3.1747 + <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 3.1748 + to publish many repositories in a <quote>fire and 3.1749 + forget</quote> manner. You only need to set up the CGI 3.1750 + script and configuration file one time. Afterwards, you can 3.1751 + publish or unpublish a repository at any time by simply moving 3.1752 + it into, or out of, the directory hierarchy in which you've 3.1753 + configured <filename role="special">hgwebdir.cgi</filename> to 3.1754 + look.</para> 3.1755 + 3.1756 + <sect3> 3.1757 + <title>Explicitly specifying which repositories to 3.1758 + publish</title> 3.1759 + 3.1760 + <para id="x_4df">In addition to the <literal>collections</literal> 3.1761 + mechanism, the <filename 3.1762 + role="special">hgwebdir.cgi</filename> script allows you 3.1763 + to publish a specific list of repositories. To do so, 3.1764 + create a <literal>paths</literal> section, with contents of 3.1765 + the following form.</para> 3.1766 + <programlisting>[paths] 3.1767 +repo1 = /my/path/to/some/repo 3.1768 +repo2 = /some/path/to/another</programlisting> 3.1769 + <para id="x_4e0">In this case, the virtual path (the component that will 3.1770 + appear in a URL) is on the left hand side of each 3.1771 + definition, while the path to the repository is on the 3.1772 + right. Notice that there does not need to be any 3.1773 + relationship between the virtual path you choose and the 3.1774 + location of a repository in your filesystem.</para> 3.1775 + 3.1776 + <para id="x_4e1">If you wish, you can use both the 3.1777 + <literal>collections</literal> and <literal>paths</literal> 3.1778 + mechanisms simultaneously in a single configuration 3.1779 + file.</para> 3.1780 + 3.1781 + <note> 3.1782 + <title>Beware duplicate virtual paths</title> 3.1783 + 3.1784 + <para id="x_4e2"> If several repositories have the same 3.1785 + virtual path, <filename 3.1786 + role="special">hgwebdir.cgi</filename> will not report 3.1787 + an error. Instead, it will behave unpredictably.</para> 3.1788 + </note> 3.1789 + </sect3> 3.1790 + </sect2> 3.1791 + 3.1792 + <sect2> 3.1793 + <title>Downloading source archives</title> 3.1794 + 3.1795 + <para id="x_4e3">Mercurial's web interface lets users download an archive 3.1796 + of any revision. This archive will contain a snapshot of the 3.1797 + working directory as of that revision, but it will not contain 3.1798 + a copy of the repository data.</para> 3.1799 + 3.1800 + <para id="x_4e4">By default, this feature is not enabled. To enable it, 3.1801 + you'll need to add an <envar 3.1802 + role="rc-item-web">allow_archive</envar> item to the 3.1803 + <literal role="rc-web">web</literal> section of your <filename 3.1804 + role="special">~/.hgrc</filename>; see below for details.</para> 3.1805 + </sect2> 3.1806 + <sect2> 3.1807 + <title>Web configuration options</title> 3.1808 + 3.1809 + <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 3.1810 + serve</command> command, and the <filename 3.1811 + role="special">hgweb.cgi</filename> and <filename 3.1812 + role="special">hgwebdir.cgi</filename> scripts) have a 3.1813 + number of configuration options that you can set. These 3.1814 + belong in a section named <literal 3.1815 + role="rc-web">web</literal>.</para> 3.1816 + <itemizedlist> 3.1817 + <listitem><para id="x_4e6"><envar 3.1818 + role="rc-item-web">allow_archive</envar>: Determines 3.1819 + which (if any) archive download mechanisms Mercurial 3.1820 + supports. If you enable this feature, users of the web 3.1821 + interface will be able to download an archive of whatever 3.1822 + revision of a repository they are viewing. To enable the 3.1823 + archive feature, this item must take the form of a 3.1824 + sequence of words drawn from the list below.</para> 3.1825 + <itemizedlist> 3.1826 + <listitem><para id="x_4e7"><literal>bz2</literal>: A 3.1827 + <command>tar</command> archive, compressed using 3.1828 + <literal>bzip2</literal> compression. This has the 3.1829 + best compression ratio, but uses the most CPU time on 3.1830 + the server.</para> 3.1831 + </listitem> 3.1832 + <listitem><para id="x_4e8"><literal>gz</literal>: A 3.1833 + <command>tar</command> archive, compressed using 3.1834 + <literal>gzip</literal> compression.</para> 3.1835 + </listitem> 3.1836 + <listitem><para id="x_4e9"><literal>zip</literal>: A 3.1837 + <command>zip</command> archive, compressed using LZW 3.1838 + compression. This format has the worst compression 3.1839 + ratio, but is widely used in the Windows world.</para> 3.1840 + </listitem> 3.1841 + </itemizedlist> 3.1842 + <para id="x_4ea"> If you provide an empty list, or don't have an 3.1843 + <envar role="rc-item-web">allow_archive</envar> entry at 3.1844 + all, this feature will be disabled. Here is an example of 3.1845 + how to enable all three supported formats.</para> 3.1846 + <programlisting>[web] 3.1847 +allow_archive = bz2 gz zip</programlisting> 3.1848 + </listitem> 3.1849 + <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 3.1850 + Boolean. Determines whether the web interface allows 3.1851 + remote users to <command role="hg-cmd">hg pull</command> 3.1852 + and <command role="hg-cmd">hg clone</command> this 3.1853 + repository over HTTP. If set to <literal>no</literal> or 3.1854 + <literal>false</literal>, only the 3.1855 + <quote>human-oriented</quote> portion of the web interface 3.1856 + is available.</para> 3.1857 + </listitem> 3.1858 + <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 3.1859 + String. A free-form (but preferably brief) string 3.1860 + identifying the person or group in charge of the 3.1861 + repository. This often contains the name and email 3.1862 + address of a person or mailing list. It often makes sense 3.1863 + to place this entry in a repository's own <filename 3.1864 + role="special">.hg/hgrc</filename> file, but it can make 3.1865 + sense to use in a global <filename 3.1866 + role="special">~/.hgrc</filename> if every repository 3.1867 + has a single maintainer.</para> 3.1868 + </listitem> 3.1869 + <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 3.1870 + Integer. The default maximum number of changesets to 3.1871 + display in a single page of output.</para> 3.1872 + </listitem> 3.1873 + <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 3.1874 + Integer. The default maximum number of modified files to 3.1875 + display in a single page of output.</para> 3.1876 + </listitem> 3.1877 + <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 3.1878 + Integer. If the web interface displays alternating 3.1879 + <quote>stripes</quote> to make it easier to visually align 3.1880 + rows when you are looking at a table, this number controls 3.1881 + the number of rows in each stripe.</para> 3.1882 + </listitem> 3.1883 + <listitem><para id="x_4f0"><envar 3.1884 + role="rc-item-web">style</envar>: Controls the template 3.1885 + Mercurial uses to display the web interface. Mercurial 3.1886 + ships with several web templates.</para> 3.1887 + <itemizedlist> 3.1888 + <listitem> 3.1889 + <para id="x_6aa"><literal>coal</literal> is monochromatic.</para> 3.1890 + </listitem> 3.1891 + <listitem> 3.1892 + <para id="x_6ab"><literal>gitweb</literal> emulates the visual 3.1893 + style of git's web interface.</para> 3.1894 + </listitem> 3.1895 + <listitem> 3.1896 + <para id="x_6ac"><literal>monoblue</literal> uses solid blues and 3.1897 + greys.</para> 3.1898 + </listitem> 3.1899 + <listitem> 3.1900 + <para id="x_6ad"><literal>paper</literal> is the default.</para> 3.1901 + </listitem> 3.1902 + <listitem> 3.1903 + <para id="x_6ae"><literal>spartan</literal> was the default for a 3.1904 + long time.</para> 3.1905 + </listitem> 3.1906 + </itemizedlist> 3.1907 + <para id="x_6af">You can 3.1908 + also specify a custom template of your own; see 3.1909 + <xref linkend="chap:template"/> for details. Here, you can 3.1910 + see how to enable the <literal>gitweb</literal> 3.1911 + style.</para> 3.1912 + <programlisting>[web] 3.1913 +style = gitweb</programlisting> 3.1914 + </listitem> 3.1915 + <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 3.1916 + Path. The directory in which to search for template 3.1917 + files. By default, Mercurial searches in the directory in 3.1918 + which it was installed.</para> 3.1919 + </listitem></itemizedlist> 3.1920 + <para id="x_4f2">If you are using <filename 3.1921 + role="special">hgwebdir.cgi</filename>, you can place a few 3.1922 + configuration items in a <literal role="rc-web">web</literal> 3.1923 + section of the <filename 3.1924 + role="special">hgweb.config</filename> file instead of a 3.1925 + <filename role="special">~/.hgrc</filename> file, for 3.1926 + convenience. These items are <envar 3.1927 + role="rc-item-web">motd</envar> and <envar 3.1928 + role="rc-item-web">style</envar>.</para> 3.1929 + 3.1930 + <sect3> 3.1931 + <title>Options specific to an individual repository</title> 3.1932 + 3.1933 + <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 3.1934 + items ought to be placed in a repository's local <filename 3.1935 + role="special">.hg/hgrc</filename>, rather than a user's 3.1936 + or global <filename role="special">~/.hgrc</filename>.</para> 3.1937 + <itemizedlist> 3.1938 + <listitem><para id="x_4f4"><envar 3.1939 + role="rc-item-web">description</envar>: String. A 3.1940 + free-form (but preferably brief) string that describes 3.1941 + the contents or purpose of the repository.</para> 3.1942 + </listitem> 3.1943 + <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 3.1944 + String. The name to use for the repository in the web 3.1945 + interface. This overrides the default name, which is 3.1946 + the last component of the repository's path.</para> 3.1947 + </listitem></itemizedlist> 3.1948 + </sect3> 3.1949 + 3.1950 + <sect3> 3.1951 + <title>Options specific to the <command role="hg-cmd">hg 3.1952 + serve</command> command</title> 3.1953 + 3.1954 + <para id="x_4f6">Some of the items in the <literal 3.1955 + role="rc-web">web</literal> section of a <filename 3.1956 + role="special">~/.hgrc</filename> file are only for use 3.1957 + with the <command role="hg-cmd">hg serve</command> 3.1958 + command.</para> 3.1959 + <itemizedlist> 3.1960 + <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 3.1961 + Path. The name of a file into which to write an access 3.1962 + log. By default, the <command role="hg-cmd">hg 3.1963 + serve</command> command writes this information to 3.1964 + standard output, not to a file. Log entries are written 3.1965 + in the standard <quote>combined</quote> file format used 3.1966 + by almost all web servers.</para> 3.1967 + </listitem> 3.1968 + <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 3.1969 + String. The local address on which the server should 3.1970 + listen for incoming connections. By default, the server 3.1971 + listens on all addresses.</para> 3.1972 + </listitem> 3.1973 + <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 3.1974 + Path. The name of a file into which to write an error 3.1975 + log. By default, the <command role="hg-cmd">hg 3.1976 + serve</command> command writes this information to 3.1977 + standard error, not to a file.</para> 3.1978 + </listitem> 3.1979 + <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 3.1980 + Boolean. Whether to use the IPv6 protocol. By default, 3.1981 + IPv6 is not used.</para> 3.1982 + </listitem> 3.1983 + <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 3.1984 + Integer. The TCP port number on which the server should 3.1985 + listen. The default port number used is 8000.</para> 3.1986 + </listitem></itemizedlist> 3.1987 + </sect3> 3.1988 + 3.1989 + <sect3> 3.1990 + <title>Choosing the right <filename 3.1991 + role="special">~/.hgrc</filename> file to add <literal 3.1992 + role="rc-web">web</literal> items to</title> 3.1993 + 3.1994 + <para id="x_4fc">It is important to remember that a web server like 3.1995 + Apache or <literal>lighttpd</literal> will run under a user 3.1996 + ID that is different to yours. CGI scripts run by your 3.1997 + server, such as <filename 3.1998 + role="special">hgweb.cgi</filename>, will usually also run 3.1999 + under that user ID.</para> 3.2000 + 3.2001 + <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 3.2002 + your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 3.2003 + <filename role="special">~/.hgrc</filename> file. Those 3.2004 + settings will thus only affect the behavior of the <command 3.2005 + role="hg-cmd">hg serve</command> command when you run it. 3.2006 + To cause CGI scripts to see your settings, either create a 3.2007 + <filename role="special">~/.hgrc</filename> file in the 3.2008 + home directory of the user ID that runs your web server, or 3.2009 + add those settings to a system-wide <filename 3.2010 + role="special">hgrc</filename> file.</para> 3.2011 + </sect3> 3.2012 + </sect2> 3.2013 + </sect1> 3.2014 + 3.2015 + <sect1> 3.2016 + <title>System-wide configuration</title> 3.2017 + 3.2018 + <para id="x_6b0">On Unix-like systems shared by multiple users (such as a 3.2019 + server to which people publish changes), it often makes sense to 3.2020 + set up some global default behaviors, such as what theme to use 3.2021 + in web interfaces.</para> 3.2022 + 3.2023 + <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename> 3.2024 + exists, Mercurial will read it at startup time and apply any 3.2025 + configuration settings it finds in that file. It will also look 3.2026 + for files ending in a <literal>.rc</literal> extension in a 3.2027 + directory named <filename>/etc/mercurial/hgrc.d</filename>, and 3.2028 + apply any configuration settings it finds in each of those 3.2029 + files.</para> 3.2030 + 3.2031 + <sect2> 3.2032 + <title>Making Mercurial more trusting</title> 3.2033 + 3.2034 + <para id="x_6b2">One situation in which a global <filename>hgrc</filename> 3.2035 + can be useful is if users are pulling changes owned by other 3.2036 + users. By default, Mercurial will not trust most of the 3.2037 + configuration items in a <filename>.hg/hgrc</filename> file 3.2038 + inside a repository that is owned by a different user. If we 3.2039 + clone or pull changes from such a repository, Mercurial will 3.2040 + print a warning stating that it does not trust their 3.2041 + <filename>.hg/hgrc</filename>.</para> 3.2042 + 3.2043 + <para id="x_6b3">If everyone in a particular Unix group is on the same team 3.2044 + and <emphasis>should</emphasis> trust each other's 3.2045 + configuration settings, or we want to trust particular users, 3.2046 + we can override Mercurial's skeptical defaults by creating a 3.2047 + system-wide <filename>hgrc</filename> file such as the 3.2048 + following:</para> 3.2049 + 3.2050 + <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc 3.2051 +[trusted] 3.2052 +# Trust all entries in any hgrc file owned by the "editors" or 3.2053 +# "www-data" groups. 3.2054 +groups = editors, www-data 3.2055 + 3.2056 +# Trust entries in hgrc files owned by the following users. 3.2057 +users = apache, bobo 3.2058 </programlisting> 3.2059 -<orderedlist> 3.2060 -<listitem><para>The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the ssh 3.2061 - protocol. 3.2062 -</para> 3.2063 -</listitem> 3.2064 -<listitem><para>The <quote><literal>bos@</literal></quote> component indicates what username to log 3.2065 - into the server as. You can leave this out if the remote username 3.2066 - is the same as your local username. 3.2067 -</para> 3.2068 -</listitem> 3.2069 -<listitem><para>The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of the 3.2070 - server to log into. 3.2071 -</para> 3.2072 -</listitem> 3.2073 -<listitem><para>The <quote>:22</quote> identifies the port number to connect to the server 3.2074 - on. The default port is 22, so you only need to specify this part 3.2075 - if you're <emphasis>not</emphasis> using port 22. 3.2076 -</para> 3.2077 -</listitem> 3.2078 -<listitem><para>The remainder of the URL is the local path to the repository on 3.2079 - the server. 3.2080 -</para> 3.2081 -</listitem></orderedlist> 3.2082 - 3.2083 -<para>There's plenty of scope for confusion with the path component of ssh 3.2084 -URLs, as there is no standard way for tools to interpret it. Some 3.2085 -programs behave differently than others when dealing with these paths. 3.2086 -This isn't an ideal situation, but it's unlikely to change. Please 3.2087 -read the following paragraphs carefully. 3.2088 -</para> 3.2089 - 3.2090 -<para>Mercurial treats the path to a repository on the server as relative to 3.2091 -the remote user's home directory. For example, if user <literal>foo</literal> 3.2092 -on the server has a home directory of <filename class="directory">/home/foo</filename>, then an ssh 3.2093 -URL that contains a path component of <filename class="directory">bar</filename> 3.2094 -<emphasis>really</emphasis> refers to the directory <filename class="directory">/home/foo/bar</filename>. 3.2095 -</para> 3.2096 - 3.2097 -<para>If you want to specify a path relative to another user's home 3.2098 -directory, you can use a path that starts with a tilde character 3.2099 -followed by the user's name (let's call them <literal>otheruser</literal>), like 3.2100 -this. 3.2101 -</para> 3.2102 -<programlisting> 3.2103 -<para> ssh://server/ otheruser/hg/repo 3.2104 -</para> 3.2105 -</programlisting> 3.2106 - 3.2107 -<para>And if you really want to specify an <emphasis>absolute</emphasis> path on the 3.2108 -server, begin the path component with two slashes, as in this example. 3.2109 -</para> 3.2110 -<programlisting> 3.2111 -<para> ssh://server//absolute/path 3.2112 -</para> 3.2113 -</programlisting> 3.2114 - 3.2115 -</sect2> 3.2116 -<sect2> 3.2117 -<title>Finding an ssh client for your system</title> 3.2118 - 3.2119 -<para>Almost every Unix-like system comes with OpenSSH preinstalled. If 3.2120 -you're using such a system, run <literal>which ssh</literal> to find out if 3.2121 -the <command>ssh</command> command is installed (it's usually in 3.2122 -<filename class="directory">/usr/bin</filename>). In the unlikely event that it isn't present, 3.2123 -take a look at your system documentation to figure out how to install 3.2124 -it. 3.2125 -</para> 3.2126 - 3.2127 -<para>On Windows, you'll first need to download a suitable ssh 3.2128 -client. There are two alternatives. 3.2129 -</para> 3.2130 -<itemizedlist> 3.2131 -<listitem><para>Simon Tatham's excellent PuTTY package <citation>web:putty</citation> provides 3.2132 - a complete suite of ssh client commands. 3.2133 -</para> 3.2134 -</listitem> 3.2135 -<listitem><para>If you have a high tolerance for pain, you can use the Cygwin 3.2136 - port of OpenSSH. 3.2137 -</para> 3.2138 -</listitem></itemizedlist> 3.2139 -<para>In either case, you'll need to edit your \hgini\ file to tell 3.2140 -Mercurial where to find the actual client command. For example, if 3.2141 -you're using PuTTY, you'll need to use the <command>plink</command> command as 3.2142 -a command-line ssh client. 3.2143 -</para> 3.2144 -<programlisting> 3.2145 -<para> [ui] 3.2146 - ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" 3.2147 -</para> 3.2148 -</programlisting> 3.2149 - 3.2150 -<note> 3.2151 -<para> The path to <command>plink</command> shouldn't contain any whitespace 3.2152 - characters, or Mercurial may not be able to run it correctly (so 3.2153 - putting it in <filename class="directory">C:\\Program Files</filename> is probably not a good 3.2154 - idea). 3.2155 -</para> 3.2156 -</note> 3.2157 - 3.2158 -</sect2> 3.2159 -<sect2> 3.2160 -<title>Generating a key pair</title> 3.2161 - 3.2162 -<para>To avoid the need to repetitively type a password every time you need 3.2163 -to use your ssh client, I recommend generating a key pair. On a 3.2164 -Unix-like system, the <command>ssh-keygen</command> command will do the trick. 3.2165 -On Windows, if you're using PuTTY, the <command>puttygen</command> command is 3.2166 -what you'll need. 3.2167 -</para> 3.2168 - 3.2169 -<para>When you generate a key pair, it's usually <emphasis>highly</emphasis> advisable to 3.2170 -protect it with a passphrase. (The only time that you might not want 3.2171 -to do this is when you're using the ssh protocol for automated tasks 3.2172 -on a secure network.) 3.2173 -</para> 3.2174 - 3.2175 -<para>Simply generating a key pair isn't enough, however. You'll need to 3.2176 -add the public key to the set of authorised keys for whatever user 3.2177 -you're logging in remotely as. For servers using OpenSSH (the vast 3.2178 -majority), this will mean adding the public key to a list in a file 3.2179 -called <filename role="special">authorized_keys</filename> in their <filename role="special" class="directory">.ssh</filename> 3.2180 -directory. 3.2181 -</para> 3.2182 - 3.2183 -<para>On a Unix-like system, your public key will have a <filename>.pub</filename> 3.2184 -extension. If you're using <command>puttygen</command> on Windows, you can 3.2185 -save the public key to a file of your choosing, or paste it from the 3.2186 -window it's displayed in straight into the 3.2187 -<filename role="special">authorized_keys</filename> file. 3.2188 -</para> 3.2189 - 3.2190 -</sect2> 3.2191 -<sect2> 3.2192 -<title>Using an authentication agent</title> 3.2193 - 3.2194 -<para>An authentication agent is a daemon that stores passphrases in memory 3.2195 -(so it will forget passphrases if you log out and log back in again). 3.2196 -An ssh client will notice if it's running, and query it for a 3.2197 -passphrase. If there's no authentication agent running, or the agent 3.2198 -doesn't store the necessary passphrase, you'll have to type your 3.2199 -passphrase every time Mercurial tries to communicate with a server on 3.2200 -your behalf (e.g. whenever you pull or push changes). 3.2201 -</para> 3.2202 - 3.2203 -<para>The downside of storing passphrases in an agent is that it's possible 3.2204 -for a well-prepared attacker to recover the plain text of your 3.2205 -passphrases, in some cases even if your system has been power-cycled. 3.2206 -You should make your own judgment as to whether this is an acceptable 3.2207 -risk. It certainly saves a lot of repeated typing. 3.2208 -</para> 3.2209 - 3.2210 -<para>On Unix-like systems, the agent is called <command>ssh-agent</command>, and 3.2211 -it's often run automatically for you when you log in. You'll need to 3.2212 -use the <command>ssh-add</command> command to add passphrases to the agent's 3.2213 -store. On Windows, if you're using PuTTY, the <command>pageant</command> 3.2214 -command acts as the agent. It adds an icon to your system tray that 3.2215 -will let you manage stored passphrases. 3.2216 -</para> 3.2217 - 3.2218 -</sect2> 3.2219 -<sect2> 3.2220 -<title>Configuring the server side properly</title> 3.2221 - 3.2222 -<para>Because ssh can be fiddly to set up if you're new to it, there's a 3.2223 -variety of things that can go wrong. Add Mercurial on top, and 3.2224 -there's plenty more scope for head-scratching. Most of these 3.2225 -potential problems occur on the server side, not the client side. The 3.2226 -good news is that once you've gotten a configuration working, it will 3.2227 -usually continue to work indefinitely. 3.2228 -</para> 3.2229 - 3.2230 -<para>Before you try using Mercurial to talk to an ssh server, it's best to 3.2231 -make sure that you can use the normal <command>ssh</command> or <command>putty</command> 3.2232 -command to talk to the server first. If you run into problems with 3.2233 -using these commands directly, Mercurial surely won't work. Worse, it 3.2234 -will obscure the underlying problem. Any time you want to debug 3.2235 -ssh-related Mercurial problems, you should drop back to making sure 3.2236 -that plain ssh client commands work first, <emphasis>before</emphasis> you worry 3.2237 -about whether there's a problem with Mercurial. 3.2238 -</para> 3.2239 - 3.2240 -<para>The first thing to be sure of on the server side is that you can 3.2241 -actually log in from another machine at all. If you can't use 3.2242 -<command>ssh</command> or <command>putty</command> to log in, the error message you get 3.2243 -may give you a few hints as to what's wrong. The most common problems 3.2244 -are as follows. 3.2245 -</para> 3.2246 -<itemizedlist> 3.2247 -<listitem><para>If you get a <quote>connection refused</quote> error, either there isn't an 3.2248 - SSH daemon running on the server at all, or it's inaccessible due to 3.2249 - firewall configuration. 3.2250 -</para> 3.2251 -</listitem> 3.2252 -<listitem><para>If you get a <quote>no route to host</quote> error, you either have an 3.2253 - incorrect address for the server or a seriously locked down firewall 3.2254 - that won't admit its existence at all. 3.2255 -</para> 3.2256 -</listitem> 3.2257 -<listitem><para>If you get a <quote>permission denied</quote> error, you may have mistyped 3.2258 - the username on the server, or you could have mistyped your key's 3.2259 - passphrase or the remote user's password. 3.2260 -</para> 3.2261 -</listitem></itemizedlist> 3.2262 -<para>In summary, if you're having trouble talking to the server's ssh 3.2263 -daemon, first make sure that one is running at all. On many systems 3.2264 -it will be installed, but disabled, by default. Once you're done with 3.2265 -this step, you should then check that the server's firewall is 3.2266 -configured to allow incoming connections on the port the ssh daemon is 3.2267 -listening on (usually 22). Don't worry about more exotic 3.2268 -possibilities for misconfiguration until you've checked these two 3.2269 -first. 3.2270 -</para> 3.2271 - 3.2272 -<para>If you're using an authentication agent on the client side to store 3.2273 -passphrases for your keys, you ought to be able to log into the server 3.2274 -without being prompted for a passphrase or a password. If you're 3.2275 -prompted for a passphrase, there are a few possible culprits. 3.2276 -</para> 3.2277 -<itemizedlist> 3.2278 -<listitem><para>You might have forgotten to use <command>ssh-add</command> or 3.2279 - <command>pageant</command> to store the passphrase. 3.2280 -</para> 3.2281 -</listitem> 3.2282 -<listitem><para>You might have stored the passphrase for the wrong key. 3.2283 -</para> 3.2284 -</listitem></itemizedlist> 3.2285 -<para>If you're being prompted for the remote user's password, there are 3.2286 -another few possible problems to check. 3.2287 -</para> 3.2288 -<itemizedlist> 3.2289 -<listitem><para>Either the user's home directory or their <filename role="special" class="directory">.ssh</filename> 3.2290 - directory might have excessively liberal permissions. As a result, 3.2291 - the ssh daemon will not trust or read their 3.2292 - <filename role="special">authorized_keys</filename> file. For example, a group-writable 3.2293 - home or <filename role="special" class="directory">.ssh</filename> directory will often cause this symptom. 3.2294 -</para> 3.2295 -</listitem> 3.2296 -<listitem><para>The user's <filename role="special">authorized_keys</filename> file may have a problem. 3.2297 - If anyone other than the user owns or can write to that file, the 3.2298 - ssh daemon will not trust or read it. 3.2299 -</para> 3.2300 -</listitem></itemizedlist> 3.2301 - 3.2302 -<para>In the ideal world, you should be able to run the following command 3.2303 -successfully, and it should print exactly one line of output, the 3.2304 -current date and time. 3.2305 -</para> 3.2306 -<programlisting> 3.2307 -<para> ssh myserver date 3.2308 -</para> 3.2309 -</programlisting> 3.2310 - 3.2311 -<para>If, on your server, you have login scripts that print banners or other 3.2312 -junk even when running non-interactive commands like this, you should 3.2313 -fix them before you continue, so that they only print output if 3.2314 -they're run interactively. Otherwise these banners will at least 3.2315 -clutter up Mercurial's output. Worse, they could potentially cause 3.2316 -problems with running Mercurial commands remotely. Mercurial makes 3.2317 -tries to detect and ignore banners in non-interactive <command>ssh</command> 3.2318 -sessions, but it is not foolproof. (If you're editing your login 3.2319 -scripts on your server, the usual way to see if a login script is 3.2320 -running in an interactive shell is to check the return code from the 3.2321 -command <literal>tty -s</literal>.) 3.2322 -</para> 3.2323 - 3.2324 -<para>Once you've verified that plain old ssh is working with your server, 3.2325 -the next step is to ensure that Mercurial runs on the server. The 3.2326 -following command should run successfully: 3.2327 -</para> 3.2328 -<programlisting> 3.2329 -<para> ssh myserver hg version 3.2330 -</para> 3.2331 -</programlisting> 3.2332 -<para>If you see an error message instead of normal <command role="hg-cmd">hg version</command> output, 3.2333 -this is usually because you haven't installed Mercurial to 3.2334 -<filename class="directory">/usr/bin</filename>. Don't worry if this is the case; you don't need 3.2335 -to do that. But you should check for a few possible problems. 3.2336 -</para> 3.2337 -<itemizedlist> 3.2338 -<listitem><para>Is Mercurial really installed on the server at all? I know this 3.2339 - sounds trivial, but it's worth checking! 3.2340 -</para> 3.2341 -</listitem> 3.2342 -<listitem><para>Maybe your shell's search path (usually set via the <envar>PATH</envar> 3.2343 - environment variable) is simply misconfigured. 3.2344 -</para> 3.2345 -</listitem> 3.2346 -<listitem><para>Perhaps your <envar>PATH</envar> environment variable is only being set 3.2347 - to point to the location of the <command>hg</command> executable if the login 3.2348 - session is interactive. This can happen if you're setting the path 3.2349 - in the wrong shell login script. See your shell's documentation for 3.2350 - details. 3.2351 -</para> 3.2352 -</listitem> 3.2353 -<listitem><para>The <envar>PYTHONPATH</envar> environment variable may need to contain 3.2354 - the path to the Mercurial Python modules. It might not be set at 3.2355 - all; it could be incorrect; or it may be set only if the login is 3.2356 - interactive. 3.2357 -</para> 3.2358 -</listitem></itemizedlist> 3.2359 - 3.2360 -<para>If you can run <command role="hg-cmd">hg version</command> over an ssh connection, well done! 3.2361 -You've got the server and client sorted out. You should now be able 3.2362 -to use Mercurial to access repositories hosted by that username on 3.2363 -that server. If you run into problems with Mercurial and ssh at this 3.2364 -point, try using the <option role="hg-opt-global">--debug</option> option to get a clearer picture 3.2365 -of what's going on. 3.2366 -</para> 3.2367 - 3.2368 -</sect2> 3.2369 -<sect2> 3.2370 -<title>Using compression with ssh</title> 3.2371 - 3.2372 -<para>Mercurial does not compress data when it uses the ssh protocol, 3.2373 -because the ssh protocol can transparently compress data. However, 3.2374 -the default behaviour of ssh clients is <emphasis>not</emphasis> to request 3.2375 -compression. 3.2376 -</para> 3.2377 - 3.2378 -<para>Over any network other than a fast LAN (even a wireless network), 3.2379 -using compression is likely to significantly speed up Mercurial's 3.2380 -network operations. For example, over a WAN, someone measured 3.2381 -compression as reducing the amount of time required to clone a 3.2382 -particularly large repository from 51 minutes to 17 minutes. 3.2383 -</para> 3.2384 - 3.2385 -<para>Both <command>ssh</command> and <command>plink</command> accept a <option role="cmd-opt-ssh">-C</option> 3.2386 -option which turns on compression. You can easily edit your <filename role="special"> /.hgrc</filename>\ to 3.2387 -enable compression for all of Mercurial's uses of the ssh protocol. 3.2388 -</para> 3.2389 -<programlisting> 3.2390 -<para> [ui] 3.2391 - ssh = ssh -C 3.2392 -</para> 3.2393 -</programlisting> 3.2394 - 3.2395 -<para>If you use <command>ssh</command>, you can configure it to always use 3.2396 -compression when talking to your server. To do this, edit your 3.2397 -<filename role="special">.ssh/config</filename> file (which may not yet exist), as follows. 3.2398 -</para> 3.2399 -<programlisting> 3.2400 -<para> Host hg 3.2401 - Compression yes 3.2402 - HostName hg.example.com 3.2403 -</para> 3.2404 -</programlisting> 3.2405 -<para>This defines an alias, <literal>hg</literal>. When you use it on the 3.2406 -<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-protocol 3.2407 -URL, it will cause <command>ssh</command> to connect to <literal>hg.example.com</literal> 3.2408 -and use compression. This gives you both a shorter name to type and 3.2409 -compression, each of which is a good thing in its own right. 3.2410 -</para> 3.2411 - 3.2412 -</sect2> 3.2413 -</sect1> 3.2414 -<sect1> 3.2415 -<title>Serving over HTTP using CGI</title> 3.2416 -<para>\label{sec:collab:cgi} 3.2417 -</para> 3.2418 - 3.2419 -<para>Depending on how ambitious you are, configuring Mercurial's CGI 3.2420 -interface can take anything from a few moments to several hours. 3.2421 -</para> 3.2422 - 3.2423 -<para>We'll begin with the simplest of examples, and work our way towards a 3.2424 -more complex configuration. Even for the most basic case, you're 3.2425 -almost certainly going to need to read and modify your web server's 3.2426 -configuration. 3.2427 -</para> 3.2428 - 3.2429 -<note> 3.2430 -<para> Configuring a web server is a complex, fiddly, and highly 3.2431 - system-dependent activity. I can't possibly give you instructions 3.2432 - that will cover anything like all of the cases you will encounter. 3.2433 - Please use your discretion and judgment in following the sections 3.2434 - below. Be prepared to make plenty of mistakes, and to spend a lot 3.2435 - of time reading your server's error logs. 3.2436 -</para> 3.2437 -</note> 3.2438 - 3.2439 -<sect2> 3.2440 -<title>Web server configuration checklist</title> 3.2441 - 3.2442 -<para>Before you continue, do take a few moments to check a few aspects of 3.2443 -your system's setup. 3.2444 -</para> 3.2445 - 3.2446 -<orderedlist> 3.2447 -<listitem><para>Do you have a web server installed at all? Mac OS X ships with 3.2448 - Apache, but many other systems may not have a web server installed. 3.2449 -</para> 3.2450 -</listitem> 3.2451 -<listitem><para>If you have a web server installed, is it actually running? On 3.2452 - most systems, even if one is present, it will be disabled by 3.2453 - default. 3.2454 -</para> 3.2455 -</listitem> 3.2456 -<listitem><para>Is your server configured to allow you to run CGI programs in 3.2457 - the directory where you plan to do so? Most servers default to 3.2458 - explicitly disabling the ability to run CGI programs. 3.2459 -</para> 3.2460 -</listitem></orderedlist> 3.2461 - 3.2462 -<para>If you don't have a web server installed, and don't have substantial 3.2463 -experience configuring Apache, you should consider using the 3.2464 -<literal>lighttpd</literal> web server instead of Apache. Apache has a 3.2465 -well-deserved reputation for baroque and confusing configuration. 3.2466 -While <literal>lighttpd</literal> is less capable in some ways than Apache, most 3.2467 -of these capabilities are not relevant to serving Mercurial 3.2468 -repositories. And <literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier 3.2469 -to get started with than Apache. 3.2470 -</para> 3.2471 - 3.2472 -</sect2> 3.2473 -<sect2> 3.2474 -<title>Basic CGI configuration</title> 3.2475 - 3.2476 -<para>On Unix-like systems, it's common for users to have a subdirectory 3.2477 -named something like <filename class="directory">public_html</filename> in their home directory, 3.2478 -from which they can serve up web pages. A file named <filename>foo</filename> 3.2479 -in this directory will be accessible at a URL of the form 3.2480 -<literal>http://www.example.com/\ {</literal>username/foo}. 3.2481 -</para> 3.2482 - 3.2483 -<para>To get started, find the <filename role="special">hgweb.cgi</filename> script that should be 3.2484 -present in your Mercurial installation. If you can't quickly find a 3.2485 -local copy on your system, simply download one from the master 3.2486 -Mercurial repository at 3.2487 -<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>. 3.2488 -</para> 3.2489 - 3.2490 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename> 3.2491 -directory, and ensure that it's executable. 3.2492 -</para> 3.2493 -<programlisting> 3.2494 -<para> cp .../hgweb.cgi /public_html 3.2495 - chmod 755 /public_html/hgweb.cgi 3.2496 -</para> 3.2497 -</programlisting> 3.2498 -<para>The <literal>755</literal> argument to <command>chmod</command> is a little more general 3.2499 -than just making the script executable: it ensures that the script is 3.2500 -executable by anyone, and that <quote>group</quote> and <quote>other</quote> write 3.2501 -permissions are <emphasis>not</emphasis> set. If you were to leave those write 3.2502 -permissions enabled, Apache's <literal>suexec</literal> subsystem would likely 3.2503 -refuse to execute the script. In fact, <literal>suexec</literal> also insists 3.2504 -that the <emphasis>directory</emphasis> in which the script resides must not be 3.2505 -writable by others. 3.2506 -</para> 3.2507 -<programlisting> 3.2508 -<para> chmod 755 /public_html 3.2509 -</para> 3.2510 -</programlisting> 3.2511 - 3.2512 -<sect3> 3.2513 -<title>What could <emphasis>possibly</emphasis> go wrong?</title> 3.2514 -<para>\label{sec:collab:wtf} 3.2515 -</para> 3.2516 - 3.2517 -<para>Once you've copied the CGI script into place, go into a web browser, 3.2518 -and try to open the URL <ulink url="http://myhostname/ myuser/hgweb.cgi">http://myhostname/ myuser/hgweb.cgi</ulink>, 3.2519 -<emphasis>but</emphasis> brace yourself for instant failure. There's a high 3.2520 -probability that trying to visit this URL will fail, and there are 3.2521 -many possible reasons for this. In fact, you're likely to stumble 3.2522 -over almost every one of the possible errors below, so please read 3.2523 -carefully. The following are all of the problems I ran into on a 3.2524 -system running Fedora 7, with a fresh installation of Apache, and a 3.2525 -user account that I created specially to perform this exercise. 3.2526 -</para> 3.2527 - 3.2528 -<para>Your web server may have per-user directories disabled. If you're 3.2529 -using Apache, search your config file for a <literal>UserDir</literal> 3.2530 -directive. If there's none present, per-user directories will be 3.2531 -disabled. If one exists, but its value is <literal>disabled</literal>, then 3.2532 -per-user directories will be disabled. Otherwise, the string after 3.2533 -<literal>UserDir</literal> gives the name of the subdirectory that Apache will 3.2534 -look in under your home directory, for example <filename class="directory">public_html</filename>. 3.2535 -</para> 3.2536 - 3.2537 -<para>Your file access permissions may be too restrictive. The web server 3.2538 -must be able to traverse your home directory and directories under 3.2539 -your <filename class="directory">public_html</filename> directory, and read files under the latter 3.2540 -too. Here's a quick recipe to help you to make your permissions more 3.2541 -appropriate. 3.2542 -</para> 3.2543 -<programlisting> 3.2544 -<para> chmod 755 3.2545 - find /public_html -type d -print0 | xargs -0r chmod 755 3.2546 - find /public_html -type f -print0 | xargs -0r chmod 644 3.2547 -</para> 3.2548 -</programlisting> 3.2549 - 3.2550 -<para>The other possibility with permissions is that you might get a 3.2551 -completely empty window when you try to load the script. In this 3.2552 -case, it's likely that your access permissions are \emph{too 3.2553 - permissive}. Apache's <literal>suexec</literal> subsystem won't execute a 3.2554 -script that's group- or world-writable, for example. 3.2555 -</para> 3.2556 - 3.2557 -<para>Your web server may be configured to disallow execution of CGI 3.2558 -programs in your per-user web directory. Here's Apache's 3.2559 -default per-user configuration from my Fedora system. 3.2560 -</para> 3.2561 -<programlisting> 3.2562 -<para> <Directory /home/*/public_html> 3.2563 - AllowOverride FileInfo AuthConfig Limit 3.2564 - Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 3.2565 - <Limit GET POST OPTIONS> 3.2566 - Order allow,deny 3.2567 - Allow from all 3.2568 - </Limit> 3.2569 - <LimitExcept GET POST OPTIONS> 3.2570 - Order deny,allow 3.2571 - Deny from all 3.2572 - </LimitExcept> 3.2573 - </Directory> 3.2574 -</para> 3.2575 -</programlisting> 3.2576 -<para>If you find a similar-looking <literal>Directory</literal> group in your Apache 3.2577 -configuration, the directive to look at inside it is <literal>Options</literal>. 3.2578 -Add <literal>ExecCGI</literal> to the end of this list if it's missing, and 3.2579 -restart the web server. 3.2580 -</para> 3.2581 - 3.2582 -<para>If you find that Apache serves you the text of the CGI script instead 3.2583 -of executing it, you may need to either uncomment (if already present) 3.2584 -or add a directive like this. 3.2585 -</para> 3.2586 -<programlisting> 3.2587 -<para> AddHandler cgi-script .cgi 3.2588 -</para> 3.2589 -</programlisting> 3.2590 - 3.2591 -<para>The next possibility is that you might be served with a colourful 3.2592 -Python backtrace claiming that it can't import a 3.2593 -<literal>mercurial</literal>-related module. This is actually progress! The 3.2594 -server is now capable of executing your CGI script. This error is 3.2595 -only likely to occur if you're running a private installation of 3.2596 -Mercurial, instead of a system-wide version. Remember that the web 3.2597 -server runs the CGI program without any of the environment variables 3.2598 -that you take for granted in an interactive session. If this error 3.2599 -happens to you, edit your copy of <filename role="special">hgweb.cgi</filename> and follow the 3.2600 -directions inside it to correctly set your <envar>PYTHONPATH</envar> 3.2601 -environment variable. 3.2602 -</para> 3.2603 - 3.2604 -<para>Finally, you are <emphasis>certain</emphasis> to by served with another colourful 3.2605 -Python backtrace: this one will complain that it can't find 3.2606 -<filename class="directory">/path/to/repository</filename>. Edit your <filename role="special">hgweb.cgi</filename> script 3.2607 -and replace the <filename class="directory">/path/to/repository</filename> string with the complete 3.2608 -path to the repository you want to serve up. 3.2609 -</para> 3.2610 - 3.2611 -<para>At this point, when you try to reload the page, you should be 3.2612 -presented with a nice HTML view of your repository's history. Whew! 3.2613 -</para> 3.2614 - 3.2615 -</sect3> 3.2616 -<sect3> 3.2617 -<title>Configuring lighttpd</title> 3.2618 - 3.2619 -<para>To be exhaustive in my experiments, I tried configuring the 3.2620 -increasingly popular <literal>lighttpd</literal> web server to serve the same 3.2621 -repository as I described with Apache above. I had already overcome 3.2622 -all of the problems I outlined with Apache, many of which are not 3.2623 -server-specific. As a result, I was fairly sure that my file and 3.2624 -directory permissions were good, and that my <filename role="special">hgweb.cgi</filename> 3.2625 -script was properly edited. 3.2626 -</para> 3.2627 - 3.2628 -<para>Once I had Apache running, getting <literal>lighttpd</literal> to serve the 3.2629 -repository was a snap (in other words, even if you're trying to use 3.2630 -<literal>lighttpd</literal>, you should read the Apache section). I first had 3.2631 -to edit the <literal>mod_access</literal> section of its config file to enable 3.2632 -<literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of which were 3.2633 -disabled by default on my system. I then added a few lines to the end 3.2634 -of the config file, to configure these modules. 3.2635 -</para> 3.2636 -<programlisting> 3.2637 -<para> userdir.path = "public_html" 3.2638 - cgi.assign = ( ".cgi" => "" ) 3.2639 -</para> 3.2640 -</programlisting> 3.2641 -<para>With this done, <literal>lighttpd</literal> ran immediately for me. If I had 3.2642 -configured <literal>lighttpd</literal> before Apache, I'd almost certainly have 3.2643 -run into many of the same system-level configuration problems as I did 3.2644 -with Apache. However, I found <literal>lighttpd</literal> to be noticeably 3.2645 -easier to configure than Apache, even though I've used Apache for over 3.2646 -a decade, and this was my first exposure to <literal>lighttpd</literal>. 3.2647 -</para> 3.2648 - 3.2649 -</sect3> 3.2650 -</sect2> 3.2651 -<sect2> 3.2652 -<title>Sharing multiple repositories with one CGI script</title> 3.2653 - 3.2654 -<para>The <filename role="special">hgweb.cgi</filename> script only lets you publish a single 3.2655 -repository, which is an annoying restriction. If you want to publish 3.2656 -more than one without wracking yourself with multiple copies of the 3.2657 -same script, each with different names, a better choice is to use the 3.2658 -<filename role="special">hgwebdir.cgi</filename> script. 3.2659 -</para> 3.2660 - 3.2661 -<para>The procedure to configure <filename role="special">hgwebdir.cgi</filename> is only a little 3.2662 -more involved than for <filename role="special">hgweb.cgi</filename>. First, you must obtain 3.2663 -a copy of the script. If you don't have one handy, you can download a 3.2664 -copy from the master Mercurial repository at 3.2665 -<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>. 3.2666 -</para> 3.2667 - 3.2668 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename> 3.2669 -directory, and ensure that it's executable. 3.2670 -</para> 3.2671 -<programlisting> 3.2672 -<para> cp .../hgwebdir.cgi /public_html 3.2673 - chmod 755 /public_html /public_html/hgwebdir.cgi 3.2674 -</para> 3.2675 -</programlisting> 3.2676 -<para>With basic configuration out of the way, try to visit 3.2677 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink> in your browser. It 3.2678 -should display an empty list of repositories. If you get a blank 3.2679 -window or error message, try walking through the list of potential 3.2680 -problems in section <xref linkend="sec:collab:wtf"/>. 3.2681 -</para> 3.2682 - 3.2683 -<para>The <filename role="special">hgwebdir.cgi</filename> script relies on an external 3.2684 -configuration file. By default, it searches for a file named 3.2685 -<filename role="special">hgweb.config</filename> in the same directory as itself. You'll need 3.2686 -to create this file, and make it world-readable. The format of the 3.2687 -file is similar to a Windows <quote>ini</quote> file, as understood by Python's 3.2688 -<literal>ConfigParser</literal> <citation>web:configparser</citation> module. 3.2689 -</para> 3.2690 - 3.2691 -<para>The easiest way to configure <filename role="special">hgwebdir.cgi</filename> is with a 3.2692 -section named <literal>collections</literal>. This will automatically publish 3.2693 -<emphasis>every</emphasis> repository under the directories you name. The section 3.2694 -should look like this: 3.2695 -</para> 3.2696 -<programlisting> 3.2697 -<para> [collections] 3.2698 - /my/root = /my/root 3.2699 -</para> 3.2700 -</programlisting> 3.2701 -<para>Mercurial interprets this by looking at the directory name on the 3.2702 -<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></quote> sign; finding 3.2703 -repositories in that directory hierarchy; and using the text on the 3.2704 -<emphasis>left</emphasis> to strip off matching text from the names it will actually 3.2705 -list in the web interface. The remaining component of a path after 3.2706 -this stripping has occurred is called a <quote>virtual path</quote>. 3.2707 -</para> 3.2708 - 3.2709 -<para>Given the example above, if we have a repository whose local path is 3.2710 -<filename class="directory">/my/root/this/repo</filename>, the CGI script will strip the leading 3.2711 -<filename class="directory">/my/root</filename> from the name, and publish the repository with a 3.2712 -virtual path of <filename class="directory">this/repo</filename>. If the base URL for our CGI 3.2713 -script is <ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink>, the complete 3.2714 -URL for that repository will be 3.2715 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi/this/repo">http://myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>. 3.2716 -</para> 3.2717 - 3.2718 -<para>If we replace <filename class="directory">/my/root</filename> on the left hand side of this example 3.2719 -with <filename class="directory">/my</filename>, then <filename role="special">hgwebdir.cgi</filename> will only strip off 3.2720 -<filename class="directory">/my</filename> from the repository name, and will give us a virtual 3.2721 -path of <filename class="directory">root/this/repo</filename> instead of <filename class="directory">this/repo</filename>. 3.2722 -</para> 3.2723 - 3.2724 -<para>The <filename role="special">hgwebdir.cgi</filename> script will recursively search each 3.2725 -directory listed in the <literal>collections</literal> section of its 3.2726 -configuration file, but it will <literal>not</literal> recurse into the 3.2727 -repositories it finds. 3.2728 -</para> 3.2729 - 3.2730 -<para>The <literal>collections</literal> mechanism makes it easy to publish many 3.2731 -repositories in a <quote>fire and forget</quote> manner. You only need to set up 3.2732 -the CGI script and configuration file one time. Afterwards, you can 3.2733 -publish or unpublish a repository at any time by simply moving it 3.2734 -into, or out of, the directory hierarchy in which you've configured 3.2735 -<filename role="special">hgwebdir.cgi</filename> to look. 3.2736 -</para> 3.2737 - 3.2738 -<sect3> 3.2739 -<title>Explicitly specifying which repositories to publish</title> 3.2740 - 3.2741 -<para>In addition to the <literal>collections</literal> mechanism, the 3.2742 -<filename role="special">hgwebdir.cgi</filename> script allows you to publish a specific list 3.2743 -of repositories. To do so, create a <literal>paths</literal> section, with 3.2744 -contents of the following form. 3.2745 -</para> 3.2746 -<programlisting> 3.2747 -<para> [paths] 3.2748 - repo1 = /my/path/to/some/repo 3.2749 - repo2 = /some/path/to/another 3.2750 -</para> 3.2751 -</programlisting> 3.2752 -<para>In this case, the virtual path (the component that will appear in a 3.2753 -URL) is on the left hand side of each definition, while the path to 3.2754 -the repository is on the right. Notice that there does not need to be 3.2755 -any relationship between the virtual path you choose and the location 3.2756 -of a repository in your filesystem. 3.2757 -</para> 3.2758 - 3.2759 -<para>If you wish, you can use both the <literal>collections</literal> and 3.2760 -<literal>paths</literal> mechanisms simultaneously in a single configuration 3.2761 -file. 3.2762 -</para> 3.2763 - 3.2764 -<note> 3.2765 -<para> If multiple repositories have the same virtual path, 3.2766 - <filename role="special">hgwebdir.cgi</filename> will not report an error. Instead, it will 3.2767 - behave unpredictably. 3.2768 -</para> 3.2769 -</note> 3.2770 - 3.2771 -</sect3> 3.2772 -</sect2> 3.2773 -<sect2> 3.2774 -<title>Downloading source archives</title> 3.2775 - 3.2776 -<para>Mercurial's web interface lets users download an archive of any 3.2777 -revision. This archive will contain a snapshot of the working 3.2778 -directory as of that revision, but it will not contain a copy of the 3.2779 -repository data. 3.2780 -</para> 3.2781 - 3.2782 -<para>By default, this feature is not enabled. To enable it, you'll need to 3.2783 -add an <envar role="rc-item-web">allow_archive</envar> item to the <literal role="rc-web">web</literal> 3.2784 -section of your <filename role="special"> /.hgrc</filename>. 3.2785 -</para> 3.2786 - 3.2787 -</sect2> 3.2788 -<sect2> 3.2789 -<title>Web configuration options</title> 3.2790 - 3.2791 -<para>Mercurial's web interfaces (the <command role="hg-cmd">hg serve</command> command, and the 3.2792 -<filename role="special">hgweb.cgi</filename> and <filename role="special">hgwebdir.cgi</filename> scripts) have a 3.2793 -number of configuration options that you can set. These belong in a 3.2794 -section named <literal role="rc-web">web</literal>. 3.2795 -</para> 3.2796 -<itemizedlist> 3.2797 -<listitem><para><envar role="rc-item-web">allow_archive</envar>: Determines which (if any) archive 3.2798 - download mechanisms Mercurial supports. If you enable this 3.2799 - feature, users of the web interface will be able to download an 3.2800 - archive of whatever revision of a repository they are viewing. 3.2801 - To enable the archive feature, this item must take the form of a 3.2802 - sequence of words drawn from the list below. 3.2803 -</para> 3.2804 -</listitem><itemizedlist> 3.2805 -<listitem><para> \item <literal>bz2</literal>: A <command>tar</command> archive, compressed using 3.2806 - <literal>bzip2</literal> compression. This has the best compression ratio, 3.2807 - but uses the most CPU time on the server. 3.2808 - \item <literal>gz</literal>: A <command>tar</command> archive, compressed using 3.2809 - <literal>gzip</literal> compression. 3.2810 - \item <literal>zip</literal>: A <command>zip</command> archive, compressed using LZW 3.2811 - compression. This format has the worst compression ratio, but is 3.2812 - widely used in the Windows world. 3.2813 -</para> 3.2814 -</listitem></itemizedlist> 3.2815 -<para> If you provide an empty list, or don't have an 3.2816 - <envar role="rc-item-web">allow_archive</envar> entry at all, this feature will be 3.2817 - disabled. Here is an example of how to enable all three supported 3.2818 - formats. 3.2819 -</para> 3.2820 -<programlisting> 3.2821 -<para> [web] 3.2822 - allow_archive = bz2 gz zip 3.2823 -</para> 3.2824 -</programlisting> 3.2825 -<listitem><para><envar role="rc-item-web">allowpull</envar>: Boolean. Determines whether the web 3.2826 - interface allows remote users to <command role="hg-cmd">hg pull</command> and <command role="hg-cmd">hg clone</command> this 3.2827 - repository over HTTP. If set to <literal>no</literal> or <literal>false</literal>, only 3.2828 - the <quote>human-oriented</quote> portion of the web interface is available. 3.2829 -</para> 3.2830 -</listitem> 3.2831 -<listitem><para><envar role="rc-item-web">contact</envar>: String. A free-form (but preferably 3.2832 - brief) string identifying the person or group in charge of the 3.2833 - repository. This often contains the name and email address of a 3.2834 - person or mailing list. It often makes sense to place this entry in 3.2835 - a repository's own <filename role="special">.hg/hgrc</filename> file, but it can make sense 3.2836 - to use in a global <filename role="special"> /.hgrc</filename>\ if every repository has a single 3.2837 - maintainer. 3.2838 -</para> 3.2839 -</listitem> 3.2840 -<listitem><para><envar role="rc-item-web">maxchanges</envar>: Integer. The default maximum number 3.2841 - of changesets to display in a single page of output. 3.2842 -</para> 3.2843 -</listitem> 3.2844 -<listitem><para><envar role="rc-item-web">maxfiles</envar>: Integer. The default maximum number 3.2845 - of modified files to display in a single page of output. 3.2846 -</para> 3.2847 -</listitem> 3.2848 -<listitem><para><envar role="rc-item-web">stripes</envar>: Integer. If the web interface displays 3.2849 - alternating <quote>stripes</quote> to make it easier to visually align rows 3.2850 - when you are looking at a table, this number controls the number of 3.2851 - rows in each stripe. 3.2852 -</para> 3.2853 -</listitem> 3.2854 -<listitem><para><envar role="rc-item-web">style</envar>: Controls the template Mercurial uses to 3.2855 - display the web interface. Mercurial ships with two web templates, 3.2856 - named <literal>default</literal> and <literal>gitweb</literal> (the latter is much more 3.2857 - visually attractive). You can also specify a custom template of 3.2858 - your own; see chapter <xref linkend="chap:template"/> for details. Here, you 3.2859 - can see how to enable the <literal>gitweb</literal> style. 3.2860 -</para> 3.2861 -</listitem><programlisting> 3.2862 -<listitem><para> [web] 3.2863 - style = gitweb 3.2864 -</para> 3.2865 -</listitem></programlisting> 3.2866 -</para> 3.2867 -</listitem> 3.2868 -<listitem><para><envar role="rc-item-web">templates</envar>: Path. The directory in which to search 3.2869 - for template files. By default, Mercurial searches in the directory 3.2870 - in which it was installed. 3.2871 -</para> 3.2872 -</listitem></itemizedlist> 3.2873 -<para>If you are using <filename role="special">hgwebdir.cgi</filename>, you can place a few 3.2874 -configuration items in a <literal role="rc-web">web</literal> section of the 3.2875 -<filename role="special">hgweb.config</filename> file instead of a <filename role="special"> /.hgrc</filename>\ file, for 3.2876 -convenience. These items are <envar role="rc-item-web">motd</envar> and 3.2877 -<envar role="rc-item-web">style</envar>. 3.2878 -</para> 3.2879 - 3.2880 -<sect3> 3.2881 -<title>Options specific to an individual repository</title> 3.2882 - 3.2883 -<para>A few <literal role="rc-web">web</literal> configuration items ought to be placed in a 3.2884 -repository's local <filename role="special">.hg/hgrc</filename>, rather than a user's or 3.2885 -global <filename role="special"> /.hgrc</filename>. 3.2886 -</para> 3.2887 -<itemizedlist> 3.2888 -<listitem><para><envar role="rc-item-web">description</envar>: String. A free-form (but preferably 3.2889 - brief) string that describes the contents or purpose of the 3.2890 - repository. 3.2891 -</para> 3.2892 -</listitem> 3.2893 -<listitem><para><envar role="rc-item-web">name</envar>: String. The name to use for the repository 3.2894 - in the web interface. This overrides the default name, which is the 3.2895 - last component of the repository's path. 3.2896 -</para> 3.2897 -</listitem></itemizedlist> 3.2898 - 3.2899 -</sect3> 3.2900 -<sect3> 3.2901 -<title>Options specific to the <command role="hg-cmd">hg serve</command> command</title> 3.2902 - 3.2903 -<para>Some of the items in the <literal role="rc-web">web</literal> section of a <filename role="special"> /.hgrc</filename>\ file are 3.2904 -only for use with the <command role="hg-cmd">hg serve</command> command. 3.2905 -</para> 3.2906 -<itemizedlist> 3.2907 -<listitem><para><envar role="rc-item-web">accesslog</envar>: Path. The name of a file into which to 3.2908 - write an access log. By default, the <command role="hg-cmd">hg serve</command> command writes 3.2909 - this information to standard output, not to a file. Log entries are 3.2910 - written in the standard <quote>combined</quote> file format used by almost all 3.2911 - web servers. 3.2912 -</para> 3.2913 -</listitem> 3.2914 -<listitem><para><envar role="rc-item-web">address</envar>: String. The local address on which the 3.2915 - server should listen for incoming connections. By default, the 3.2916 - server listens on all addresses. 3.2917 -</para> 3.2918 -</listitem> 3.2919 -<listitem><para><envar role="rc-item-web">errorlog</envar>: Path. The name of a file into which to 3.2920 - write an error log. By default, the <command role="hg-cmd">hg serve</command> command writes this 3.2921 - information to standard error, not to a file. 3.2922 -</para> 3.2923 -</listitem> 3.2924 -<listitem><para><envar role="rc-item-web">ipv6</envar>: Boolean. Whether to use the IPv6 protocol. 3.2925 - By default, IPv6 is not used. 3.2926 -</para> 3.2927 -</listitem> 3.2928 -<listitem><para><envar role="rc-item-web">port</envar>: Integer. The TCP port number on which the 3.2929 - server should listen. The default port number used is 8000. 3.2930 -</para> 3.2931 -</listitem></itemizedlist> 3.2932 - 3.2933 -<para>\subsubsection{Choosing the right <filename role="special"> /.hgrc</filename>\ file to add <literal role="rc-web">web</literal> 3.2934 - items to} 3.2935 -</para> 3.2936 - 3.2937 -<para>It is important to remember that a web server like Apache or 3.2938 -<literal>lighttpd</literal> will run under a user ID that is different to yours. 3.2939 -CGI scripts run by your server, such as <filename role="special">hgweb.cgi</filename>, will 3.2940 -usually also run under that user ID. 3.2941 -</para> 3.2942 - 3.2943 -<para>If you add <literal role="rc-web">web</literal> items to your own personal <filename role="special"> /.hgrc</filename>\ file, CGI 3.2944 -scripts won't read that <filename role="special"> /.hgrc</filename>\ file. Those settings will thus only 3.2945 -affect the behaviour of the <command role="hg-cmd">hg serve</command> command when you run it. To 3.2946 -cause CGI scripts to see your settings, either create a <filename role="special"> /.hgrc</filename>\ file in 3.2947 -the home directory of the user ID that runs your web server, or add 3.2948 -those settings to a system-wide <filename role="special"> /.hgrc</filename>\ file. 3.2949 -</para> 3.2950 - 3.2951 - 3.2952 -</sect3> 3.2953 -</sect2> 3.2954 -</sect1> 3.2955 + </sect2> 3.2956 + </sect1> 3.2957 </chapter> 3.2958 3.2959 <!-- 3.2960 local variables: 3.2961 sgml-parent-document: ("00book.xml" "book" "chapter") 3.2962 end: 3.2963 ---> 3.2964 \ No newline at end of file 3.2965 +-->
4.1 --- a/fr/ch07-filenames.xml Wed Sep 09 15:25:09 2009 +0200 4.2 +++ b/fr/ch07-filenames.xml Wed Sep 09 16:07:36 2009 +0200 4.3 @@ -1,388 +1,451 @@ 4.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 4.5 4.6 -<chapter> 4.7 -<title>File names and pattern matching</title> 4.8 -<para>\label{chap:names}</para> 4.9 - 4.10 -<para>Mercurial provides mechanisms that let you work with file names in a 4.11 -consistent and expressive way.</para> 4.12 - 4.13 -<sect1> 4.14 -<title>Simple file naming</title> 4.15 - 4.16 -<para>Mercurial uses a unified piece of machinery <quote>under the hood</quote> to 4.17 -handle file names. Every command behaves uniformly with respect to 4.18 -file names. The way in which commands work with file names is as 4.19 -follows.</para> 4.20 - 4.21 -<para>If you explicitly name real files on the command line, Mercurial works 4.22 -with exactly those files, as you would expect. 4.23 -<!-- &interaction.filenames.files; --></para> 4.24 - 4.25 -<para>When you provide a directory name, Mercurial will interpret this as 4.26 -<quote>operate on every file in this directory and its subdirectories</quote>. 4.27 -Mercurial traverses the files and subdirectories in a directory in 4.28 -alphabetical order. When it encounters a subdirectory, it will 4.29 -traverse that subdirectory before continuing with the current 4.30 -directory. 4.31 -<!-- &interaction.filenames.dirs; --></para> 4.32 - 4.33 -</sect1> 4.34 -<sect1> 4.35 -<title>Running commands without any file names</title> 4.36 - 4.37 -<para>Mercurial's commands that work with file names have useful default 4.38 -behaviours when you invoke them without providing any file names or 4.39 -patterns. What kind of behaviour you should expect depends on what 4.40 -the command does. Here are a few rules of thumb you can use to 4.41 -predict what a command is likely to do if you don't give it any names 4.42 -to work with.</para> 4.43 -<itemizedlist> 4.44 -<listitem><para>Most commands will operate on the entire working directory. 4.45 - This is what the <command role="hg-cmd">hg add</command> command does, for example.</para> 4.46 -</listitem> 4.47 -<listitem><para>If the command has effects that are difficult or impossible to 4.48 - reverse, it will force you to explicitly provide at least one name 4.49 - or pattern (see below). This protects you from accidentally 4.50 - deleting files by running <command role="hg-cmd">hg remove</command> with no arguments, for 4.51 - example.</para> 4.52 -</listitem></itemizedlist> 4.53 - 4.54 -<para>It's easy to work around these default behaviours if they don't suit 4.55 -you. If a command normally operates on the whole working directory, 4.56 -you can invoke it on just the current directory and its subdirectories 4.57 -by giving it the name <quote><filename class="directory">.</filename></quote>. 4.58 -<!-- &interaction.filenames.wdir-subdir; --> 4.59 -</para> 4.60 - 4.61 -<para>Along the same lines, some commands normally print file names relative 4.62 -to the root of the repository, even if you're invoking them from a 4.63 -subdirectory. Such a command will print file names relative to your 4.64 -subdirectory if you give it explicit names. Here, we're going to run 4.65 -<command role="hg-cmd">hg status</command> from a subdirectory, and get it to operate on the 4.66 -entire working directory while printing file names relative to our 4.67 -subdirectory, by passing it the output of the <command role="hg-cmd">hg root</command> command. 4.68 -<!-- &interaction.filenames.wdir-relname; --> 4.69 -</para> 4.70 - 4.71 -</sect1> 4.72 -<sect1> 4.73 -<title>Telling you what's going on</title> 4.74 - 4.75 -<para>The <command role="hg-cmd">hg add</command> example in the preceding section illustrates something 4.76 -else that's helpful about Mercurial commands. If a command operates 4.77 -on a file that you didn't name explicitly on the command line, it will 4.78 -usually print the name of the file, so that you will not be surprised 4.79 -what's going on. 4.80 -</para> 4.81 - 4.82 -<para>The principle here is of <emphasis>least surprise</emphasis>. If you've exactly 4.83 -named a file on the command line, there's no point in repeating it 4.84 -back at you. If Mercurial is acting on a file <emphasis>implicitly</emphasis>, 4.85 -because you provided no names, or a directory, or a pattern (see 4.86 -below), it's safest to tell you what it's doing. 4.87 -</para> 4.88 - 4.89 -<para>For commands that behave this way, you can silence them using the 4.90 -<option role="hg-opt-global">-q</option> option. You can also get them to print the name of every 4.91 -file, even those you've named explicitly, using the <option role="hg-opt-global">-v</option> 4.92 -option. 4.93 -</para> 4.94 - 4.95 -</sect1> 4.96 -<sect1> 4.97 -<title>Using patterns to identify files</title> 4.98 - 4.99 -<para>In addition to working with file and directory names, Mercurial lets 4.100 -you use <emphasis>patterns</emphasis> to identify files. Mercurial's pattern 4.101 -handling is expressive. 4.102 -</para> 4.103 - 4.104 -<para>On Unix-like systems (Linux, MacOS, etc.), the job of matching file 4.105 -names to patterns normally falls to the shell. On these systems, you 4.106 -must explicitly tell Mercurial that a name is a pattern. On Windows, 4.107 -the shell does not expand patterns, so Mercurial will automatically 4.108 -identify names that are patterns, and expand them for you. 4.109 -</para> 4.110 - 4.111 -<para>To provide a pattern in place of a regular name on the command line, 4.112 -the mechanism is simple: 4.113 -</para> 4.114 -<programlisting> 4.115 -<para> syntax:patternbody 4.116 -</para> 4.117 +<chapter id="chap:names"> 4.118 + <?dbhtml filename="file-names-and-pattern-matching.html"?> 4.119 + <title>File names and pattern matching</title> 4.120 + 4.121 + <para id="x_543">Mercurial provides mechanisms that let you work with file 4.122 + names in a consistent and expressive way.</para> 4.123 + 4.124 + <sect1> 4.125 + <title>Simple file naming</title> 4.126 + 4.127 + <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the 4.128 + hood</quote> to handle file names. Every command behaves 4.129 + uniformly with respect to file names. The way in which commands 4.130 + work with file names is as follows.</para> 4.131 + 4.132 + <para id="x_545">If you explicitly name real files on the command line, 4.133 + Mercurial works with exactly those files, as you would expect. 4.134 + &interaction.filenames.files;</para> 4.135 + 4.136 + <para id="x_546">When you provide a directory name, Mercurial will interpret 4.137 + this as <quote>operate on every file in this directory and its 4.138 + subdirectories</quote>. Mercurial traverses the files and 4.139 + subdirectories in a directory in alphabetical order. When it 4.140 + encounters a subdirectory, it will traverse that subdirectory 4.141 + before continuing with the current directory.</para> 4.142 + 4.143 + &interaction.filenames.dirs; 4.144 + </sect1> 4.145 + 4.146 + <sect1> 4.147 + <title>Running commands without any file names</title> 4.148 + 4.149 + <para id="x_547">Mercurial's commands that work with file names have useful 4.150 + default behaviors when you invoke them without providing any 4.151 + file names or patterns. What kind of behavior you should 4.152 + expect depends on what the command does. Here are a few rules 4.153 + of thumb you can use to predict what a command is likely to do 4.154 + if you don't give it any names to work with.</para> 4.155 + <itemizedlist> 4.156 + <listitem><para id="x_548">Most commands will operate on the entire working 4.157 + directory. This is what the <command role="hg-cmd">hg 4.158 + add</command> command does, for example.</para> 4.159 + </listitem> 4.160 + <listitem><para id="x_549">If the command has effects that are difficult or 4.161 + impossible to reverse, it will force you to explicitly 4.162 + provide at least one name or pattern (see below). This 4.163 + protects you from accidentally deleting files by running 4.164 + <command role="hg-cmd">hg remove</command> with no 4.165 + arguments, for example.</para> 4.166 + </listitem></itemizedlist> 4.167 + 4.168 + <para id="x_54a">It's easy to work around these default behaviors if they 4.169 + don't suit you. If a command normally operates on the whole 4.170 + working directory, you can invoke it on just the current 4.171 + directory and its subdirectories by giving it the name 4.172 + <quote><filename class="directory">.</filename></quote>.</para> 4.173 + 4.174 + &interaction.filenames.wdir-subdir; 4.175 + 4.176 + <para id="x_54b">Along the same lines, some commands normally print file 4.177 + names relative to the root of the repository, even if you're 4.178 + invoking them from a subdirectory. Such a command will print 4.179 + file names relative to your subdirectory if you give it explicit 4.180 + names. Here, we're going to run <command role="hg-cmd">hg 4.181 + status</command> from a subdirectory, and get it to operate on 4.182 + the entire working directory while printing file names relative 4.183 + to our subdirectory, by passing it the output of the <command 4.184 + role="hg-cmd">hg root</command> command.</para> 4.185 + 4.186 + &interaction.filenames.wdir-relname; 4.187 + </sect1> 4.188 + 4.189 + <sect1> 4.190 + <title>Telling you what's going on</title> 4.191 + 4.192 + <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the 4.193 + preceding section illustrates something else that's helpful 4.194 + about Mercurial commands. If a command operates on a file that 4.195 + you didn't name explicitly on the command line, it will usually 4.196 + print the name of the file, so that you will not be surprised 4.197 + what's going on.</para> 4.198 + 4.199 + <para id="x_54d">The principle here is of <emphasis>least 4.200 + surprise</emphasis>. If you've exactly named a file on the 4.201 + command line, there's no point in repeating it back at you. If 4.202 + Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g. 4.203 + because you provided no names, or a directory, or a pattern (see 4.204 + below), it is safest to tell you what files it's operating on.</para> 4.205 + 4.206 + <para id="x_54e">For commands that behave this way, you can silence them 4.207 + using the <option role="hg-opt-global">-q</option> option. You 4.208 + can also get them to print the name of every file, even those 4.209 + you've named explicitly, using the <option 4.210 + role="hg-opt-global">-v</option> option.</para> 4.211 + </sect1> 4.212 + 4.213 + <sect1> 4.214 + <title>Using patterns to identify files</title> 4.215 + 4.216 + <para id="x_54f">In addition to working with file and directory names, 4.217 + Mercurial lets you use <emphasis>patterns</emphasis> to identify 4.218 + files. Mercurial's pattern handling is expressive.</para> 4.219 + 4.220 + <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of 4.221 + matching file names to patterns normally falls to the shell. On 4.222 + these systems, you must explicitly tell Mercurial that a name is 4.223 + a pattern. On Windows, the shell does not expand patterns, so 4.224 + Mercurial will automatically identify names that are patterns, 4.225 + and expand them for you.</para> 4.226 + 4.227 + <para id="x_551">To provide a pattern in place of a regular name on the 4.228 + command line, the mechanism is simple:</para> 4.229 + <programlisting>syntax:patternbody</programlisting> 4.230 + <para id="x_552">That is, a pattern is identified by a short text string that 4.231 + says what kind of pattern this is, followed by a colon, followed 4.232 + by the actual pattern.</para> 4.233 + 4.234 + <para id="x_553">Mercurial supports two kinds of pattern syntax. The most 4.235 + frequently used is called <literal>glob</literal>; this is the 4.236 + same kind of pattern matching used by the Unix shell, and should 4.237 + be familiar to Windows command prompt users, too.</para> 4.238 + 4.239 + <para id="x_554">When Mercurial does automatic pattern matching on Windows, 4.240 + it uses <literal>glob</literal> syntax. You can thus omit the 4.241 + <quote><literal>glob:</literal></quote> prefix on Windows, but 4.242 + it's safe to use it, too.</para> 4.243 + 4.244 + <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets 4.245 + you specify patterns using regular expressions, also known as 4.246 + regexps.</para> 4.247 + 4.248 + <para id="x_556">By the way, in the examples that follow, notice that I'm 4.249 + careful to wrap all of my patterns in quote characters, so that 4.250 + they won't get expanded by the shell before Mercurial sees 4.251 + them.</para> 4.252 + 4.253 + <sect2> 4.254 + <title>Shell-style <literal>glob</literal> patterns</title> 4.255 + 4.256 + <para id="x_557">This is an overview of the kinds of patterns you can use 4.257 + when you're matching on glob patterns.</para> 4.258 + 4.259 + <para id="x_558">The <quote><literal>*</literal></quote> character matches 4.260 + any string, within a single directory.</para> 4.261 + 4.262 + &interaction.filenames.glob.star; 4.263 + 4.264 + <para id="x_559">The <quote><literal>**</literal></quote> pattern matches 4.265 + any string, and crosses directory boundaries. It's not a 4.266 + standard Unix glob token, but it's accepted by several popular 4.267 + Unix shells, and is very useful.</para> 4.268 + 4.269 + &interaction.filenames.glob.starstar; 4.270 + 4.271 + <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches 4.272 + any single character.</para> 4.273 + 4.274 + &interaction.filenames.glob.question; 4.275 + 4.276 + <para id="x_55b">The <quote><literal>[</literal></quote> character begins a 4.277 + <emphasis>character class</emphasis>. This matches any single 4.278 + character within the class. The class ends with a 4.279 + <quote><literal>]</literal></quote> character. A class may 4.280 + contain multiple <emphasis>range</emphasis>s of the form 4.281 + <quote><literal>a-f</literal></quote>, which is shorthand for 4.282 + <quote><literal>abcdef</literal></quote>.</para> 4.283 + 4.284 + &interaction.filenames.glob.range; 4.285 + 4.286 + <para id="x_55c">If the first character after the 4.287 + <quote><literal>[</literal></quote> in a character class is a 4.288 + <quote><literal>!</literal></quote>, it 4.289 + <emphasis>negates</emphasis> the class, making it match any 4.290 + single character not in the class.</para> 4.291 + 4.292 + <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of 4.293 + subpatterns, where the whole group matches if any subpattern 4.294 + in the group matches. The <quote><literal>,</literal></quote> 4.295 + character separates subpatterns, and 4.296 + <quote><literal>}</literal></quote> ends the group.</para> 4.297 + 4.298 + &interaction.filenames.glob.group; 4.299 + 4.300 + <sect3> 4.301 + <title>Watch out!</title> 4.302 + 4.303 + <para id="x_55e">Don't forget that if you want to match a pattern in any 4.304 + directory, you should not be using the 4.305 + <quote><literal>*</literal></quote> match-any token, as this 4.306 + will only match within one directory. Instead, use the 4.307 + <quote><literal>**</literal></quote> token. This small 4.308 + example illustrates the difference between the two.</para> 4.309 + 4.310 + &interaction.filenames.glob.star-starstar; 4.311 + </sect3> 4.312 + </sect2> 4.313 + 4.314 + <sect2> 4.315 + <title>Regular expression matching with <literal>re</literal> 4.316 + patterns</title> 4.317 + 4.318 + <para id="x_55f">Mercurial accepts the same regular expression syntax as 4.319 + the Python programming language (it uses Python's regexp 4.320 + engine internally). This is based on the Perl language's 4.321 + regexp syntax, which is the most popular dialect in use (it's 4.322 + also used in Java, for example).</para> 4.323 + 4.324 + <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail 4.325 + here, as regexps are not often used. Perl-style regexps are 4.326 + in any case already exhaustively documented on a multitude of 4.327 + web sites, and in many books. Instead, I will focus here on a 4.328 + few things you should know if you find yourself needing to use 4.329 + regexps with Mercurial.</para> 4.330 + 4.331 + <para id="x_561">A regexp is matched against an entire file name, relative 4.332 + to the root of the repository. In other words, even if you're 4.333 + already in subbdirectory <filename 4.334 + class="directory">foo</filename>, if you want to match files 4.335 + under this directory, your pattern must start with 4.336 + <quote><literal>foo/</literal></quote>.</para> 4.337 + 4.338 + <para id="x_562">One thing to note, if you're familiar with Perl-style 4.339 + regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 4.340 + That is, a regexp starts matching against the beginning of a 4.341 + string; it doesn't look for a match anywhere within the 4.342 + string. To match anywhere in a string, start your pattern 4.343 + with <quote><literal>.*</literal></quote>.</para> 4.344 + </sect2> 4.345 + </sect1> 4.346 + 4.347 + <sect1> 4.348 + <title>Filtering files</title> 4.349 + 4.350 + <para id="x_563">Not only does Mercurial give you a variety of ways to 4.351 + specify files; it lets you further winnow those files using 4.352 + <emphasis>filters</emphasis>. Commands that work with file 4.353 + names accept two filtering options.</para> 4.354 + <itemizedlist> 4.355 + <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or 4.356 + <option role="hg-opt-global">--include</option>, lets you 4.357 + specify a pattern that file names must match in order to be 4.358 + processed.</para> 4.359 + </listitem> 4.360 + <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or 4.361 + <option role="hg-opt-global">--exclude</option>, gives you a 4.362 + way to <emphasis>avoid</emphasis> processing files, if they 4.363 + match this pattern.</para> 4.364 + </listitem></itemizedlist> 4.365 + <para id="x_566">You can provide multiple <option 4.366 + role="hg-opt-global">-I</option> and <option 4.367 + role="hg-opt-global">-X</option> options on the command line, 4.368 + and intermix them as you please. Mercurial interprets the 4.369 + patterns you provide using glob syntax by default (but you can 4.370 + use regexps if you need to).</para> 4.371 + 4.372 + <para id="x_567">You can read a <option role="hg-opt-global">-I</option> 4.373 + filter as <quote>process only the files that match this 4.374 + filter</quote>.</para> 4.375 + 4.376 + &interaction.filenames.filter.include; 4.377 + 4.378 + <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best 4.379 + read as <quote>process only the files that don't match this 4.380 + pattern</quote>.</para> 4.381 + 4.382 + &interaction.filenames.filter.exclude; 4.383 + </sect1> 4.384 + 4.385 + <sect1> 4.386 + <title>Permanently ignoring unwanted files and directories</title> 4.387 + 4.388 + <para id="x_569">When you create a new repository, the chances are 4.389 + that over time it will grow to contain files that ought to 4.390 + <emphasis>not</emphasis> be managed by Mercurial, but which you 4.391 + don't want to see listed every time you run <command>hg 4.392 + status</command>. For instance, <quote>build products</quote> 4.393 + are files that are created as part of a build but which should 4.394 + not be managed by a revision control system. The most common 4.395 + build products are output files produced by software tools such 4.396 + as compilers. As another example, many text editors litter a 4.397 + directory with lock files, temporary working files, and backup 4.398 + files, which it also makes no sense to manage.</para> 4.399 + 4.400 + <para id="x_6b4">To have Mercurial permanently ignore such files, create a 4.401 + file named <filename>.hgignore</filename> in the root of your 4.402 + repository. You <emphasis>should</emphasis> <command>hg 4.403 + add</command> this file so that it gets tracked with the rest of 4.404 + your repository contents, since your collaborators will probably 4.405 + find it useful too.</para> 4.406 + 4.407 + <para id="x_6b5">By default, the <filename>.hgignore</filename> file should 4.408 + contain a list of regular expressions, one per line. Empty 4.409 + lines are skipped. Most people prefer to describe the files they 4.410 + want to ignore using the <quote>glob</quote> syntax that we 4.411 + described above, so a typical <filename>.hgignore</filename> 4.412 + file will start with this directive:</para> 4.413 + 4.414 + <programlisting>syntax: glob</programlisting> 4.415 + 4.416 + <para id="x_6b6">This tells Mercurial to interpret the lines that follow as 4.417 + glob patterns, not regular expressions.</para> 4.418 + 4.419 + <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename> 4.420 + file.</para> 4.421 + 4.422 + <programlisting>syntax: glob 4.423 +# This line is a comment, and will be skipped. 4.424 +# Empty lines are skipped too. 4.425 + 4.426 +# Backup files left behind by the Emacs editor. 4.427 +*~ 4.428 + 4.429 +# Lock files used by the Emacs editor. 4.430 +# Notice that the "#" character is quoted with a backslash. 4.431 +# This prevents it from being interpreted as starting a comment. 4.432 +.\#* 4.433 + 4.434 +# Temporary files used by the vim editor. 4.435 +.*.swp 4.436 + 4.437 +# A hidden file created by the Mac OS X Finder. 4.438 +.DS_Store 4.439 </programlisting> 4.440 -<para>That is, a pattern is identified by a short text string that says what 4.441 -kind of pattern this is, followed by a colon, followed by the actual 4.442 -pattern. 4.443 -</para> 4.444 - 4.445 -<para>Mercurial supports two kinds of pattern syntax. The most frequently 4.446 -used is called <literal>glob</literal>; this is the same kind of pattern 4.447 -matching used by the Unix shell, and should be familiar to Windows 4.448 -command prompt users, too. 4.449 -</para> 4.450 - 4.451 -<para>When Mercurial does automatic pattern matching on Windows, it uses 4.452 -<literal>glob</literal> syntax. You can thus omit the <quote><literal>glob:</literal></quote> prefix 4.453 -on Windows, but it's safe to use it, too. 4.454 -</para> 4.455 - 4.456 -<para>The <literal>re</literal> syntax is more powerful; it lets you specify patterns 4.457 -using regular expressions, also known as regexps. 4.458 -</para> 4.459 - 4.460 -<para>By the way, in the examples that follow, notice that I'm careful to 4.461 -wrap all of my patterns in quote characters, so that they won't get 4.462 -expanded by the shell before Mercurial sees them. 4.463 -</para> 4.464 - 4.465 -<sect2> 4.466 -<title>Shell-style <literal>glob</literal> patterns</title> 4.467 - 4.468 -<para>This is an overview of the kinds of patterns you can use when you're 4.469 -matching on glob patterns. 4.470 -</para> 4.471 - 4.472 -<para>The <quote><literal>*</literal></quote> character matches any string, within a single 4.473 -directory. 4.474 -<!-- &interaction.filenames.glob.star; --> 4.475 -</para> 4.476 - 4.477 -<para>The <quote><literal>**</literal></quote> pattern matches any string, and crosses directory 4.478 -boundaries. It's not a standard Unix glob token, but it's accepted by 4.479 -several popular Unix shells, and is very useful. 4.480 -<!-- &interaction.filenames.glob.starstar; --> 4.481 -</para> 4.482 - 4.483 -<para>The <quote><literal>?</literal></quote> pattern matches any single character. 4.484 -<!-- &interaction.filenames.glob.question; --> 4.485 -</para> 4.486 - 4.487 -<para>The <quote><literal>[</literal></quote> character begins a <emphasis>character class</emphasis>. This 4.488 -matches any single character within the class. The class ends with a 4.489 -<quote><literal>]</literal></quote> character. A class may contain multiple <emphasis>range</emphasis>s 4.490 -of the form <quote><literal>a-f</literal></quote>, which is shorthand for 4.491 -<quote><literal>abcdef</literal></quote>. 4.492 -<!-- &interaction.filenames.glob.range; --> 4.493 -If the first character after the <quote><literal>[</literal></quote> in a character class 4.494 -is a <quote><literal>!</literal></quote>, it <emphasis>negates</emphasis> the class, making it match any 4.495 -single character not in the class. 4.496 -</para> 4.497 - 4.498 -<para>A <quote><literal>{</literal></quote> begins a group of subpatterns, where the whole group 4.499 -matches if any subpattern in the group matches. The <quote><literal>,</literal></quote> 4.500 -character separates subpatterns, and <quote>\texttt{}}</quote> ends the group. 4.501 -<!-- &interaction.filenames.glob.group; --> 4.502 -</para> 4.503 - 4.504 -<sect3> 4.505 -<title>Watch out!</title> 4.506 - 4.507 -<para>Don't forget that if you want to match a pattern in any directory, you 4.508 -should not be using the <quote><literal>*</literal></quote> match-any token, as this will 4.509 -only match within one directory. Instead, use the <quote><literal>**</literal></quote> 4.510 -token. This small example illustrates the difference between the two. 4.511 -<!-- &interaction.filenames.glob.star-starstar; --> 4.512 -</para> 4.513 - 4.514 -</sect3> 4.515 -</sect2> 4.516 -<sect2> 4.517 -<title>Regular expression matching with <literal>re</literal> patterns</title> 4.518 - 4.519 -<para>Mercurial accepts the same regular expression syntax as the Python 4.520 -programming language (it uses Python's regexp engine internally). 4.521 -This is based on the Perl language's regexp syntax, which is the most 4.522 -popular dialect in use (it's also used in Java, for example). 4.523 -</para> 4.524 - 4.525 -<para>I won't discuss Mercurial's regexp dialect in any detail here, as 4.526 -regexps are not often used. Perl-style regexps are in any case 4.527 -already exhaustively documented on a multitude of web sites, and in 4.528 -many books. Instead, I will focus here on a few things you should 4.529 -know if you find yourself needing to use regexps with Mercurial. 4.530 -</para> 4.531 - 4.532 -<para>A regexp is matched against an entire file name, relative to the root 4.533 -of the repository. In other words, even if you're already in 4.534 -subbdirectory <filename class="directory">foo</filename>, if you want to match files under this 4.535 -directory, your pattern must start with <quote><literal>foo/</literal></quote>. 4.536 -</para> 4.537 - 4.538 -<para>One thing to note, if you're familiar with Perl-style regexps, is that 4.539 -Mercurial's are <emphasis>rooted</emphasis>. That is, a regexp starts matching 4.540 -against the beginning of a string; it doesn't look for a match 4.541 -anywhere within the string. To match anywhere in a string, start 4.542 -your pattern with <quote><literal>.*</literal></quote>. 4.543 -</para> 4.544 - 4.545 -</sect2> 4.546 -</sect1> 4.547 -<sect1> 4.548 -<title>Filtering files</title> 4.549 - 4.550 -<para>Not only does Mercurial give you a variety of ways to specify files; 4.551 -it lets you further winnow those files using <emphasis>filters</emphasis>. Commands 4.552 -that work with file names accept two filtering options. 4.553 -</para> 4.554 -<itemizedlist> 4.555 -<listitem><para><option role="hg-opt-global">-I</option>, or <option role="hg-opt-global">--include</option>, lets you specify a pattern 4.556 - that file names must match in order to be processed. 4.557 -</para> 4.558 -</listitem> 4.559 -<listitem><para><option role="hg-opt-global">-X</option>, or <option role="hg-opt-global">--exclude</option>, gives you a way to 4.560 - <emphasis>avoid</emphasis> processing files, if they match this pattern. 4.561 -</para> 4.562 -</listitem></itemizedlist> 4.563 -<para>You can provide multiple <option role="hg-opt-global">-I</option> and <option role="hg-opt-global">-X</option> options on the 4.564 -command line, and intermix them as you please. Mercurial interprets 4.565 -the patterns you provide using glob syntax by default (but you can use 4.566 -regexps if you need to). 4.567 -</para> 4.568 - 4.569 -<para>You can read a <option role="hg-opt-global">-I</option> filter as <quote>process only the files that 4.570 -match this filter</quote>. 4.571 -<!-- &interaction.filenames.filter.include; --> 4.572 -The <option role="hg-opt-global">-X</option> filter is best read as <quote>process only the files that 4.573 -don't match this pattern</quote>. 4.574 -<!-- &interaction.filenames.filter.exclude; --> 4.575 -</para> 4.576 - 4.577 -</sect1> 4.578 -<sect1> 4.579 -<title>Ignoring unwanted files and directories</title> 4.580 - 4.581 -<para>XXX. 4.582 -</para> 4.583 - 4.584 -</sect1> 4.585 -<sect1> 4.586 -<title>Case sensitivity</title> 4.587 -<para>\label{sec:names:case} 4.588 -</para> 4.589 - 4.590 -<para>If you're working in a mixed development environment that contains 4.591 -both Linux (or other Unix) systems and Macs or Windows systems, you 4.592 -should keep in the back of your mind the knowledge that they treat the 4.593 -case (<quote>N</quote> versus <quote>n</quote>) of file names in incompatible ways. This is 4.594 -not very likely to affect you, and it's easy to deal with if it does, 4.595 -but it could surprise you if you don't know about it. 4.596 -</para> 4.597 - 4.598 -<para>Operating systems and filesystems differ in the way they handle the 4.599 -<emphasis>case</emphasis> of characters in file and directory names. There are 4.600 -three common ways to handle case in names. 4.601 -</para> 4.602 -<itemizedlist> 4.603 -<listitem><para>Completely case insensitive. Uppercase and lowercase versions 4.604 - of a letter are treated as identical, both when creating a file and 4.605 - during subsequent accesses. This is common on older DOS-based 4.606 - systems. 4.607 -</para> 4.608 -</listitem> 4.609 -<listitem><para>Case preserving, but insensitive. When a file or directory is 4.610 - created, the case of its name is stored, and can be retrieved and 4.611 - displayed by the operating system. When an existing file is being 4.612 - looked up, its case is ignored. This is the standard arrangement on 4.613 - Windows and MacOS. The names <filename>foo</filename> and <filename>FoO</filename> 4.614 - identify the same file. This treatment of uppercase and lowercase 4.615 - letters as interchangeable is also referred to as \emph{case 4.616 - folding}. 4.617 -</para> 4.618 -</listitem> 4.619 -<listitem><para>Case sensitive. The case of a name is significant at all times. 4.620 - The names <filename>foo</filename> and {FoO} identify different files. This 4.621 - is the way Linux and Unix systems normally work. 4.622 -</para> 4.623 -</listitem></itemizedlist> 4.624 - 4.625 -<para>On Unix-like systems, it is possible to have any or all of the above 4.626 -ways of handling case in action at once. For example, if you use a 4.627 -USB thumb drive formatted with a FAT32 filesystem on a Linux system, 4.628 -Linux will handle names on that filesystem in a case preserving, but 4.629 -insensitive, way. 4.630 -</para> 4.631 - 4.632 -<sect2> 4.633 -<title>Safe, portable repository storage</title> 4.634 - 4.635 -<para>Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>. It 4.636 -translates file names so that they can be safely stored on both case 4.637 -sensitive and case insensitive filesystems. This means that you can 4.638 -use normal file copying tools to transfer a Mercurial repository onto, 4.639 -for example, a USB thumb drive, and safely move that drive and 4.640 -repository back and forth between a Mac, a PC running Windows, and a 4.641 -Linux box. 4.642 -</para> 4.643 - 4.644 -</sect2> 4.645 -<sect2> 4.646 -<title>Detecting case conflicts</title> 4.647 - 4.648 -<para>When operating in the working directory, Mercurial honours the naming 4.649 -policy of the filesystem where the working directory is located. If 4.650 -the filesystem is case preserving, but insensitive, Mercurial will 4.651 -treat names that differ only in case as the same. 4.652 -</para> 4.653 - 4.654 -<para>An important aspect of this approach is that it is possible to commit 4.655 -a changeset on a case sensitive (typically Linux or Unix) filesystem 4.656 -that will cause trouble for users on case insensitive (usually Windows 4.657 -and MacOS) users. If a Linux user commits changes to two files, one 4.658 -named <filename>myfile.c</filename> and the other named <filename>MyFile.C</filename>, 4.659 -they will be stored correctly in the repository. And in the working 4.660 -directories of other Linux users, they will be correctly represented 4.661 -as separate files. 4.662 -</para> 4.663 - 4.664 -<para>If a Windows or Mac user pulls this change, they will not initially 4.665 -have a problem, because Mercurial's repository storage mechanism is 4.666 -case safe. However, once they try to <command role="hg-cmd">hg update</command> the working 4.667 -directory to that changeset, or <command role="hg-cmd">hg merge</command> with that changeset, 4.668 -Mercurial will spot the conflict between the two file names that the 4.669 -filesystem would treat as the same, and forbid the update or merge 4.670 -from occurring. 4.671 -</para> 4.672 - 4.673 -</sect2> 4.674 -<sect2> 4.675 -<title>Fixing a case conflict</title> 4.676 - 4.677 -<para>If you are using Windows or a Mac in a mixed environment where some of 4.678 -your collaborators are using Linux or Unix, and Mercurial reports a 4.679 -case folding conflict when you try to <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg merge</command>, 4.680 -the procedure to fix the problem is simple. 4.681 -</para> 4.682 - 4.683 -<para>Just find a nearby Linux or Unix box, clone the problem repository 4.684 -onto it, and use Mercurial's <command role="hg-cmd">hg rename</command> command to change the 4.685 -names of any offending files or directories so that they will no 4.686 -longer cause case folding conflicts. Commit this change, <command role="hg-cmd">hg pull</command> 4.687 -or <command role="hg-cmd">hg push</command> it across to your Windows or MacOS system, and 4.688 -<command role="hg-cmd">hg update</command> to the revision with the non-conflicting names. 4.689 -</para> 4.690 - 4.691 -<para>The changeset with case-conflicting names will remain in your 4.692 -project's history, and you still won't be able to <command role="hg-cmd">hg update</command> your 4.693 -working directory to that changeset on a Windows or MacOS system, but 4.694 -you can continue development unimpeded. 4.695 -</para> 4.696 - 4.697 -<note> 4.698 -<para> Prior to version 0.9.3, Mercurial did not use a case safe repository 4.699 - storage mechanism, and did not detect case folding conflicts. If 4.700 - you are using an older version of Mercurial on Windows or MacOS, I 4.701 - strongly recommend that you upgrade. 4.702 -</para> 4.703 -</note> 4.704 - 4.705 -</sect2> 4.706 -</sect1> 4.707 + </sect1> 4.708 + 4.709 + <sect1 id="sec:names:case"> 4.710 + <title>Case sensitivity</title> 4.711 + 4.712 + <para id="x_56a">If you're working in a mixed development environment that 4.713 + contains both Linux (or other Unix) systems and Macs or Windows 4.714 + systems, you should keep in the back of your mind the knowledge 4.715 + that they treat the case (<quote>N</quote> versus 4.716 + <quote>n</quote>) of file names in incompatible ways. This is 4.717 + not very likely to affect you, and it's easy to deal with if it 4.718 + does, but it could surprise you if you don't know about 4.719 + it.</para> 4.720 + 4.721 + <para id="x_56b">Operating systems and filesystems differ in the way they 4.722 + handle the <emphasis>case</emphasis> of characters in file and 4.723 + directory names. There are three common ways to handle case in 4.724 + names.</para> 4.725 + <itemizedlist> 4.726 + <listitem><para id="x_56c">Completely case insensitive. Uppercase and 4.727 + lowercase versions of a letter are treated as identical, 4.728 + both when creating a file and during subsequent accesses. 4.729 + This is common on older DOS-based systems.</para> 4.730 + </listitem> 4.731 + <listitem><para id="x_56d">Case preserving, but insensitive. When a file 4.732 + or directory is created, the case of its name is stored, and 4.733 + can be retrieved and displayed by the operating system. 4.734 + When an existing file is being looked up, its case is 4.735 + ignored. This is the standard arrangement on Windows and 4.736 + MacOS. The names <filename>foo</filename> and 4.737 + <filename>FoO</filename> identify the same file. This 4.738 + treatment of uppercase and lowercase letters as 4.739 + interchangeable is also referred to as <emphasis>case 4.740 + folding</emphasis>.</para> 4.741 + </listitem> 4.742 + <listitem><para id="x_56e">Case sensitive. The case of a name 4.743 + is significant at all times. The names 4.744 + <filename>foo</filename> and <filename>FoO</filename> 4.745 + identify different files. This is the way Linux and Unix 4.746 + systems normally work.</para> 4.747 + </listitem></itemizedlist> 4.748 + 4.749 + <para id="x_56f">On Unix-like systems, it is possible to have any or all of 4.750 + the above ways of handling case in action at once. For example, 4.751 + if you use a USB thumb drive formatted with a FAT32 filesystem 4.752 + on a Linux system, Linux will handle names on that filesystem in 4.753 + a case preserving, but insensitive, way.</para> 4.754 + 4.755 + <sect2> 4.756 + <title>Safe, portable repository storage</title> 4.757 + 4.758 + <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case 4.759 + safe</emphasis>. It translates file names so that they can 4.760 + be safely stored on both case sensitive and case insensitive 4.761 + filesystems. This means that you can use normal file copying 4.762 + tools to transfer a Mercurial repository onto, for example, a 4.763 + USB thumb drive, and safely move that drive and repository 4.764 + back and forth between a Mac, a PC running Windows, and a 4.765 + Linux box.</para> 4.766 + 4.767 + </sect2> 4.768 + <sect2> 4.769 + <title>Detecting case conflicts</title> 4.770 + 4.771 + <para id="x_571">When operating in the working directory, Mercurial honours 4.772 + the naming policy of the filesystem where the working 4.773 + directory is located. If the filesystem is case preserving, 4.774 + but insensitive, Mercurial will treat names that differ only 4.775 + in case as the same.</para> 4.776 + 4.777 + <para id="x_572">An important aspect of this approach is that it is 4.778 + possible to commit a changeset on a case sensitive (typically 4.779 + Linux or Unix) filesystem that will cause trouble for users on 4.780 + case insensitive (usually Windows and MacOS) users. If a 4.781 + Linux user commits changes to two files, one named 4.782 + <filename>myfile.c</filename> and the other named 4.783 + <filename>MyFile.C</filename>, they will be stored correctly 4.784 + in the repository. And in the working directories of other 4.785 + Linux users, they will be correctly represented as separate 4.786 + files.</para> 4.787 + 4.788 + <para id="x_573">If a Windows or Mac user pulls this change, they will not 4.789 + initially have a problem, because Mercurial's repository 4.790 + storage mechanism is case safe. However, once they try to 4.791 + <command role="hg-cmd">hg update</command> the working 4.792 + directory to that changeset, or <command role="hg-cmd">hg 4.793 + merge</command> with that changeset, Mercurial will spot the 4.794 + conflict between the two file names that the filesystem would 4.795 + treat as the same, and forbid the update or merge from 4.796 + occurring.</para> 4.797 + </sect2> 4.798 + 4.799 + <sect2> 4.800 + <title>Fixing a case conflict</title> 4.801 + 4.802 + <para id="x_574">If you are using Windows or a Mac in a mixed environment 4.803 + where some of your collaborators are using Linux or Unix, and 4.804 + Mercurial reports a case folding conflict when you try to 4.805 + <command role="hg-cmd">hg update</command> or <command 4.806 + role="hg-cmd">hg merge</command>, the procedure to fix the 4.807 + problem is simple.</para> 4.808 + 4.809 + <para id="x_575">Just find a nearby Linux or Unix box, clone the problem 4.810 + repository onto it, and use Mercurial's <command 4.811 + role="hg-cmd">hg rename</command> command to change the 4.812 + names of any offending files or directories so that they will 4.813 + no longer cause case folding conflicts. Commit this change, 4.814 + <command role="hg-cmd">hg pull</command> or <command 4.815 + role="hg-cmd">hg push</command> it across to your Windows or 4.816 + MacOS system, and <command role="hg-cmd">hg update</command> 4.817 + to the revision with the non-conflicting names.</para> 4.818 + 4.819 + <para id="x_576">The changeset with case-conflicting names will remain in 4.820 + your project's history, and you still won't be able to 4.821 + <command role="hg-cmd">hg update</command> your working 4.822 + directory to that changeset on a Windows or MacOS system, but 4.823 + you can continue development unimpeded.</para> 4.824 + </sect2> 4.825 + </sect1> 4.826 </chapter> 4.827 4.828 <!-- 4.829 local variables: 4.830 sgml-parent-document: ("00book.xml" "book" "chapter") 4.831 end: 4.832 ---> 4.833 \ No newline at end of file 4.834 +-->
5.1 --- a/fr/ch08-branch.xml Wed Sep 09 15:25:09 2009 +0200 5.2 +++ b/fr/ch08-branch.xml Wed Sep 09 16:07:36 2009 +0200 5.3 @@ -1,473 +1,533 @@ 5.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 5.5 5.6 -<chapter> 5.7 -<title>Managing releases and branchy development</title> 5.8 -<para>\label{chap:branch}</para> 5.9 - 5.10 -<para>Mercurial provides several mechanisms for you to manage a project that 5.11 -is making progress on multiple fronts at once. To understand these 5.12 -mechanisms, let's first take a brief look at a fairly normal software 5.13 -project structure.</para> 5.14 - 5.15 -<para>Many software projects issue periodic <quote>major</quote> releases that contain 5.16 -substantial new features. In parallel, they may issue <quote>minor</quote> 5.17 -releases. These are usually identical to the major releases off which 5.18 -they're based, but with a few bugs fixed.</para> 5.19 - 5.20 -<para>In this chapter, we'll start by talking about how to keep records of 5.21 -project milestones such as releases. We'll then continue on to talk 5.22 -about the flow of work between different phases of a project, and how 5.23 -Mercurial can help you to isolate and manage this work.</para> 5.24 - 5.25 -<sect1> 5.26 -<title>Giving a persistent name to a revision</title> 5.27 - 5.28 -<para>Once you decide that you'd like to call a particular revision a 5.29 -<quote>release</quote>, it's a good idea to record the identity of that revision. 5.30 -This will let you reproduce that release at a later date, for whatever 5.31 -purpose you might need at the time (reproducing a bug, porting to a 5.32 -new platform, etc). 5.33 -<!-- &interaction.tag.init; --></para> 5.34 - 5.35 -<para>Mercurial lets you give a permanent name to any revision using the 5.36 -<command role="hg-cmd">hg tag</command> command. Not surprisingly, these names are called 5.37 -<quote>tags</quote>. 5.38 -<!-- &interaction.tag.tag; --></para> 5.39 - 5.40 -<para>A tag is nothing more than a <quote>symbolic name</quote> for a revision. Tags 5.41 -exist purely for your convenience, so that you have a handy permanent 5.42 -way to refer to a revision; Mercurial doesn't interpret the tag names 5.43 -you use in any way. Neither does Mercurial place any restrictions on 5.44 -the name of a tag, beyond a few that are necessary to ensure that a 5.45 -tag can be parsed unambiguously. A tag name cannot contain any of the 5.46 -following characters:</para> 5.47 -<itemizedlist> 5.48 -<listitem><para>Colon (ASCII 58, <quote><literal>:</literal></quote>)</para> 5.49 -</listitem> 5.50 -<listitem><para>Carriage return (ASCII 13, <quote><literal>\r</literal></quote>) 5.51 -</para> 5.52 -</listitem> 5.53 -<listitem><para>Newline (ASCII 10, <quote><literal>\n</literal></quote>) 5.54 -</para> 5.55 -</listitem></itemizedlist> 5.56 - 5.57 -<para>You can use the <command role="hg-cmd">hg tags</command> command to display the tags present in 5.58 -your repository. In the output, each tagged revision is identified 5.59 -first by its name, then by revision number, and finally by the unique 5.60 -hash of the revision. 5.61 -<!-- &interaction.tag.tags; --> 5.62 -Notice that <literal>tip</literal> is listed in the output of <command role="hg-cmd">hg tags</command>. The 5.63 -<literal>tip</literal> tag is a special <quote>floating</quote> tag, which always 5.64 -identifies the newest revision in the repository. 5.65 -</para> 5.66 - 5.67 -<para>In the output of the <command role="hg-cmd">hg tags</command> command, tags are listed in reverse 5.68 -order, by revision number. This usually means that recent tags are 5.69 -listed before older tags. It also means that <literal>tip</literal> is always 5.70 -going to be the first tag listed in the output of <command role="hg-cmd">hg tags</command>. 5.71 -</para> 5.72 - 5.73 -<para>When you run <command role="hg-cmd">hg log</command>, if it displays a revision that has tags 5.74 -associated with it, it will print those tags. 5.75 -<!-- &interaction.tag.log; --> 5.76 -</para> 5.77 - 5.78 -<para>Any time you need to provide a revision ID to a Mercurial command, the 5.79 -command will accept a tag name in its place. Internally, Mercurial 5.80 -will translate your tag name into the corresponding revision ID, then 5.81 -use that. 5.82 -<!-- &interaction.tag.log.v1.0; --> 5.83 -</para> 5.84 - 5.85 -<para>There's no limit on the number of tags you can have in a repository, 5.86 -or on the number of tags that a single revision can have. As a 5.87 -practical matter, it's not a great idea to have <quote>too many</quote> (a number 5.88 -which will vary from project to project), simply because tags are 5.89 -supposed to help you to find revisions. If you have lots of tags, the 5.90 -ease of using them to identify revisions diminishes rapidly. 5.91 -</para> 5.92 - 5.93 -<para>For example, if your project has milestones as frequent as every few 5.94 -days, it's perfectly reasonable to tag each one of those. But if you 5.95 -have a continuous build system that makes sure every revision can be 5.96 -built cleanly, you'd be introducing a lot of noise if you were to tag 5.97 -every clean build. Instead, you could tag failed builds (on the 5.98 -assumption that they're rare!), or simply not use tags to track 5.99 -buildability. 5.100 -</para> 5.101 - 5.102 -<para>If you want to remove a tag that you no longer want, use 5.103 -<command role="hg-cmd">hg tag --remove</command>. 5.104 -<!-- &interaction.tag.remove; --> 5.105 -You can also modify a tag at any time, so that it identifies a 5.106 -different revision, by simply issuing a new <command role="hg-cmd">hg tag</command> command. 5.107 -You'll have to use the <option role="hg-opt-tag">-f</option> option to tell Mercurial that 5.108 -you <emphasis>really</emphasis> want to update the tag. 5.109 -<!-- &interaction.tag.replace; --> 5.110 -There will still be a permanent record of the previous identity of the 5.111 -tag, but Mercurial will no longer use it. There's thus no penalty to 5.112 -tagging the wrong revision; all you have to do is turn around and tag 5.113 -the correct revision once you discover your error. 5.114 -</para> 5.115 - 5.116 -<para>Mercurial stores tags in a normal revision-controlled file in your 5.117 -repository. If you've created any tags, you'll find them in a file 5.118 -named <filename role="special">.hgtags</filename>. When you run the <command role="hg-cmd">hg tag</command> command, 5.119 -Mercurial modifies this file, then automatically commits the change to 5.120 -it. This means that every time you run <command role="hg-cmd">hg tag</command>, you'll see a 5.121 -corresponding changeset in the output of <command role="hg-cmd">hg log</command>. 5.122 -<!-- &interaction.tag.tip; --> 5.123 -</para> 5.124 - 5.125 -<sect2> 5.126 -<title>Handling tag conflicts during a merge</title> 5.127 - 5.128 -<para>You won't often need to care about the <filename role="special">.hgtags</filename> file, but 5.129 -it sometimes makes its presence known during a merge. The format of 5.130 -the file is simple: it consists of a series of lines. Each line 5.131 -starts with a changeset hash, followed by a space, followed by the 5.132 -name of a tag. 5.133 -</para> 5.134 - 5.135 -<para>If you're resolving a conflict in the <filename role="special">.hgtags</filename> file during 5.136 -a merge, there's one twist to modifying the <filename role="special">.hgtags</filename> file: 5.137 -when Mercurial is parsing the tags in a repository, it <emphasis>never</emphasis> 5.138 -reads the working copy of the <filename role="special">.hgtags</filename> file. Instead, it 5.139 -reads the <emphasis>most recently committed</emphasis> revision of the file. 5.140 -</para> 5.141 - 5.142 -<para>An unfortunate consequence of this design is that you can't actually 5.143 -verify that your merged <filename role="special">.hgtags</filename> file is correct until 5.144 -<emphasis>after</emphasis> you've committed a change. So if you find yourself 5.145 -resolving a conflict on <filename role="special">.hgtags</filename> during a merge, be sure to 5.146 -run <command role="hg-cmd">hg tags</command> after you commit. If it finds an error in the 5.147 -<filename role="special">.hgtags</filename> file, it will report the location of the error, 5.148 -which you can then fix and commit. You should then run <command role="hg-cmd">hg tags</command> 5.149 -again, just to be sure that your fix is correct. 5.150 -</para> 5.151 - 5.152 -</sect2> 5.153 -<sect2> 5.154 -<title>Tags and cloning</title> 5.155 - 5.156 -<para>You may have noticed that the <command role="hg-cmd">hg clone</command> command has a 5.157 -<option role="hg-opt-clone">-r</option> option that lets you clone an exact copy of the 5.158 -repository as of a particular changeset. The new clone will not 5.159 -contain any project history that comes after the revision you 5.160 -specified. This has an interaction with tags that can surprise the 5.161 -unwary. 5.162 -</para> 5.163 - 5.164 -<para>Recall that a tag is stored as a revision to the <filename role="special">.hgtags</filename> 5.165 -file, so that when you create a tag, the changeset in which it's 5.166 -recorded necessarily refers to an older changeset. When you run 5.167 -<command role="hg-cmd">hg clone -r foo</command> to clone a repository as of tag 5.168 -<literal>foo</literal>, the new clone \emph{will not contain the history that 5.169 - created the tag} that you used to clone the repository. The result 5.170 -is that you'll get exactly the right subset of the project's history 5.171 -in the new repository, but <emphasis>not</emphasis> the tag you might have expected. 5.172 -</para> 5.173 - 5.174 -</sect2> 5.175 -<sect2> 5.176 -<title>When permanent tags are too much</title> 5.177 - 5.178 -<para>Since Mercurial's tags are revision controlled and carried around with 5.179 -a project's history, everyone you work with will see the tags you 5.180 -create. But giving names to revisions has uses beyond simply noting 5.181 -that revision <literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>. If 5.182 -you're trying to track down a subtle bug, you might want a tag to 5.183 -remind you of something like <quote>Anne saw the symptoms with this 5.184 -revision</quote>. 5.185 -</para> 5.186 - 5.187 -<para>For cases like this, what you might want to use are <emphasis>local</emphasis> tags. 5.188 -You can create a local tag with the <option role="hg-opt-tag">-l</option> option to the 5.189 -<command role="hg-cmd">hg tag</command> command. This will store the tag in a file called 5.190 -<filename role="special">.hg/localtags</filename>. Unlike <filename role="special">.hgtags</filename>, 5.191 -<filename role="special">.hg/localtags</filename> is not revision controlled. Any tags you 5.192 -create using <option role="hg-opt-tag">-l</option> remain strictly local to the repository 5.193 -you're currently working in. 5.194 -</para> 5.195 - 5.196 -</sect2> 5.197 -</sect1> 5.198 -<sect1> 5.199 -<title>The flow of changes&emdash;big picture vs. little</title> 5.200 - 5.201 -<para>To return to the outline I sketched at the beginning of a chapter, 5.202 -let's think about a project that has multiple concurrent pieces of 5.203 -work under development at once. 5.204 -</para> 5.205 - 5.206 -<para>There might be a push for a new <quote>main</quote> release; a new minor bugfix 5.207 -release to the last main release; and an unexpected <quote>hot fix</quote> to an 5.208 -old release that is now in maintenance mode. 5.209 -</para> 5.210 - 5.211 -<para>The usual way people refer to these different concurrent directions of 5.212 -development is as <quote>branches</quote>. However, we've already seen numerous 5.213 -times that Mercurial treats <emphasis>all of history</emphasis> as a series of 5.214 -branches and merges. Really, what we have here is two ideas that are 5.215 -peripherally related, but which happen to share a name. 5.216 -</para> 5.217 -<itemizedlist> 5.218 -<listitem><para><quote>Big picture</quote> branches represent the sweep of a project's 5.219 - evolution; people give them names, and talk about them in 5.220 - conversation. 5.221 -</para> 5.222 -</listitem> 5.223 -<listitem><para><quote>Little picture</quote> branches are artefacts of the day-to-day 5.224 - activity of developing and merging changes. They expose the 5.225 - narrative of how the code was developed. 5.226 -</para> 5.227 -</listitem></itemizedlist> 5.228 - 5.229 -</sect1> 5.230 -<sect1> 5.231 -<title>Managing big-picture branches in repositories</title> 5.232 - 5.233 -<para>The easiest way to isolate a <quote>big picture</quote> branch in Mercurial is in 5.234 -a dedicated repository. If you have an existing shared 5.235 -repository&emdash;let's call it <literal>myproject</literal>&emdash;that reaches a <quote>1.0</quote> 5.236 -milestone, you can start to prepare for future maintenance releases on 5.237 -top of version 1.0 by tagging the revision from which you prepared 5.238 -the 1.0 release. 5.239 -<!-- &interaction.branch-repo.tag; --> 5.240 -You can then clone a new shared <literal>myproject-1.0.1</literal> repository as 5.241 -of that tag. 5.242 -<!-- &interaction.branch-repo.clone; --> 5.243 -</para> 5.244 - 5.245 -<para>Afterwards, if someone needs to work on a bug fix that ought to go 5.246 -into an upcoming 1.0.1 minor release, they clone the 5.247 -<literal>myproject-1.0.1</literal> repository, make their changes, and push them 5.248 -back. 5.249 -<!-- &interaction.branch-repo.bugfix; --> 5.250 -Meanwhile, development for the next major release can continue, 5.251 -isolated and unabated, in the <literal>myproject</literal> repository. 5.252 -<!-- &interaction.branch-repo.new; --> 5.253 -</para> 5.254 - 5.255 -</sect1> 5.256 -<sect1> 5.257 -<title>Don't repeat yourself: merging across branches</title> 5.258 - 5.259 -<para>In many cases, if you have a bug to fix on a maintenance branch, the 5.260 -chances are good that the bug exists on your project's main branch 5.261 -(and possibly other maintenance branches, too). It's a rare developer 5.262 -who wants to fix the same bug multiple times, so let's look at a few 5.263 -ways that Mercurial can help you to manage these bugfixes without 5.264 -duplicating your work. 5.265 -</para> 5.266 - 5.267 -<para>In the simplest instance, all you need to do is pull changes from your 5.268 -maintenance branch into your local clone of the target branch. 5.269 -<!-- &interaction.branch-repo.pull; --> 5.270 -You'll then need to merge the heads of the two branches, and push back 5.271 -to the main branch. 5.272 -<!-- &interaction.branch-repo.merge; --> 5.273 -</para> 5.274 - 5.275 -</sect1> 5.276 -<sect1> 5.277 -<title>Naming branches within one repository</title> 5.278 - 5.279 -<para>In most instances, isolating branches in repositories is the right 5.280 -approach. Its simplicity makes it easy to understand; and so it's 5.281 -hard to make mistakes. There's a one-to-one relationship between 5.282 -branches you're working in and directories on your system. This lets 5.283 -you use normal (non-Mercurial-aware) tools to work on files within a 5.284 -branch/repository. 5.285 -</para> 5.286 - 5.287 -<para>If you're more in the <quote>power user</quote> category (<emphasis>and</emphasis> your 5.288 -collaborators are too), there is an alternative way of handling 5.289 -branches that you can consider. I've already mentioned the 5.290 -human-level distinction between <quote>small picture</quote> and <quote>big picture</quote> 5.291 -branches. While Mercurial works with multiple <quote>small picture</quote> 5.292 -branches in a repository all the time (for example after you pull 5.293 -changes in, but before you merge them), it can <emphasis>also</emphasis> work with 5.294 -multiple <quote>big picture</quote> branches. 5.295 -</para> 5.296 - 5.297 -<para>The key to working this way is that Mercurial lets you assign a 5.298 -persistent <emphasis>name</emphasis> to a branch. There always exists a branch 5.299 -named <literal>default</literal>. Even before you start naming branches 5.300 -yourself, you can find traces of the <literal>default</literal> branch if you 5.301 -look for them. 5.302 -</para> 5.303 - 5.304 -<para>As an example, when you run the <command role="hg-cmd">hg commit</command> command, and it pops up 5.305 -your editor so that you can enter a commit message, look for a line 5.306 -that contains the text <quote><literal>HG: branch default</literal></quote> at the bottom. 5.307 -This is telling you that your commit will occur on the branch named 5.308 -<literal>default</literal>. 5.309 -</para> 5.310 - 5.311 -<para>To start working with named branches, use the <command role="hg-cmd">hg branches</command> 5.312 -command. This command lists the named branches already present in 5.313 -your repository, telling you which changeset is the tip of each. 5.314 -<!-- &interaction.branch-named.branches; --> 5.315 -Since you haven't created any named branches yet, the only one that 5.316 -exists is <literal>default</literal>. 5.317 -</para> 5.318 - 5.319 -<para>To find out what the <quote>current</quote> branch is, run the <command role="hg-cmd">hg branch</command> 5.320 -command, giving it no arguments. This tells you what branch the 5.321 -parent of the current changeset is on. 5.322 -<!-- &interaction.branch-named.branch; --> 5.323 -</para> 5.324 - 5.325 -<para>To create a new branch, run the <command role="hg-cmd">hg branch</command> command again. This 5.326 -time, give it one argument: the name of the branch you want to create. 5.327 -<!-- &interaction.branch-named.create; --> 5.328 -</para> 5.329 - 5.330 -<para>After you've created a branch, you might wonder what effect the 5.331 -<command role="hg-cmd">hg branch</command> command has had. What do the <command role="hg-cmd">hg status</command> and 5.332 -<command role="hg-cmd">hg tip</command> commands report? 5.333 -<!-- &interaction.branch-named.status; --> 5.334 -Nothing has changed in the working directory, and there's been no new 5.335 -history created. As this suggests, running the <command role="hg-cmd">hg branch</command> command 5.336 -has no permanent effect; it only tells Mercurial what branch name to 5.337 -use the <emphasis>next</emphasis> time you commit a changeset. 5.338 -</para> 5.339 - 5.340 -<para>When you commit a change, Mercurial records the name of the branch on 5.341 -which you committed. Once you've switched from the <literal>default</literal> 5.342 -branch to another and committed, you'll see the name of the new branch 5.343 -show up in the output of <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg tip</command>, and other commands 5.344 -that display the same kind of output. 5.345 -<!-- &interaction.branch-named.commit; --> 5.346 -The <command role="hg-cmd">hg log</command>-like commands will print the branch name of every 5.347 -changeset that's not on the <literal>default</literal> branch. As a result, if 5.348 -you never use named branches, you'll never see this information. 5.349 -</para> 5.350 - 5.351 -<para>Once you've named a branch and committed a change with that name, 5.352 -every subsequent commit that descends from that change will inherit 5.353 -the same branch name. You can change the name of a branch at any 5.354 -time, using the <command role="hg-cmd">hg branch</command> command. 5.355 -<!-- &interaction.branch-named.rebranch; --> 5.356 -In practice, this is something you won't do very often, as branch 5.357 -names tend to have fairly long lifetimes. (This isn't a rule, just an 5.358 -observation.) 5.359 -</para> 5.360 - 5.361 -</sect1> 5.362 -<sect1> 5.363 -<title>Dealing with multiple named branches in a repository</title> 5.364 - 5.365 -<para>If you have more than one named branch in a repository, Mercurial will 5.366 -remember the branch that your working directory on when you start a 5.367 -command like <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg pull -u</command>. It will update 5.368 -the working directory to the tip of this branch, no matter what the 5.369 -<quote>repo-wide</quote> tip is. To update to a revision that's on a different 5.370 -named branch, you may need to use the <option role="hg-opt-update">-C</option> option to 5.371 -<command role="hg-cmd">hg update</command>. 5.372 -</para> 5.373 - 5.374 -<para>This behaviour is a little subtle, so let's see it in action. First, 5.375 -let's remind ourselves what branch we're currently on, and what 5.376 -branches are in our repository. 5.377 -<!-- &interaction.branch-named.parents; --> 5.378 -We're on the <literal>bar</literal> branch, but there also exists an older 5.379 -<command role="hg-cmd">hg foo</command> branch. 5.380 -</para> 5.381 - 5.382 -<para>We can <command role="hg-cmd">hg update</command> back and forth between the tips of the 5.383 -<literal>foo</literal> and <literal>bar</literal> branches without needing to use the 5.384 -<option role="hg-opt-update">-C</option> option, because this only involves going backwards 5.385 -and forwards linearly through our change history. 5.386 -<!-- &interaction.branch-named.update-switchy; --> 5.387 -</para> 5.388 - 5.389 -<para>If we go back to the <literal>foo</literal> branch and then run <command role="hg-cmd">hg update</command>, 5.390 -it will keep us on <literal>foo</literal>, not move us to the tip of 5.391 -<literal>bar</literal>. 5.392 -<!-- &interaction.branch-named.update-nothing; --> 5.393 -</para> 5.394 - 5.395 -<para>Committing a new change on the <literal>foo</literal> branch introduces a new 5.396 -head. 5.397 -<!-- &interaction.branch-named.foo-commit; --> 5.398 -</para> 5.399 - 5.400 -</sect1> 5.401 -<sect1> 5.402 -<title>Branch names and merging</title> 5.403 - 5.404 -<para>As you've probably noticed, merges in Mercurial are not symmetrical. 5.405 -Let's say our repository has two heads, 17 and 23. If I 5.406 -<command role="hg-cmd">hg update</command> to 17 and then <command role="hg-cmd">hg merge</command> with 23, Mercurial records 5.407 -17 as the first parent of the merge, and 23 as the second. Whereas if 5.408 -I <command role="hg-cmd">hg update</command> to 23 and then <command role="hg-cmd">hg merge</command> with 17, it records 23 5.409 -as the first parent, and 17 as the second. 5.410 -</para> 5.411 - 5.412 -<para>This affects Mercurial's choice of branch name when you merge. After 5.413 -a merge, Mercurial will retain the branch name of the first parent 5.414 -when you commit the result of the merge. If your first parent's 5.415 -branch name is <literal>foo</literal>, and you merge with <literal>bar</literal>, the 5.416 -branch name will still be <literal>foo</literal> after you merge. 5.417 -</para> 5.418 - 5.419 -<para>It's not unusual for a repository to contain multiple heads, each with 5.420 -the same branch name. Let's say I'm working on the <literal>foo</literal> 5.421 -branch, and so are you. We commit different changes; I pull your 5.422 -changes; I now have two heads, each claiming to be on the <literal>foo</literal> 5.423 -branch. The result of a merge will be a single head on the 5.424 -<literal>foo</literal> branch, as you might hope. 5.425 -</para> 5.426 - 5.427 -<para>But if I'm working on the <literal>bar</literal> branch, and I merge work from 5.428 -the <literal>foo</literal> branch, the result will remain on the <literal>bar</literal> 5.429 -branch. 5.430 -<!-- &interaction.branch-named.merge; --> 5.431 -</para> 5.432 - 5.433 -<para>To give a more concrete example, if I'm working on the 5.434 -<literal>bleeding-edge</literal> branch, and I want to bring in the latest fixes 5.435 -from the <literal>stable</literal> branch, Mercurial will choose the <quote>right</quote> 5.436 -(<literal>bleeding-edge</literal>) branch name when I pull and merge from 5.437 -<literal>stable</literal>. 5.438 -</para> 5.439 - 5.440 -</sect1> 5.441 -<sect1> 5.442 -<title>Branch naming is generally useful</title> 5.443 - 5.444 -<para>You shouldn't think of named branches as applicable only to situations 5.445 -where you have multiple long-lived branches cohabiting in a single 5.446 -repository. They're very useful even in the one-branch-per-repository 5.447 -case. 5.448 -</para> 5.449 - 5.450 -<para>In the simplest case, giving a name to each branch gives you a 5.451 -permanent record of which branch a changeset originated on. This 5.452 -gives you more context when you're trying to follow the history of a 5.453 -long-lived branchy project. 5.454 -</para> 5.455 - 5.456 -<para>If you're working with shared repositories, you can set up a 5.457 -<literal role="hook">pretxnchangegroup</literal> hook on each that will block incoming changes 5.458 -that have the <quote>wrong</quote> branch name. This provides a simple, but 5.459 -effective, defence against people accidentally pushing changes from a 5.460 -<quote>bleeding edge</quote> branch to a <quote>stable</quote> branch. Such a hook might 5.461 -look like this inside the shared repo's <filename role="special"> /.hgrc</filename>. 5.462 -</para> 5.463 -<programlisting> 5.464 -<para> [hooks] 5.465 - pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch 5.466 -</para> 5.467 -</programlisting> 5.468 - 5.469 -</sect1> 5.470 +<chapter id="chap:branch"> 5.471 + <?dbhtml filename="managing-releases-and-branchy-development.html"?> 5.472 + <title>Managing releases and branchy development</title> 5.473 + 5.474 + <para id="x_369">Mercurial provides several mechanisms for you to manage a 5.475 + project that is making progress on multiple fronts at once. To 5.476 + understand these mechanisms, let's first take a brief look at a 5.477 + fairly normal software project structure.</para> 5.478 + 5.479 + <para id="x_36a">Many software projects issue periodic <quote>major</quote> 5.480 + releases that contain substantial new features. In parallel, they 5.481 + may issue <quote>minor</quote> releases. These are usually 5.482 + identical to the major releases off which they're based, but with 5.483 + a few bugs fixed.</para> 5.484 + 5.485 + <para id="x_36b">In this chapter, we'll start by talking about how to keep 5.486 + records of project milestones such as releases. We'll then 5.487 + continue on to talk about the flow of work between different 5.488 + phases of a project, and how Mercurial can help you to isolate and 5.489 + manage this work.</para> 5.490 + 5.491 + <sect1> 5.492 + <title>Giving a persistent name to a revision</title> 5.493 + 5.494 + <para id="x_36c">Once you decide that you'd like to call a particular 5.495 + revision a <quote>release</quote>, it's a good idea to record 5.496 + the identity of that revision. This will let you reproduce that 5.497 + release at a later date, for whatever purpose you might need at 5.498 + the time (reproducing a bug, porting to a new platform, etc). 5.499 + &interaction.tag.init;</para> 5.500 + 5.501 + <para id="x_36d">Mercurial lets you give a permanent name to any revision 5.502 + using the <command role="hg-cmd">hg tag</command> command. Not 5.503 + surprisingly, these names are called <quote>tags</quote>.</para> 5.504 + 5.505 + &interaction.tag.tag; 5.506 + 5.507 + <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote> 5.508 + for a revision. Tags exist purely for your convenience, so that 5.509 + you have a handy permanent way to refer to a revision; Mercurial 5.510 + doesn't interpret the tag names you use in any way. Neither 5.511 + does Mercurial place any restrictions on the name of a tag, 5.512 + beyond a few that are necessary to ensure that a tag can be 5.513 + parsed unambiguously. A tag name cannot contain any of the 5.514 + following characters:</para> 5.515 + <itemizedlist> 5.516 + <listitem><para id="x_36f">Colon (ASCII 58, 5.517 + <quote><literal>:</literal></quote>)</para> 5.518 + </listitem> 5.519 + <listitem><para id="x_370">Carriage return (ASCII 13, 5.520 + <quote><literal>\r</literal></quote>)</para> 5.521 + </listitem> 5.522 + <listitem><para id="x_371">Newline (ASCII 10, 5.523 + <quote><literal>\n</literal></quote>)</para> 5.524 + </listitem></itemizedlist> 5.525 + 5.526 + <para id="x_372">You can use the <command role="hg-cmd">hg tags</command> 5.527 + command to display the tags present in your repository. In the 5.528 + output, each tagged revision is identified first by its name, 5.529 + then by revision number, and finally by the unique hash of the 5.530 + revision.</para> 5.531 + 5.532 + &interaction.tag.tags; 5.533 + 5.534 + <para id="x_373">Notice that <literal>tip</literal> is listed in the output 5.535 + of <command role="hg-cmd">hg tags</command>. The 5.536 + <literal>tip</literal> tag is a special <quote>floating</quote> 5.537 + tag, which always identifies the newest revision in the 5.538 + repository.</para> 5.539 + 5.540 + <para id="x_374">In the output of the <command role="hg-cmd">hg 5.541 + tags</command> command, tags are listed in reverse order, by 5.542 + revision number. This usually means that recent tags are listed 5.543 + before older tags. It also means that <literal>tip</literal> is 5.544 + always going to be the first tag listed in the output of 5.545 + <command role="hg-cmd">hg tags</command>.</para> 5.546 + 5.547 + <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it 5.548 + displays a revision that has tags associated with it, it will 5.549 + print those tags.</para> 5.550 + 5.551 + &interaction.tag.log; 5.552 + 5.553 + <para id="x_376">Any time you need to provide a revision ID to a Mercurial 5.554 + command, the command will accept a tag name in its place. 5.555 + Internally, Mercurial will translate your tag name into the 5.556 + corresponding revision ID, then use that.</para> 5.557 + 5.558 + &interaction.tag.log.v1.0; 5.559 + 5.560 + <para id="x_377">There's no limit on the number of tags you can have in a 5.561 + repository, or on the number of tags that a single revision can 5.562 + have. As a practical matter, it's not a great idea to have 5.563 + <quote>too many</quote> (a number which will vary from project 5.564 + to project), simply because tags are supposed to help you to 5.565 + find revisions. If you have lots of tags, the ease of using 5.566 + them to identify revisions diminishes rapidly.</para> 5.567 + 5.568 + <para id="x_378">For example, if your project has milestones as frequent as 5.569 + every few days, it's perfectly reasonable to tag each one of 5.570 + those. But if you have a continuous build system that makes 5.571 + sure every revision can be built cleanly, you'd be introducing a 5.572 + lot of noise if you were to tag every clean build. Instead, you 5.573 + could tag failed builds (on the assumption that they're rare!), 5.574 + or simply not use tags to track buildability.</para> 5.575 + 5.576 + <para id="x_379">If you want to remove a tag that you no longer want, use 5.577 + <command role="hg-cmd">hg tag --remove</command>.</para> 5.578 + 5.579 + &interaction.tag.remove; 5.580 + 5.581 + <para id="x_37a">You can also modify a tag at any time, so that it identifies 5.582 + a different revision, by simply issuing a new <command 5.583 + role="hg-cmd">hg tag</command> command. You'll have to use the 5.584 + <option role="hg-opt-tag">-f</option> option to tell Mercurial 5.585 + that you <emphasis>really</emphasis> want to update the 5.586 + tag.</para> 5.587 + 5.588 + &interaction.tag.replace; 5.589 + 5.590 + <para id="x_37b">There will still be a permanent record of the previous 5.591 + identity of the tag, but Mercurial will no longer use it. 5.592 + There's thus no penalty to tagging the wrong revision; all you 5.593 + have to do is turn around and tag the correct revision once you 5.594 + discover your error.</para> 5.595 + 5.596 + <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 5.597 + in your repository. If you've created any tags, you'll find 5.598 + them in a file in the root of your repository named <filename 5.599 + role="special">.hgtags</filename>. When you run the <command 5.600 + role="hg-cmd">hg tag</command> command, Mercurial modifies 5.601 + this file, then automatically commits the change to it. This 5.602 + means that every time you run <command role="hg-cmd">hg 5.603 + tag</command>, you'll see a corresponding changeset in the 5.604 + output of <command role="hg-cmd">hg log</command>.</para> 5.605 + 5.606 + &interaction.tag.tip; 5.607 + 5.608 + <sect2> 5.609 + <title>Handling tag conflicts during a merge</title> 5.610 + 5.611 + <para id="x_37d">You won't often need to care about the <filename 5.612 + role="special">.hgtags</filename> file, but it sometimes 5.613 + makes its presence known during a merge. The format of the 5.614 + file is simple: it consists of a series of lines. Each line 5.615 + starts with a changeset hash, followed by a space, followed by 5.616 + the name of a tag.</para> 5.617 + 5.618 + <para id="x_37e">If you're resolving a conflict in the <filename 5.619 + role="special">.hgtags</filename> file during a merge, 5.620 + there's one twist to modifying the <filename 5.621 + role="special">.hgtags</filename> file: when Mercurial is 5.622 + parsing the tags in a repository, it 5.623 + <emphasis>never</emphasis> reads the working copy of the 5.624 + <filename role="special">.hgtags</filename> file. Instead, it 5.625 + reads the <emphasis>most recently committed</emphasis> 5.626 + revision of the file.</para> 5.627 + 5.628 + <para id="x_37f">An unfortunate consequence of this design is that you 5.629 + can't actually verify that your merged <filename 5.630 + role="special">.hgtags</filename> file is correct until 5.631 + <emphasis>after</emphasis> you've committed a change. So if 5.632 + you find yourself resolving a conflict on <filename 5.633 + role="special">.hgtags</filename> during a merge, be sure to 5.634 + run <command role="hg-cmd">hg tags</command> after you commit. 5.635 + If it finds an error in the <filename 5.636 + role="special">.hgtags</filename> file, it will report the 5.637 + location of the error, which you can then fix and commit. You 5.638 + should then run <command role="hg-cmd">hg tags</command> 5.639 + again, just to be sure that your fix is correct.</para> 5.640 + </sect2> 5.641 + 5.642 + <sect2> 5.643 + <title>Tags and cloning</title> 5.644 + 5.645 + <para id="x_380">You may have noticed that the <command role="hg-cmd">hg 5.646 + clone</command> command has a <option 5.647 + role="hg-opt-clone">-r</option> option that lets you clone 5.648 + an exact copy of the repository as of a particular changeset. 5.649 + The new clone will not contain any project history that comes 5.650 + after the revision you specified. This has an interaction 5.651 + with tags that can surprise the unwary.</para> 5.652 + 5.653 + <para id="x_381">Recall that a tag is stored as a revision to 5.654 + the <filename role="special">.hgtags</filename> file. When you 5.655 + create a tag, the changeset in which its recorded refers to an 5.656 + older changeset. When you run <command role="hg-cmd">hg clone 5.657 + -r foo</command> to clone a repository as of tag 5.658 + <literal>foo</literal>, the new clone <emphasis>will not 5.659 + contain any revision newer than the one the tag refers to, 5.660 + including the revision where the tag was created</emphasis>. 5.661 + The result is that you'll get exactly the right subset of the 5.662 + project's history in the new repository, but 5.663 + <emphasis>not</emphasis> the tag you might have 5.664 + expected.</para> 5.665 + </sect2> 5.666 + 5.667 + <sect2> 5.668 + <title>When permanent tags are too much</title> 5.669 + 5.670 + <para id="x_382">Since Mercurial's tags are revision controlled and carried 5.671 + around with a project's history, everyone you work with will 5.672 + see the tags you create. But giving names to revisions has 5.673 + uses beyond simply noting that revision 5.674 + <literal>4237e45506ee</literal> is really 5.675 + <literal>v2.0.2</literal>. If you're trying to track down a 5.676 + subtle bug, you might want a tag to remind you of something 5.677 + like <quote>Anne saw the symptoms with this 5.678 + revision</quote>.</para> 5.679 + 5.680 + <para id="x_383">For cases like this, what you might want to use are 5.681 + <emphasis>local</emphasis> tags. You can create a local tag 5.682 + with the <option role="hg-opt-tag">-l</option> option to the 5.683 + <command role="hg-cmd">hg tag</command> command. This will 5.684 + store the tag in a file called <filename 5.685 + role="special">.hg/localtags</filename>. Unlike <filename 5.686 + role="special">.hgtags</filename>, <filename 5.687 + role="special">.hg/localtags</filename> is not revision 5.688 + controlled. Any tags you create using <option 5.689 + role="hg-opt-tag">-l</option> remain strictly local to the 5.690 + repository you're currently working in.</para> 5.691 + </sect2> 5.692 + </sect1> 5.693 + 5.694 + <sect1> 5.695 + <title>The flow of changes&emdash;big picture vs. little</title> 5.696 + 5.697 + <para id="x_384">To return to the outline I sketched at the 5.698 + beginning of the chapter, let's think about a project that has 5.699 + multiple concurrent pieces of work under development at 5.700 + once.</para> 5.701 + 5.702 + <para id="x_385">There might be a push for a new <quote>main</quote> release; 5.703 + a new minor bugfix release to the last main release; and an 5.704 + unexpected <quote>hot fix</quote> to an old release that is now 5.705 + in maintenance mode.</para> 5.706 + 5.707 + <para id="x_386">The usual way people refer to these different concurrent 5.708 + directions of development is as <quote>branches</quote>. 5.709 + However, we've already seen numerous times that Mercurial treats 5.710 + <emphasis>all of history</emphasis> as a series of branches and 5.711 + merges. Really, what we have here is two ideas that are 5.712 + peripherally related, but which happen to share a name.</para> 5.713 + <itemizedlist> 5.714 + <listitem><para id="x_387"><quote>Big picture</quote> branches represent 5.715 + the sweep of a project's evolution; people give them names, 5.716 + and talk about them in conversation.</para> 5.717 + </listitem> 5.718 + <listitem><para id="x_388"><quote>Little picture</quote> branches are 5.719 + artefacts of the day-to-day activity of developing and 5.720 + merging changes. They expose the narrative of how the code 5.721 + was developed.</para> 5.722 + </listitem></itemizedlist> 5.723 + </sect1> 5.724 + 5.725 + <sect1> 5.726 + <title>Managing big-picture branches in repositories</title> 5.727 + 5.728 + <para id="x_389">The easiest way to isolate a <quote>big picture</quote> 5.729 + branch in Mercurial is in a dedicated repository. If you have 5.730 + an existing shared repository&emdash;let's call it 5.731 + <literal>myproject</literal>&emdash;that reaches a 5.732 + <quote>1.0</quote> milestone, you can start to prepare for 5.733 + future maintenance releases on top of version 1.0 by tagging the 5.734 + revision from which you prepared the 1.0 release.</para> 5.735 + 5.736 + &interaction.branch-repo.tag; 5.737 + 5.738 + <para id="x_38a">You can then clone a new shared 5.739 + <literal>myproject-1.0.1</literal> repository as of that 5.740 + tag.</para> 5.741 + 5.742 + &interaction.branch-repo.clone; 5.743 + 5.744 + <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought 5.745 + to go into an upcoming 1.0.1 minor release, they clone the 5.746 + <literal>myproject-1.0.1</literal> repository, make their 5.747 + changes, and push them back.</para> 5.748 + 5.749 + &interaction.branch-repo.bugfix; 5.750 + 5.751 + <para id="x_38c">Meanwhile, development for 5.752 + the next major release can continue, isolated and unabated, in 5.753 + the <literal>myproject</literal> repository.</para> 5.754 + 5.755 + &interaction.branch-repo.new; 5.756 + </sect1> 5.757 + 5.758 + <sect1> 5.759 + <title>Don't repeat yourself: merging across branches</title> 5.760 + 5.761 + <para id="x_38d">In many cases, if you have a bug to fix on a maintenance 5.762 + branch, the chances are good that the bug exists on your 5.763 + project's main branch (and possibly other maintenance branches, 5.764 + too). It's a rare developer who wants to fix the same bug 5.765 + multiple times, so let's look at a few ways that Mercurial can 5.766 + help you to manage these bugfixes without duplicating your 5.767 + work.</para> 5.768 + 5.769 + <para id="x_38e">In the simplest instance, all you need to do is pull changes 5.770 + from your maintenance branch into your local clone of the target 5.771 + branch.</para> 5.772 + 5.773 + &interaction.branch-repo.pull; 5.774 + 5.775 + <para id="x_38f">You'll then need to merge the heads of the two branches, and 5.776 + push back to the main branch.</para> 5.777 + 5.778 + &interaction.branch-repo.merge; 5.779 + </sect1> 5.780 + 5.781 + <sect1> 5.782 + <title>Naming branches within one repository</title> 5.783 + 5.784 + <para id="x_390">In most instances, isolating branches in repositories is the 5.785 + right approach. Its simplicity makes it easy to understand; and 5.786 + so it's hard to make mistakes. There's a one-to-one 5.787 + relationship between branches you're working in and directories 5.788 + on your system. This lets you use normal (non-Mercurial-aware) 5.789 + tools to work on files within a branch/repository.</para> 5.790 + 5.791 + <para id="x_391">If you're more in the <quote>power user</quote> category 5.792 + (<emphasis>and</emphasis> your collaborators are too), there is 5.793 + an alternative way of handling branches that you can consider. 5.794 + I've already mentioned the human-level distinction between 5.795 + <quote>small picture</quote> and <quote>big picture</quote> 5.796 + branches. While Mercurial works with multiple <quote>small 5.797 + picture</quote> branches in a repository all the time (for 5.798 + example after you pull changes in, but before you merge them), 5.799 + it can <emphasis>also</emphasis> work with multiple <quote>big 5.800 + picture</quote> branches.</para> 5.801 + 5.802 + <para id="x_392">The key to working this way is that Mercurial lets you 5.803 + assign a persistent <emphasis>name</emphasis> to a branch. 5.804 + There always exists a branch named <literal>default</literal>. 5.805 + Even before you start naming branches yourself, you can find 5.806 + traces of the <literal>default</literal> branch if you look for 5.807 + them.</para> 5.808 + 5.809 + <para id="x_393">As an example, when you run the <command role="hg-cmd">hg 5.810 + commit</command> command, and it pops up your editor so that 5.811 + you can enter a commit message, look for a line that contains 5.812 + the text <quote><literal>HG: branch default</literal></quote> at 5.813 + the bottom. This is telling you that your commit will occur on 5.814 + the branch named <literal>default</literal>.</para> 5.815 + 5.816 + <para id="x_394">To start working with named branches, use the <command 5.817 + role="hg-cmd">hg branches</command> command. This command 5.818 + lists the named branches already present in your repository, 5.819 + telling you which changeset is the tip of each.</para> 5.820 + 5.821 + &interaction.branch-named.branches; 5.822 + 5.823 + <para id="x_395">Since you haven't created any named branches yet, the only 5.824 + one that exists is <literal>default</literal>.</para> 5.825 + 5.826 + <para id="x_396">To find out what the <quote>current</quote> branch is, run 5.827 + the <command role="hg-cmd">hg branch</command> command, giving 5.828 + it no arguments. This tells you what branch the parent of the 5.829 + current changeset is on.</para> 5.830 + 5.831 + &interaction.branch-named.branch; 5.832 + 5.833 + <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg 5.834 + branch</command> command again. This time, give it one 5.835 + argument: the name of the branch you want to create.</para> 5.836 + 5.837 + &interaction.branch-named.create; 5.838 + 5.839 + <para id="x_398">After you've created a branch, you might wonder what effect 5.840 + the <command role="hg-cmd">hg branch</command> command has had. 5.841 + What do the <command role="hg-cmd">hg status</command> and 5.842 + <command role="hg-cmd">hg tip</command> commands report?</para> 5.843 + 5.844 + &interaction.branch-named.status; 5.845 + 5.846 + <para id="x_399">Nothing has changed in the 5.847 + working directory, and there's been no new history created. As 5.848 + this suggests, running the <command role="hg-cmd">hg 5.849 + branch</command> command has no permanent effect; it only 5.850 + tells Mercurial what branch name to use the 5.851 + <emphasis>next</emphasis> time you commit a changeset.</para> 5.852 + 5.853 + <para id="x_39a">When you commit a change, Mercurial records the name of the 5.854 + branch on which you committed. Once you've switched from the 5.855 + <literal>default</literal> branch to another and committed, 5.856 + you'll see the name of the new branch show up in the output of 5.857 + <command role="hg-cmd">hg log</command>, <command 5.858 + role="hg-cmd">hg tip</command>, and other commands that 5.859 + display the same kind of output.</para> 5.860 + 5.861 + &interaction.branch-named.commit; 5.862 + 5.863 + <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands 5.864 + will print the branch name of every changeset that's not on the 5.865 + <literal>default</literal> branch. As a result, if you never 5.866 + use named branches, you'll never see this information.</para> 5.867 + 5.868 + <para id="x_39c">Once you've named a branch and committed a change with that 5.869 + name, every subsequent commit that descends from that change 5.870 + will inherit the same branch name. You can change the name of a 5.871 + branch at any time, using the <command role="hg-cmd">hg 5.872 + branch</command> command.</para> 5.873 + 5.874 + &interaction.branch-named.rebranch; 5.875 + 5.876 + <para id="x_39d">In practice, this is something you won't do very often, as 5.877 + branch names tend to have fairly long lifetimes. (This isn't a 5.878 + rule, just an observation.)</para> 5.879 + </sect1> 5.880 + 5.881 + <sect1> 5.882 + <title>Dealing with multiple named branches in a 5.883 + repository</title> 5.884 + 5.885 + <para id="x_39e">If you have more than one named branch in a repository, 5.886 + Mercurial will remember the branch that your working directory 5.887 + is on when you start a command like <command role="hg-cmd">hg 5.888 + update</command> or <command role="hg-cmd">hg pull 5.889 + -u</command>. It will update the working directory to the tip 5.890 + of this branch, no matter what the <quote>repo-wide</quote> tip 5.891 + is. To update to a revision that's on a different named branch, 5.892 + you may need to use the <option role="hg-opt-update">-C</option> 5.893 + option to <command role="hg-cmd">hg update</command>.</para> 5.894 + 5.895 + <para id="x_39f">This behavior is a little subtle, so let's see it in 5.896 + action. First, let's remind ourselves what branch we're 5.897 + currently on, and what branches are in our repository.</para> 5.898 + 5.899 + &interaction.branch-named.parents; 5.900 + 5.901 + <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also 5.902 + exists an older <command role="hg-cmd">hg foo</command> 5.903 + branch.</para> 5.904 + 5.905 + <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and 5.906 + forth between the tips of the <literal>foo</literal> and 5.907 + <literal>bar</literal> branches without needing to use the 5.908 + <option role="hg-opt-update">-C</option> option, because this 5.909 + only involves going backwards and forwards linearly through our 5.910 + change history.</para> 5.911 + 5.912 + &interaction.branch-named.update-switchy; 5.913 + 5.914 + <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then 5.915 + run <command role="hg-cmd">hg update</command>, it will keep us 5.916 + on <literal>foo</literal>, not move us to the tip of 5.917 + <literal>bar</literal>.</para> 5.918 + 5.919 + &interaction.branch-named.update-nothing; 5.920 + 5.921 + <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch 5.922 + introduces a new head.</para> 5.923 + 5.924 + &interaction.branch-named.foo-commit; 5.925 + </sect1> 5.926 + 5.927 + <sect1> 5.928 + <title>Branch names and merging</title> 5.929 + 5.930 + <para id="x_3a4">As you've probably noticed, merges in Mercurial are not 5.931 + symmetrical. Let's say our repository has two heads, 17 and 23. 5.932 + If I <command role="hg-cmd">hg update</command> to 17 and then 5.933 + <command role="hg-cmd">hg merge</command> with 23, Mercurial 5.934 + records 17 as the first parent of the merge, and 23 as the 5.935 + second. Whereas if I <command role="hg-cmd">hg update</command> 5.936 + to 23 and then <command role="hg-cmd">hg merge</command> with 5.937 + 17, it records 23 as the first parent, and 17 as the 5.938 + second.</para> 5.939 + 5.940 + <para id="x_3a5">This affects Mercurial's choice of branch name when you 5.941 + merge. After a merge, Mercurial will retain the branch name of 5.942 + the first parent when you commit the result of the merge. If 5.943 + your first parent's branch name is <literal>foo</literal>, and 5.944 + you merge with <literal>bar</literal>, the branch name will 5.945 + still be <literal>foo</literal> after you merge.</para> 5.946 + 5.947 + <para id="x_3a6">It's not unusual for a repository to contain multiple heads, 5.948 + each with the same branch name. Let's say I'm working on the 5.949 + <literal>foo</literal> branch, and so are you. We commit 5.950 + different changes; I pull your changes; I now have two heads, 5.951 + each claiming to be on the <literal>foo</literal> branch. The 5.952 + result of a merge will be a single head on the 5.953 + <literal>foo</literal> branch, as you might hope.</para> 5.954 + 5.955 + <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and 5.956 + I merge work from the <literal>foo</literal> branch, the result 5.957 + will remain on the <literal>bar</literal> branch.</para> 5.958 + 5.959 + &interaction.branch-named.merge; 5.960 + 5.961 + <para id="x_3a8">To give a more concrete example, if I'm working on the 5.962 + <literal>bleeding-edge</literal> branch, and I want to bring in 5.963 + the latest fixes from the <literal>stable</literal> branch, 5.964 + Mercurial will choose the <quote>right</quote> 5.965 + (<literal>bleeding-edge</literal>) branch name when I pull and 5.966 + merge from <literal>stable</literal>.</para> 5.967 + </sect1> 5.968 + 5.969 + <sect1> 5.970 + <title>Branch naming is generally useful</title> 5.971 + 5.972 + <para id="x_3a9">You shouldn't think of named branches as applicable only to 5.973 + situations where you have multiple long-lived branches 5.974 + cohabiting in a single repository. They're very useful even in 5.975 + the one-branch-per-repository case.</para> 5.976 + 5.977 + <para id="x_3aa">In the simplest case, giving a name to each branch gives you 5.978 + a permanent record of which branch a changeset originated on. 5.979 + This gives you more context when you're trying to follow the 5.980 + history of a long-lived branchy project.</para> 5.981 + 5.982 + <para id="x_3ab">If you're working with shared repositories, you can set up a 5.983 + <literal role="hook">pretxnchangegroup</literal> hook on each 5.984 + that will block incoming changes that have the 5.985 + <quote>wrong</quote> branch name. This provides a simple, but 5.986 + effective, defence against people accidentally pushing changes 5.987 + from a <quote>bleeding edge</quote> branch to a 5.988 + <quote>stable</quote> branch. Such a hook might look like this 5.989 + inside the shared repo's <filename role="special"> 5.990 + /.hgrc</filename>.</para> 5.991 + <programlisting>[hooks] 5.992 +pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 5.993 + </sect1> 5.994 </chapter> 5.995 5.996 <!-- 5.997 local variables: 5.998 sgml-parent-document: ("00book.xml" "book" "chapter") 5.999 end: 5.1000 ---> 5.1001 \ No newline at end of file 5.1002 +-->
6.1 --- a/fr/ch09-undo.xml Wed Sep 09 15:25:09 2009 +0200 6.2 +++ b/fr/ch09-undo.xml Wed Sep 09 16:07:36 2009 +0200 6.3 @@ -1,963 +1,1201 @@ 6.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 6.5 6.6 -<chapter> 6.7 -<title>Finding and fixing your mistakes</title> 6.8 -<para>\label{chap:undo}</para> 6.9 - 6.10 -<para>To err might be human, but to really handle the consequences well 6.11 -takes a top-notch revision control system. In this chapter, we'll 6.12 -discuss some of the techniques you can use when you find that a 6.13 -problem has crept into your project. Mercurial has some highly 6.14 -capable features that will help you to isolate the sources of 6.15 -problems, and to handle them appropriately.</para> 6.16 - 6.17 -<sect1> 6.18 -<title>Erasing local history</title> 6.19 - 6.20 -<sect2> 6.21 -<title>The accidental commit</title> 6.22 - 6.23 -<para>I have the occasional but persistent problem of typing rather more 6.24 -quickly than I can think, which sometimes results in me committing a 6.25 -changeset that is either incomplete or plain wrong. In my case, the 6.26 -usual kind of incomplete changeset is one in which I've created a new 6.27 -source file, but forgotten to <command role="hg-cmd">hg add</command> it. A <quote>plain wrong</quote> 6.28 -changeset is not as common, but no less annoying.</para> 6.29 - 6.30 -</sect2> 6.31 -<sect2> 6.32 -<title>Rolling back a transaction</title> 6.33 -<para>\label{sec:undo:rollback}</para> 6.34 - 6.35 -<para>In section <xref linkend="sec:concepts:txn"/>, I mentioned that Mercurial treats 6.36 -each modification of a repository as a <emphasis>transaction</emphasis>. Every time 6.37 -you commit a changeset or pull changes from another repository, 6.38 -Mercurial remembers what you did. You can undo, or <emphasis>roll back</emphasis>, 6.39 -exactly one of these actions using the <command role="hg-cmd">hg rollback</command> command. (See 6.40 -section <xref linkend="sec:undo:rollback-after-push"/> for an important caveat 6.41 -about the use of this command.)</para> 6.42 - 6.43 -<para>Here's a mistake that I often find myself making: committing a change 6.44 -in which I've created a new file, but forgotten to <command role="hg-cmd">hg add</command> it. 6.45 -<!-- &interaction.rollback.commit; --> 6.46 -Looking at the output of <command role="hg-cmd">hg status</command> after the commit immediately 6.47 -confirms the error. 6.48 -<!-- &interaction.rollback.status; --> 6.49 -The commit captured the changes to the file <filename>a</filename>, but not the 6.50 -new file <filename>b</filename>. If I were to push this changeset to a 6.51 -repository that I shared with a colleague, the chances are high that 6.52 -something in <filename>a</filename> would refer to <filename>b</filename>, which would not 6.53 -be present in their repository when they pulled my changes. I would 6.54 -thus become the object of some indignation.</para> 6.55 - 6.56 -<para>However, luck is with me&emdash;I've caught my error before I pushed the 6.57 -changeset. I use the <command role="hg-cmd">hg rollback</command> command, and Mercurial makes 6.58 -that last changeset vanish. 6.59 -<!-- &interaction.rollback.rollback; --> 6.60 -Notice that the changeset is no longer present in the repository's 6.61 -history, and the working directory once again thinks that the file 6.62 -<filename>a</filename> is modified. The commit and rollback have left the 6.63 -working directory exactly as it was prior to the commit; the changeset 6.64 -has been completely erased. I can now safely <command role="hg-cmd">hg add</command> the file 6.65 -<filename>b</filename>, and rerun my commit. 6.66 -<!-- &interaction.rollback.add; --></para> 6.67 - 6.68 -</sect2> 6.69 -<sect2> 6.70 -<title>The erroneous pull</title> 6.71 - 6.72 -<para>It's common practice with Mercurial to maintain separate development 6.73 -branches of a project in different repositories. Your development 6.74 -team might have one shared repository for your project's <quote>0.9</quote> 6.75 -release, and another, containing different changes, for the <quote>1.0</quote> 6.76 -release.</para> 6.77 - 6.78 -<para>Given this, you can imagine that the consequences could be messy if 6.79 -you had a local <quote>0.9</quote> repository, and accidentally pulled changes 6.80 -from the shared <quote>1.0</quote> repository into it. At worst, you could be 6.81 -paying insufficient attention, and push those changes into the shared 6.82 -<quote>0.9</quote> tree, confusing your entire team (but don't worry, we'll 6.83 -return to this horror scenario later). However, it's more likely that 6.84 -you'll notice immediately, because Mercurial will display the URL it's 6.85 -pulling from, or you will see it pull a suspiciously large number of 6.86 -changes into the repository. 6.87 -</para> 6.88 - 6.89 -<para>The <command role="hg-cmd">hg rollback</command> command will work nicely to expunge all of the 6.90 -changesets that you just pulled. Mercurial groups all changes from 6.91 -one <command role="hg-cmd">hg pull</command> into a single transaction, so one <command role="hg-cmd">hg rollback</command> is 6.92 -all you need to undo this mistake. 6.93 -</para> 6.94 - 6.95 -</sect2> 6.96 -<sect2> 6.97 -<title>Rolling back is useless once you've pushed</title> 6.98 -<para>\label{sec:undo:rollback-after-push} 6.99 -</para> 6.100 - 6.101 -<para>The value of the <command role="hg-cmd">hg rollback</command> command drops to zero once you've 6.102 -pushed your changes to another repository. Rolling back a change 6.103 -makes it disappear entirely, but <emphasis>only</emphasis> in the repository in 6.104 -which you perform the <command role="hg-cmd">hg rollback</command>. Because a rollback eliminates 6.105 -history, there's no way for the disappearance of a change to propagate 6.106 -between repositories. 6.107 -</para> 6.108 - 6.109 -<para>If you've pushed a change to another repository&emdash;particularly if it's 6.110 -a shared repository&emdash;it has essentially <quote>escaped into the wild,</quote> 6.111 -and you'll have to recover from your mistake in a different way. What 6.112 -will happen if you push a changeset somewhere, then roll it back, then 6.113 -pull from the repository you pushed to, is that the changeset will 6.114 -reappear in your repository. 6.115 -</para> 6.116 - 6.117 -<para>(If you absolutely know for sure that the change you want to roll back 6.118 -is the most recent change in the repository that you pushed to, 6.119 -<emphasis>and</emphasis> you know that nobody else could have pulled it from that 6.120 -repository, you can roll back the changeset there, too, but you really 6.121 -should really not rely on this working reliably. If you do this, 6.122 -sooner or later a change really will make it into a repository that 6.123 -you don't directly control (or have forgotten about), and come back to 6.124 -bite you.) 6.125 -</para> 6.126 - 6.127 -</sect2> 6.128 -<sect2> 6.129 -<title>You can only roll back once</title> 6.130 - 6.131 -<para>Mercurial stores exactly one transaction in its transaction log; that 6.132 -transaction is the most recent one that occurred in the repository. 6.133 -This means that you can only roll back one transaction. If you expect 6.134 -to be able to roll back one transaction, then its predecessor, this is 6.135 -not the behaviour you will get. 6.136 -<!-- &interaction.rollback.twice; --> 6.137 -Once you've rolled back one transaction in a repository, you can't 6.138 -roll back again in that repository until you perform another commit or 6.139 -pull. 6.140 -</para> 6.141 - 6.142 -</sect2> 6.143 -</sect1> 6.144 -<sect1> 6.145 -<title>Reverting the mistaken change</title> 6.146 - 6.147 -<para>If you make a modification to a file, and decide that you really 6.148 -didn't want to change the file at all, and you haven't yet committed 6.149 -your changes, the <command role="hg-cmd">hg revert</command> command is the one you'll need. It 6.150 -looks at the changeset that's the parent of the working directory, and 6.151 -restores the contents of the file to their state as of that changeset. 6.152 -(That's a long-winded way of saying that, in the normal case, it 6.153 -undoes your modifications.) 6.154 -</para> 6.155 - 6.156 -<para>Let's illustrate how the <command role="hg-cmd">hg revert</command> command works with yet another 6.157 -small example. We'll begin by modifying a file that Mercurial is 6.158 -already tracking. 6.159 -<!-- &interaction.daily.revert.modify; --> 6.160 -If we don't want that change, we can simply <command role="hg-cmd">hg revert</command> the file. 6.161 -<!-- &interaction.daily.revert.unmodify; --> 6.162 -The <command role="hg-cmd">hg revert</command> command provides us with an extra degree of safety 6.163 -by saving our modified file with a <filename>.orig</filename> extension. 6.164 -<!-- &interaction.daily.revert.status; --> 6.165 -</para> 6.166 - 6.167 -<para>Here is a summary of the cases that the <command role="hg-cmd">hg revert</command> command can 6.168 -deal with. We will describe each of these in more detail in the 6.169 -section that follows. 6.170 -</para> 6.171 -<itemizedlist> 6.172 -<listitem><para>If you modify a file, it will restore the file to its unmodified 6.173 - state. 6.174 -</para> 6.175 -</listitem> 6.176 -<listitem><para>If you <command role="hg-cmd">hg add</command> a file, it will undo the <quote>added</quote> state of 6.177 - the file, but leave the file itself untouched. 6.178 -</para> 6.179 -</listitem> 6.180 -<listitem><para>If you delete a file without telling Mercurial, it will restore 6.181 - the file to its unmodified contents. 6.182 -</para> 6.183 -</listitem> 6.184 -<listitem><para>If you use the <command role="hg-cmd">hg remove</command> command to remove a file, it will 6.185 - undo the <quote>removed</quote> state of the file, and restore the file to its 6.186 - unmodified contents. 6.187 -</para> 6.188 -</listitem></itemizedlist> 6.189 - 6.190 -<sect2> 6.191 -<title>File management errors</title> 6.192 -<para>\label{sec:undo:mgmt} 6.193 -</para> 6.194 - 6.195 -<para>The <command role="hg-cmd">hg revert</command> command is useful for more than just modified 6.196 -files. It lets you reverse the results of all of Mercurial's file 6.197 -management commands&emdash;<command role="hg-cmd">hg add</command>, <command role="hg-cmd">hg remove</command>, and so on. 6.198 -</para> 6.199 - 6.200 -<para>If you <command role="hg-cmd">hg add</command> a file, then decide that in fact you don't want 6.201 -Mercurial to track it, use <command role="hg-cmd">hg revert</command> to undo the add. Don't 6.202 -worry; Mercurial will not modify the file in any way. It will just 6.203 -<quote>unmark</quote> the file. 6.204 -<!-- &interaction.daily.revert.add; --> 6.205 -</para> 6.206 - 6.207 -<para>Similarly, if you ask Mercurial to <command role="hg-cmd">hg remove</command> a file, you can use 6.208 -<command role="hg-cmd">hg revert</command> to restore it to the contents it had as of the parent 6.209 -of the working directory. 6.210 -<!-- &interaction.daily.revert.remove; --> 6.211 -This works just as well for a file that you deleted by hand, without 6.212 -telling Mercurial (recall that in Mercurial terminology, this kind of 6.213 -file is called <quote>missing</quote>). 6.214 -<!-- &interaction.daily.revert.missing; --> 6.215 -</para> 6.216 - 6.217 -<para>If you revert a <command role="hg-cmd">hg copy</command>, the copied-to file remains in your 6.218 -working directory afterwards, untracked. Since a copy doesn't affect 6.219 -the copied-from file in any way, Mercurial doesn't do anything with 6.220 -the copied-from file. 6.221 -<!-- &interaction.daily.revert.copy; --> 6.222 -</para> 6.223 - 6.224 -<sect3> 6.225 -<title>A slightly special case: reverting a rename</title> 6.226 - 6.227 -<para>If you <command role="hg-cmd">hg rename</command> a file, there is one small detail that 6.228 -you should remember. When you <command role="hg-cmd">hg revert</command> a rename, it's not 6.229 -enough to provide the name of the renamed-to file, as you can see 6.230 -here. 6.231 -<!-- &interaction.daily.revert.rename; --> 6.232 -As you can see from the output of <command role="hg-cmd">hg status</command>, the renamed-to file 6.233 -is no longer identified as added, but the renamed-<emphasis>from</emphasis> file is 6.234 -still removed! This is counter-intuitive (at least to me), but at 6.235 -least it's easy to deal with. 6.236 -<!-- &interaction.daily.revert.rename-orig; --> 6.237 -So remember, to revert a <command role="hg-cmd">hg rename</command>, you must provide <emphasis>both</emphasis> 6.238 -the source and destination names. 6.239 -</para> 6.240 - 6.241 -<para>% TODO: the output doesn't look like it will be removed! 6.242 -</para> 6.243 - 6.244 -<para>(By the way, if you rename a file, then modify the renamed-to file, 6.245 -then revert both components of the rename, when Mercurial restores the 6.246 -file that was removed as part of the rename, it will be unmodified. 6.247 -If you need the modifications in the renamed-to file to show up in the 6.248 -renamed-from file, don't forget to copy them over.) 6.249 -</para> 6.250 - 6.251 -<para>These fiddly aspects of reverting a rename arguably constitute a small 6.252 -bug in Mercurial. 6.253 -</para> 6.254 - 6.255 -</sect3> 6.256 -</sect2> 6.257 -</sect1> 6.258 -<sect1> 6.259 -<title>Dealing with committed changes</title> 6.260 - 6.261 -<para>Consider a case where you have committed a change $a$, and another 6.262 -change $b$ on top of it; you then realise that change $a$ was 6.263 -incorrect. Mercurial lets you <quote>back out</quote> an entire changeset 6.264 -automatically, and building blocks that let you reverse part of a 6.265 -changeset by hand. 6.266 -</para> 6.267 - 6.268 -<para>Before you read this section, here's something to keep in mind: the 6.269 -<command role="hg-cmd">hg backout</command> command undoes changes by <emphasis>adding</emphasis> history, not 6.270 -by modifying or erasing it. It's the right tool to use if you're 6.271 -fixing bugs, but not if you're trying to undo some change that has 6.272 -catastrophic consequences. To deal with those, see 6.273 -section <xref linkend="sec:undo:aaaiiieee"/>. 6.274 -</para> 6.275 - 6.276 -<sect2> 6.277 -<title>Backing out a changeset</title> 6.278 - 6.279 -<para>The <command role="hg-cmd">hg backout</command> command lets you <quote>undo</quote> the effects of an entire 6.280 -changeset in an automated fashion. Because Mercurial's history is 6.281 -immutable, this command <emphasis>does not</emphasis> get rid of the changeset you 6.282 -want to undo. Instead, it creates a new changeset that 6.283 -<emphasis>reverses</emphasis> the effect of the to-be-undone changeset. 6.284 -</para> 6.285 - 6.286 -<para>The operation of the <command role="hg-cmd">hg backout</command> command is a little intricate, so 6.287 -let's illustrate it with some examples. First, we'll create a 6.288 -repository with some simple changes. 6.289 -<!-- &interaction.backout.init; --> 6.290 -</para> 6.291 - 6.292 -<para>The <command role="hg-cmd">hg backout</command> command takes a single changeset ID as its 6.293 -argument; this is the changeset to back out. Normally, 6.294 -<command role="hg-cmd">hg backout</command> will drop you into a text editor to write a commit 6.295 -message, so you can record why you're backing the change out. In this 6.296 -example, we provide a commit message on the command line using the 6.297 -<option role="hg-opt-backout">-m</option> option. 6.298 -</para> 6.299 - 6.300 -</sect2> 6.301 -<sect2> 6.302 -<title>Backing out the tip changeset</title> 6.303 - 6.304 -<para>We're going to start by backing out the last changeset we committed. 6.305 -<!-- &interaction.backout.simple; --> 6.306 -You can see that the second line from <filename>myfile</filename> is no longer 6.307 -present. Taking a look at the output of <command role="hg-cmd">hg log</command> gives us an idea 6.308 -of what the <command role="hg-cmd">hg backout</command> command has done. 6.309 -<!-- &interaction.backout.simple.log; --> 6.310 -Notice that the new changeset that <command role="hg-cmd">hg backout</command> has created is a 6.311 -child of the changeset we backed out. It's easier to see this in 6.312 -figure <xref linkend="fig:undo:backout"/>, which presents a graphical view of the 6.313 -change history. As you can see, the history is nice and linear. 6.314 -</para> 6.315 - 6.316 -<informalfigure> 6.317 - 6.318 -<para> <mediaobject><imageobject><imagedata fileref="undo-simple"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 6.319 - <caption><para>Backing out a change using the <command role="hg-cmd">hg backout</command> command</para></caption> 6.320 - \label{fig:undo:backout} 6.321 -</para> 6.322 -</informalfigure> 6.323 - 6.324 -</sect2> 6.325 -<sect2> 6.326 -<title>Backing out a non-tip change</title> 6.327 - 6.328 -<para>If you want to back out a change other than the last one you 6.329 -committed, pass the <option role="hg-opt-backout">--merge</option> option to the 6.330 -<command role="hg-cmd">hg backout</command> command. 6.331 -<!-- &interaction.backout.non-tip.clone; --> 6.332 -This makes backing out any changeset a <quote>one-shot</quote> operation that's 6.333 -usually simple and fast. 6.334 -<!-- &interaction.backout.non-tip.backout; --> 6.335 -</para> 6.336 - 6.337 -<para>If you take a look at the contents of <filename>myfile</filename> after the 6.338 -backout finishes, you'll see that the first and third changes are 6.339 -present, but not the second. 6.340 -<!-- &interaction.backout.non-tip.cat; --> 6.341 -</para> 6.342 - 6.343 -<para>As the graphical history in figure <xref linkend="fig:undo:backout-non-tip"/> 6.344 -illustrates, Mercurial actually commits <emphasis>two</emphasis> changes in this 6.345 -kind of situation (the box-shaped nodes are the ones that Mercurial 6.346 -commits automatically). Before Mercurial begins the backout process, 6.347 -it first remembers what the current parent of the working directory 6.348 -is. It then backs out the target changeset, and commits that as a 6.349 -changeset. Finally, it merges back to the previous parent of the 6.350 -working directory, and commits the result of the merge. 6.351 -</para> 6.352 - 6.353 -<para>% TODO: to me it looks like mercurial doesn't commit the second merge automatically! 6.354 -</para> 6.355 - 6.356 -<informalfigure> 6.357 - 6.358 -<para> <mediaobject><imageobject><imagedata fileref="undo-non-tip"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 6.359 - <caption><para>Automated backout of a non-tip change using the <command role="hg-cmd">hg backout</command> command</para></caption> 6.360 - \label{fig:undo:backout-non-tip} 6.361 -</para> 6.362 -</informalfigure> 6.363 - 6.364 -<para>The result is that you end up <quote>back where you were</quote>, only with some 6.365 -extra history that undoes the effect of the changeset you wanted to 6.366 -back out. 6.367 -</para> 6.368 - 6.369 -<sect3> 6.370 -<title>Always use the <option role="hg-opt-backout">--merge</option> option</title> 6.371 - 6.372 -<para>In fact, since the <option role="hg-opt-backout">--merge</option> option will do the <quote>right 6.373 -thing</quote> whether or not the changeset you're backing out is the tip 6.374 -(i.e. it won't try to merge if it's backing out the tip, since there's 6.375 -no need), you should <emphasis>always</emphasis> use this option when you run the 6.376 -<command role="hg-cmd">hg backout</command> command. 6.377 -</para> 6.378 - 6.379 -</sect3> 6.380 -</sect2> 6.381 -<sect2> 6.382 -<title>Gaining more control of the backout process</title> 6.383 - 6.384 -<para>While I've recommended that you always use the 6.385 -<option role="hg-opt-backout">--merge</option> option when backing out a change, the 6.386 -<command role="hg-cmd">hg backout</command> command lets you decide how to merge a backout 6.387 -changeset. Taking control of the backout process by hand is something 6.388 -you will rarely need to do, but it can be useful to understand what 6.389 -the <command role="hg-cmd">hg backout</command> command is doing for you automatically. To 6.390 -illustrate this, let's clone our first repository, but omit the 6.391 -backout change that it contains. 6.392 -</para> 6.393 - 6.394 -<para><!-- &interaction.backout.manual.clone; --> 6.395 -As with our earlier example, We'll commit a third changeset, then back 6.396 -out its parent, and see what happens. 6.397 -<!-- &interaction.backout.manual.backout; --> 6.398 -Our new changeset is again a descendant of the changeset we backout 6.399 -out; it's thus a new head, <emphasis>not</emphasis> a descendant of the changeset 6.400 -that was the tip. The <command role="hg-cmd">hg backout</command> command was quite explicit in 6.401 -telling us this. 6.402 -<!-- &interaction.backout.manual.log; --> 6.403 -</para> 6.404 - 6.405 -<para>Again, it's easier to see what has happened by looking at a graph of 6.406 -the revision history, in figure <xref linkend="fig:undo:backout-manual"/>. This 6.407 -makes it clear that when we use <command role="hg-cmd">hg backout</command> to back out a change 6.408 -other than the tip, Mercurial adds a new head to the repository (the 6.409 -change it committed is box-shaped). 6.410 -</para> 6.411 - 6.412 -<informalfigure> 6.413 - 6.414 -<para> <mediaobject><imageobject><imagedata fileref="undo-manual"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 6.415 - <caption><para>Backing out a change using the <command role="hg-cmd">hg backout</command> command</para></caption> 6.416 - \label{fig:undo:backout-manual} 6.417 -</para> 6.418 -</informalfigure> 6.419 - 6.420 -<para>After the <command role="hg-cmd">hg backout</command> command has completed, it leaves the new 6.421 -<quote>backout</quote> changeset as the parent of the working directory. 6.422 -<!-- &interaction.backout.manual.parents; --> 6.423 -Now we have two isolated sets of changes. 6.424 -<!-- &interaction.backout.manual.heads; --> 6.425 -</para> 6.426 - 6.427 -<para>Let's think about what we expect to see as the contents of 6.428 -<filename>myfile</filename> now. The first change should be present, because 6.429 -we've never backed it out. The second change should be missing, as 6.430 -that's the change we backed out. Since the history graph shows the 6.431 -third change as a separate head, we <emphasis>don't</emphasis> expect to see the 6.432 -third change present in <filename>myfile</filename>. 6.433 -<!-- &interaction.backout.manual.cat; --> 6.434 -To get the third change back into the file, we just do a normal merge 6.435 -of our two heads. 6.436 -<!-- &interaction.backout.manual.merge; --> 6.437 -Afterwards, the graphical history of our repository looks like 6.438 -figure <xref linkend="fig:undo:backout-manual-merge"/>. 6.439 -</para> 6.440 - 6.441 -<informalfigure> 6.442 - 6.443 -<para> <mediaobject><imageobject><imagedata fileref="undo-manual-merge"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 6.444 - <caption><para>Manually merging a backout change</para></caption> 6.445 - \label{fig:undo:backout-manual-merge} 6.446 -</para> 6.447 -</informalfigure> 6.448 - 6.449 -</sect2> 6.450 -<sect2> 6.451 -<title>Why <command role="hg-cmd">hg backout</command> works as it does</title> 6.452 - 6.453 -<para>Here's a brief description of how the <command role="hg-cmd">hg backout</command> command works. 6.454 -</para> 6.455 -<orderedlist> 6.456 -<listitem><para>It ensures that the working directory is <quote>clean</quote>, i.e. that 6.457 - the output of <command role="hg-cmd">hg status</command> would be empty. 6.458 -</para> 6.459 -</listitem> 6.460 -<listitem><para>It remembers the current parent of the working directory. Let's 6.461 - call this changeset <literal>orig</literal> 6.462 -</para> 6.463 -</listitem> 6.464 -<listitem><para>It does the equivalent of a <command role="hg-cmd">hg update</command> to sync the working 6.465 - directory to the changeset you want to back out. Let's call this 6.466 - changeset <literal>backout</literal> 6.467 -</para> 6.468 -</listitem> 6.469 -<listitem><para>It finds the parent of that changeset. Let's call that 6.470 - changeset <literal>parent</literal>. 6.471 -</para> 6.472 -</listitem> 6.473 -<listitem><para>For each file that the <literal>backout</literal> changeset affected, it 6.474 - does the equivalent of a <command role="hg-cmd">hg revert -r parent</command> on that file, 6.475 - to restore it to the contents it had before that changeset was 6.476 - committed. 6.477 -</para> 6.478 -</listitem> 6.479 -<listitem><para>It commits the result as a new changeset. This changeset has 6.480 - <literal>backout</literal> as its parent. 6.481 -</para> 6.482 -</listitem> 6.483 -<listitem><para>If you specify <option role="hg-opt-backout">--merge</option> on the command line, it 6.484 - merges with <literal>orig</literal>, and commits the result of the merge. 6.485 -</para> 6.486 -</listitem></orderedlist> 6.487 - 6.488 -<para>An alternative way to implement the <command role="hg-cmd">hg backout</command> command would be 6.489 -to <command role="hg-cmd">hg export</command> the to-be-backed-out changeset as a diff, then use 6.490 -the <option role="cmd-opt-patch">--reverse</option> option to the <command>patch</command> command to 6.491 -reverse the effect of the change without fiddling with the working 6.492 -directory. This sounds much simpler, but it would not work nearly as 6.493 -well. 6.494 -</para> 6.495 - 6.496 -<para>The reason that <command role="hg-cmd">hg backout</command> does an update, a commit, a merge, and 6.497 -another commit is to give the merge machinery the best chance to do a 6.498 -good job when dealing with all the changes <emphasis>between</emphasis> the change 6.499 -you're backing out and the current tip. 6.500 -</para> 6.501 - 6.502 -<para>If you're backing out a changeset that's 100 revisions back in your 6.503 -project's history, the chances that the <command>patch</command> command will 6.504 -be able to apply a reverse diff cleanly are not good, because 6.505 -intervening changes are likely to have <quote>broken the context</quote> that 6.506 -<command>patch</command> uses to determine whether it can apply a patch (if 6.507 -this sounds like gibberish, see <xref linkend="sec:mq:patch"/> for a 6.508 -discussion of the <command>patch</command> command). Also, Mercurial's merge 6.509 -machinery will handle files and directories being renamed, permission 6.510 -changes, and modifications to binary files, none of which 6.511 -<command>patch</command> can deal with. 6.512 -</para> 6.513 - 6.514 -</sect2> 6.515 -</sect1> 6.516 -<sect1> 6.517 -<title>Changes that should never have been</title> 6.518 -<para>\label{sec:undo:aaaiiieee} 6.519 -</para> 6.520 - 6.521 -<para>Most of the time, the <command role="hg-cmd">hg backout</command> command is exactly what you need 6.522 -if you want to undo the effects of a change. It leaves a permanent 6.523 -record of exactly what you did, both when committing the original 6.524 -changeset and when you cleaned up after it. 6.525 -</para> 6.526 - 6.527 -<para>On rare occasions, though, you may find that you've committed a change 6.528 -that really should not be present in the repository at all. For 6.529 -example, it would be very unusual, and usually considered a mistake, 6.530 -to commit a software project's object files as well as its source 6.531 -files. Object files have almost no intrinsic value, and they're 6.532 -<emphasis>big</emphasis>, so they increase the size of the repository and the amount 6.533 -of time it takes to clone or pull changes. 6.534 -</para> 6.535 - 6.536 -<para>Before I discuss the options that you have if you commit a <quote>brown 6.537 -paper bag</quote> change (the kind that's so bad that you want to pull a 6.538 -brown paper bag over your head), let me first discuss some approaches 6.539 -that probably won't work. 6.540 -</para> 6.541 - 6.542 -<para>Since Mercurial treats history as accumulative&emdash;every change builds 6.543 -on top of all changes that preceded it&emdash;you generally can't just make 6.544 -disastrous changes disappear. The one exception is when you've just 6.545 -committed a change, and it hasn't been pushed or pulled into another 6.546 -repository. That's when you can safely use the <command role="hg-cmd">hg rollback</command> 6.547 -command, as I detailed in section <xref linkend="sec:undo:rollback"/>. 6.548 -</para> 6.549 - 6.550 -<para>After you've pushed a bad change to another repository, you 6.551 -<emphasis>could</emphasis> still use <command role="hg-cmd">hg rollback</command> to make your local copy of the 6.552 -change disappear, but it won't have the consequences you want. The 6.553 -change will still be present in the remote repository, so it will 6.554 -reappear in your local repository the next time you pull. 6.555 -</para> 6.556 - 6.557 -<para>If a situation like this arises, and you know which repositories your 6.558 -bad change has propagated into, you can <emphasis>try</emphasis> to get rid of the 6.559 -changeefrom <emphasis>every</emphasis> one of those repositories. This is, of 6.560 -course, not a satisfactory solution: if you miss even a single 6.561 -repository while you're expunging, the change is still <quote>in the 6.562 -wild</quote>, and could propagate further. 6.563 -</para> 6.564 - 6.565 -<para>If you've committed one or more changes <emphasis>after</emphasis> the change that 6.566 -you'd like to see disappear, your options are further reduced. 6.567 -Mercurial doesn't provide a way to <quote>punch a hole</quote> in history, 6.568 -leaving changesets intact. 6.569 -</para> 6.570 - 6.571 -<para>XXX This needs filling out. The <literal>hg-replay</literal> script in the 6.572 -<literal>examples</literal> directory works, but doesn't handle merge 6.573 -changesets. Kind of an important omission. 6.574 -</para> 6.575 - 6.576 -<sect2> 6.577 -<title>Protect yourself from <quote>escaped</quote> changes</title> 6.578 - 6.579 -<para>If you've committed some changes to your local repository and they've 6.580 -been pushed or pulled somewhere else, this isn't necessarily a 6.581 -disaster. You can protect yourself ahead of time against some classes 6.582 -of bad changeset. This is particularly easy if your team usually 6.583 -pulls changes from a central repository. 6.584 -</para> 6.585 - 6.586 -<para>By configuring some hooks on that repository to validate incoming 6.587 -changesets (see chapter <xref linkend="chap:hook"/>), you can automatically 6.588 -prevent some kinds of bad changeset from being pushed to the central 6.589 -repository at all. With such a configuration in place, some kinds of 6.590 -bad changeset will naturally tend to <quote>die out</quote> because they can't 6.591 -propagate into the central repository. Better yet, this happens 6.592 -without any need for explicit intervention. 6.593 -</para> 6.594 - 6.595 -<para>For instance, an incoming change hook that verifies that a changeset 6.596 -will actually compile can prevent people from inadvertantly <quote>breaking 6.597 -the build</quote>. 6.598 -</para> 6.599 - 6.600 -</sect2> 6.601 -</sect1> 6.602 -<sect1> 6.603 -<title>Finding the source of a bug</title> 6.604 -<para>\label{sec:undo:bisect} 6.605 -</para> 6.606 - 6.607 -<para>While it's all very well to be able to back out a changeset that 6.608 -introduced a bug, this requires that you know which changeset to back 6.609 -out. Mercurial provides an invaluable command, called 6.610 -<command role="hg-cmd">hg bisect</command>, that helps you to automate this process and accomplish 6.611 -it very efficiently. 6.612 -</para> 6.613 - 6.614 -<para>The idea behind the <command role="hg-cmd">hg bisect</command> command is that a changeset has 6.615 -introduced some change of behaviour that you can identify with a 6.616 -simple binary test. You don't know which piece of code introduced the 6.617 -change, but you know how to test for the presence of the bug. The 6.618 -<command role="hg-cmd">hg bisect</command> command uses your test to direct its search for the 6.619 -changeset that introduced the code that caused the bug. 6.620 -</para> 6.621 - 6.622 -<para>Here are a few scenarios to help you understand how you might apply 6.623 -this command. 6.624 -</para> 6.625 -<itemizedlist> 6.626 -<listitem><para>The most recent version of your software has a bug that you 6.627 - remember wasn't present a few weeks ago, but you don't know when it 6.628 - was introduced. Here, your binary test checks for the presence of 6.629 - that bug. 6.630 -</para> 6.631 -</listitem> 6.632 -<listitem><para>You fixed a bug in a rush, and now it's time to close the entry 6.633 - in your team's bug database. The bug database requires a changeset 6.634 - ID when you close an entry, but you don't remember which changeset 6.635 - you fixed the bug in. Once again, your binary test checks for the 6.636 - presence of the bug. 6.637 -</para> 6.638 -</listitem> 6.639 -<listitem><para>Your software works correctly, but runs 15% slower than the 6.640 - last time you measured it. You want to know which changeset 6.641 - introduced the performance regression. In this case, your binary 6.642 - test measures the performance of your software, to see whether it's 6.643 - <quote>fast</quote> or <quote>slow</quote>. 6.644 -</para> 6.645 -</listitem> 6.646 -<listitem><para>The sizes of the components of your project that you ship 6.647 - exploded recently, and you suspect that something changed in the way 6.648 - you build your project. 6.649 -</para> 6.650 -</listitem></itemizedlist> 6.651 - 6.652 -<para>From these examples, it should be clear that the <command role="hg-cmd">hg bisect</command> 6.653 -command is not useful only for finding the sources of bugs. You can 6.654 -use it to find any <quote>emergent property</quote> of a repository (anything 6.655 -that you can't find from a simple text search of the files in the 6.656 -tree) for which you can write a binary test. 6.657 -</para> 6.658 - 6.659 -<para>We'll introduce a little bit of terminology here, just to make it 6.660 -clear which parts of the search process are your responsibility, and 6.661 -which are Mercurial's. A <emphasis>test</emphasis> is something that <emphasis>you</emphasis> run 6.662 -when <command role="hg-cmd">hg bisect</command> chooses a changeset. A <emphasis>probe</emphasis> is what 6.663 -<command role="hg-cmd">hg bisect</command> runs to tell whether a revision is good. Finally, 6.664 -we'll use the word <quote>bisect</quote>, as both a noun and a verb, to stand in 6.665 -for the phrase <quote>search using the <command role="hg-cmd">hg bisect</command> command. 6.666 -</para> 6.667 - 6.668 -<para>One simple way to automate the searching process would be simply to 6.669 -probe every changeset. However, this scales poorly. If it took ten 6.670 -minutes to test a single changeset, and you had 10,000 changesets in 6.671 -your repository, the exhaustive approach would take on average 35 6.672 -<emphasis>days</emphasis> to find the changeset that introduced a bug. Even if you 6.673 -knew that the bug was introduced by one of the last 500 changesets, 6.674 -and limited your search to those, you'd still be looking at over 40 6.675 -hours to find the changeset that introduced your bug. 6.676 -</para> 6.677 - 6.678 -<para>What the <command role="hg-cmd">hg bisect</command> command does is use its knowledge of the 6.679 -<quote>shape</quote> of your project's revision history to perform a search in 6.680 -time proportional to the <emphasis>logarithm</emphasis> of the number of changesets 6.681 -to check (the kind of search it performs is called a dichotomic 6.682 -search). With this approach, searching through 10,000 changesets will 6.683 -take less than three hours, even at ten minutes per test (the search 6.684 -will require about 14 tests). Limit your search to the last hundred 6.685 -changesets, and it will take only about an hour (roughly seven tests). 6.686 -</para> 6.687 - 6.688 -<para>The <command role="hg-cmd">hg bisect</command> command is aware of the <quote>branchy</quote> nature of a 6.689 -Mercurial project's revision history, so it has no problems dealing 6.690 -with branches, merges, or multiple heads in a repository. It can 6.691 -prune entire branches of history with a single probe, which is how it 6.692 -operates so efficiently. 6.693 -</para> 6.694 - 6.695 -<sect2> 6.696 -<title>Using the <command role="hg-cmd">hg bisect</command> command</title> 6.697 - 6.698 -<para>Here's an example of <command role="hg-cmd">hg bisect</command> in action. 6.699 -</para> 6.700 - 6.701 -<note> 6.702 -<para> In versions 0.9.5 and earlier of Mercurial, <command role="hg-cmd">hg bisect</command> was not a 6.703 - core command: it was distributed with Mercurial as an extension. 6.704 - This section describes the built-in command, not the old extension. 6.705 -</para> 6.706 -</note> 6.707 - 6.708 -<para>Now let's create a repository, so that we can try out the 6.709 -<command role="hg-cmd">hg bisect</command> command in isolation. 6.710 -<!-- &interaction.bisect.init; --> 6.711 -We'll simulate a project that has a bug in it in a simple-minded way: 6.712 -create trivial changes in a loop, and nominate one specific change 6.713 -that will have the <quote>bug</quote>. This loop creates 35 changesets, each 6.714 -adding a single file to the repository. We'll represent our <quote>bug</quote> 6.715 -with a file that contains the text <quote>i have a gub</quote>. 6.716 -<!-- &interaction.bisect.commits; --> 6.717 -</para> 6.718 - 6.719 -<para>The next thing that we'd like to do is figure out how to use the 6.720 -<command role="hg-cmd">hg bisect</command> command. We can use Mercurial's normal built-in help 6.721 -mechanism for this. 6.722 -<!-- &interaction.bisect.help; --> 6.723 -</para> 6.724 - 6.725 -<para>The <command role="hg-cmd">hg bisect</command> command works in steps. Each step proceeds as follows. 6.726 -</para> 6.727 -<orderedlist> 6.728 -<listitem><para>You run your binary test. 6.729 -</para> 6.730 -</listitem><itemizedlist> 6.731 -<listitem><para> \item If the test succeeded, you tell <command role="hg-cmd">hg bisect</command> by running the 6.732 - <command role="hg-cmd">hg bisect good</command> command. 6.733 - \item If it failed, run the <command role="hg-cmd">hg bisect --bad</command> command. 6.734 -</para> 6.735 -</listitem></itemizedlist> 6.736 -<listitem><para>The command uses your information to decide which changeset to 6.737 - test next. 6.738 -</para> 6.739 -</listitem> 6.740 -<listitem><para>It updates the working directory to that changeset, and the 6.741 - process begins again. 6.742 -</para> 6.743 -</listitem></orderedlist> 6.744 -<para>The process ends when <command role="hg-cmd">hg bisect</command> identifies a unique changeset 6.745 -that marks the point where your test transitioned from <quote>succeeding</quote> 6.746 -to <quote>failing</quote>. 6.747 -</para> 6.748 - 6.749 -<para>To start the search, we must run the <command role="hg-cmd">hg bisect --reset</command> command. 6.750 -<!-- &interaction.bisect.search.init; --> 6.751 -</para> 6.752 - 6.753 -<para>In our case, the binary test we use is simple: we check to see if any 6.754 -file in the repository contains the string <quote>i have a gub</quote>. If it 6.755 -does, this changeset contains the change that <quote>caused the bug</quote>. By 6.756 -convention, a changeset that has the property we're searching for is 6.757 -<quote>bad</quote>, while one that doesn't is <quote>good</quote>. 6.758 -</para> 6.759 - 6.760 -<para>Most of the time, the revision to which the working directory is 6.761 -synced (usually the tip) already exhibits the problem introduced by 6.762 -the buggy change, so we'll mark it as <quote>bad</quote>. 6.763 -<!-- &interaction.bisect.search.bad-init; --> 6.764 -</para> 6.765 - 6.766 -<para>Our next task is to nominate a changeset that we know <emphasis>doesn't</emphasis> 6.767 -have the bug; the <command role="hg-cmd">hg bisect</command> command will <quote>bracket</quote> its search 6.768 -between the first pair of good and bad changesets. In our case, we 6.769 -know that revision 10 didn't have the bug. (I'll have more words 6.770 -about choosing the first <quote>good</quote> changeset later.) 6.771 -<!-- &interaction.bisect.search.good-init; --> 6.772 -</para> 6.773 - 6.774 -<para>Notice that this command printed some output. 6.775 -</para> 6.776 -<itemizedlist> 6.777 -<listitem><para>It told us how many changesets it must consider before it can 6.778 - identify the one that introduced the bug, and how many tests that 6.779 - will require. 6.780 -</para> 6.781 -</listitem> 6.782 -<listitem><para>It updated the working directory to the next changeset to test, 6.783 - and told us which changeset it's testing. 6.784 -</para> 6.785 -</listitem></itemizedlist> 6.786 - 6.787 -<para>We now run our test in the working directory. We use the 6.788 -<command>grep</command> command to see if our <quote>bad</quote> file is present in the 6.789 -working directory. If it is, this revision is bad; if not, this 6.790 -revision is good. 6.791 -<!-- &interaction.bisect.search.step1; --> 6.792 -</para> 6.793 - 6.794 -<para>This test looks like a perfect candidate for automation, so let's turn 6.795 -it into a shell function. 6.796 -<!-- &interaction.bisect.search.mytest; --> 6.797 -We can now run an entire test step with a single command, 6.798 -<literal>mytest</literal>. 6.799 -<!-- &interaction.bisect.search.step2; --> 6.800 -A few more invocations of our canned test step command, and we're 6.801 -done. 6.802 -<!-- &interaction.bisect.search.rest; --> 6.803 -</para> 6.804 - 6.805 -<para>Even though we had 40 changesets to search through, the <command role="hg-cmd">hg bisect</command> 6.806 -command let us find the changeset that introduced our <quote>bug</quote> with 6.807 -only five tests. Because the number of tests that the <command role="hg-cmd">hg bisect</command> 6.808 -command performs grows logarithmically with the number of changesets to 6.809 -search, the advantage that it has over the <quote>brute force</quote> search 6.810 -approach increases with every changeset you add. 6.811 -</para> 6.812 - 6.813 -</sect2> 6.814 -<sect2> 6.815 -<title>Cleaning up after your search</title> 6.816 - 6.817 -<para>When you're finished using the <command role="hg-cmd">hg bisect</command> command in a 6.818 -repository, you can use the <command role="hg-cmd">hg bisect reset</command> command to drop 6.819 -the information it was using to drive your search. The command 6.820 -doesn't use much space, so it doesn't matter if you forget to run this 6.821 -command. However, <command role="hg-cmd">hg bisect</command> won't let you start a new search in 6.822 -that repository until you do a <command role="hg-cmd">hg bisect reset</command>. 6.823 -<!-- &interaction.bisect.search.reset; --> 6.824 -</para> 6.825 - 6.826 -</sect2> 6.827 -</sect1> 6.828 -<sect1> 6.829 -<title>Tips for finding bugs effectively</title> 6.830 - 6.831 -<sect2> 6.832 -<title>Give consistent input</title> 6.833 - 6.834 -<para>The <command role="hg-cmd">hg bisect</command> command requires that you correctly report the 6.835 -result of every test you perform. If you tell it that a test failed 6.836 -when it really succeeded, it <emphasis>might</emphasis> be able to detect the 6.837 -inconsistency. If it can identify an inconsistency in your reports, 6.838 -it will tell you that a particular changeset is both good and bad. 6.839 -However, it can't do this perfectly; it's about as likely to report 6.840 -the wrong changeset as the source of the bug. 6.841 -</para> 6.842 - 6.843 -</sect2> 6.844 -<sect2> 6.845 -<title>Automate as much as possible</title> 6.846 - 6.847 -<para>When I started using the <command role="hg-cmd">hg bisect</command> command, I tried a few times 6.848 -to run my tests by hand, on the command line. This is an approach 6.849 -that I, at least, am not suited to. After a few tries, I found that I 6.850 -was making enough mistakes that I was having to restart my searches 6.851 -several times before finally getting correct results. 6.852 -</para> 6.853 - 6.854 -<para>My initial problems with driving the <command role="hg-cmd">hg bisect</command> command by hand 6.855 -occurred even with simple searches on small repositories; if the 6.856 -problem you're looking for is more subtle, or the number of tests that 6.857 -<command role="hg-cmd">hg bisect</command> must perform increases, the likelihood of operator 6.858 -error ruining the search is much higher. Once I started automating my 6.859 -tests, I had much better results. 6.860 -</para> 6.861 - 6.862 -<para>The key to automated testing is twofold: 6.863 -</para> 6.864 -<itemizedlist> 6.865 -<listitem><para>always test for the same symptom, and 6.866 -</para> 6.867 -</listitem> 6.868 -<listitem><para>always feed consistent input to the <command role="hg-cmd">hg bisect</command> command. 6.869 -</para> 6.870 -</listitem></itemizedlist> 6.871 -<para>In my tutorial example above, the <command>grep</command> command tests for the 6.872 -symptom, and the <literal>if</literal> statement takes the result of this check 6.873 -and ensures that we always feed the same input to the <command role="hg-cmd">hg bisect</command> 6.874 -command. The <literal>mytest</literal> function marries these together in a 6.875 -reproducible way, so that every test is uniform and consistent. 6.876 -</para> 6.877 - 6.878 -</sect2> 6.879 -<sect2> 6.880 -<title>Check your results</title> 6.881 - 6.882 -<para>Because the output of a <command role="hg-cmd">hg bisect</command> search is only as good as the 6.883 -input you give it, don't take the changeset it reports as the 6.884 -absolute truth. A simple way to cross-check its report is to manually 6.885 -run your test at each of the following changesets: 6.886 -</para> 6.887 -<itemizedlist> 6.888 -<listitem><para>The changeset that it reports as the first bad revision. Your 6.889 - test should still report this as bad. 6.890 -</para> 6.891 -</listitem> 6.892 -<listitem><para>The parent of that changeset (either parent, if it's a merge). 6.893 - Your test should report this changeset as good. 6.894 -</para> 6.895 -</listitem> 6.896 -<listitem><para>A child of that changeset. Your test should report this 6.897 - changeset as bad. 6.898 -</para> 6.899 -</listitem></itemizedlist> 6.900 - 6.901 -</sect2> 6.902 -<sect2> 6.903 -<title>Beware interference between bugs</title> 6.904 - 6.905 -<para>It's possible that your search for one bug could be disrupted by the 6.906 -presence of another. For example, let's say your software crashes at 6.907 -revision 100, and worked correctly at revision 50. Unknown to you, 6.908 -someone else introduced a different crashing bug at revision 60, and 6.909 -fixed it at revision 80. This could distort your results in one of 6.910 -several ways. 6.911 -</para> 6.912 - 6.913 -<para>It is possible that this other bug completely <quote>masks</quote> yours, which 6.914 -is to say that it occurs before your bug has a chance to manifest 6.915 -itself. If you can't avoid that other bug (for example, it prevents 6.916 -your project from building), and so can't tell whether your bug is 6.917 -present in a particular changeset, the <command role="hg-cmd">hg bisect</command> command cannot 6.918 -help you directly. Instead, you can mark a changeset as untested by 6.919 -running <command role="hg-cmd">hg bisect --skip</command>. 6.920 -</para> 6.921 - 6.922 -<para>A different problem could arise if your test for a bug's presence is 6.923 -not specific enough. If you check for <quote>my program crashes</quote>, then 6.924 -both your crashing bug and an unrelated crashing bug that masks it 6.925 -will look like the same thing, and mislead <command role="hg-cmd">hg bisect</command>. 6.926 -</para> 6.927 - 6.928 -<para>Another useful situation in which to use <command role="hg-cmd">hg bisect --skip</command> is 6.929 -if you can't test a revision because your project was in a broken and 6.930 -hence untestable state at that revision, perhaps because someone 6.931 -checked in a change that prevented the project from building. 6.932 -</para> 6.933 - 6.934 -</sect2> 6.935 -<sect2> 6.936 -<title>Bracket your search lazily</title> 6.937 - 6.938 -<para>Choosing the first <quote>good</quote> and <quote>bad</quote> changesets that will mark the 6.939 -end points of your search is often easy, but it bears a little 6.940 -discussion nevertheless. From the perspective of <command role="hg-cmd">hg bisect</command>, the 6.941 -<quote>newest</quote> changeset is conventionally <quote>bad</quote>, and the older 6.942 -changeset is <quote>good</quote>. 6.943 -</para> 6.944 - 6.945 -<para>If you're having trouble remembering when a suitable <quote>good</quote> change 6.946 -was, so that you can tell <command role="hg-cmd">hg bisect</command>, you could do worse than 6.947 -testing changesets at random. Just remember to eliminate contenders 6.948 -that can't possibly exhibit the bug (perhaps because the feature with 6.949 -the bug isn't present yet) and those where another problem masks the 6.950 -bug (as I discussed above). 6.951 -</para> 6.952 - 6.953 -<para>Even if you end up <quote>early</quote> by thousands of changesets or months of 6.954 -history, you will only add a handful of tests to the total number that 6.955 -<command role="hg-cmd">hg bisect</command> must perform, thanks to its logarithmic behaviour. 6.956 -</para> 6.957 - 6.958 -</sect2> 6.959 -</sect1> 6.960 +<chapter id="chap:undo"> 6.961 + <?dbhtml filename="finding-and-fixing-mistakes.html"?> 6.962 + <title>Finding and fixing mistakes</title> 6.963 + 6.964 + <para id="x_d2">To err might be human, but to really handle the consequences 6.965 + well takes a top-notch revision control system. In this chapter, 6.966 + we'll discuss some of the techniques you can use when you find 6.967 + that a problem has crept into your project. Mercurial has some 6.968 + highly capable features that will help you to isolate the sources 6.969 + of problems, and to handle them appropriately.</para> 6.970 + 6.971 + <sect1> 6.972 + <title>Erasing local history</title> 6.973 + 6.974 + <sect2> 6.975 + <title>The accidental commit</title> 6.976 + 6.977 + <para id="x_d3">I have the occasional but persistent problem of typing 6.978 + rather more quickly than I can think, which sometimes results 6.979 + in me committing a changeset that is either incomplete or 6.980 + plain wrong. In my case, the usual kind of incomplete 6.981 + changeset is one in which I've created a new source file, but 6.982 + forgotten to <command role="hg-cmd">hg add</command> it. A 6.983 + <quote>plain wrong</quote> changeset is not as common, but no 6.984 + less annoying.</para> 6.985 + 6.986 + </sect2> 6.987 + <sect2 id="sec:undo:rollback"> 6.988 + <title>Rolling back a transaction</title> 6.989 + 6.990 + <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I 6.991 + mentioned that Mercurial treats each modification of a 6.992 + repository as a <emphasis>transaction</emphasis>. Every time 6.993 + you commit a changeset or pull changes from another 6.994 + repository, Mercurial remembers what you did. You can undo, 6.995 + or <emphasis>roll back</emphasis>, exactly one of these 6.996 + actions using the <command role="hg-cmd">hg rollback</command> 6.997 + command. (See <xref linkend="sec:undo:rollback-after-push"/> 6.998 + for an important caveat about the use of this command.)</para> 6.999 + 6.1000 + <para id="x_d5">Here's a mistake that I often find myself making: 6.1001 + committing a change in which I've created a new file, but 6.1002 + forgotten to <command role="hg-cmd">hg add</command> 6.1003 + it.</para> 6.1004 + 6.1005 + &interaction.rollback.commit; 6.1006 + 6.1007 + <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 6.1008 + status</command> after the commit immediately confirms the 6.1009 + error.</para> 6.1010 + 6.1011 + &interaction.rollback.status; 6.1012 + 6.1013 + <para id="x_d7">The commit captured the changes to the file 6.1014 + <filename>a</filename>, but not the new file 6.1015 + <filename>b</filename>. If I were to push this changeset to a 6.1016 + repository that I shared with a colleague, the chances are 6.1017 + high that something in <filename>a</filename> would refer to 6.1018 + <filename>b</filename>, which would not be present in their 6.1019 + repository when they pulled my changes. I would thus become 6.1020 + the object of some indignation.</para> 6.1021 + 6.1022 + <para id="x_d8">However, luck is with me&emdash;I've caught my error 6.1023 + before I pushed the changeset. I use the <command 6.1024 + role="hg-cmd">hg rollback</command> command, and Mercurial 6.1025 + makes that last changeset vanish.</para> 6.1026 + 6.1027 + &interaction.rollback.rollback; 6.1028 + 6.1029 + <para id="x_d9">Notice that the changeset is no longer present in the 6.1030 + repository's history, and the working directory once again 6.1031 + thinks that the file <filename>a</filename> is modified. The 6.1032 + commit and rollback have left the working directory exactly as 6.1033 + it was prior to the commit; the changeset has been completely 6.1034 + erased. I can now safely <command role="hg-cmd">hg 6.1035 + add</command> the file <filename>b</filename>, and rerun my 6.1036 + commit.</para> 6.1037 + 6.1038 + &interaction.rollback.add; 6.1039 + 6.1040 + </sect2> 6.1041 + <sect2> 6.1042 + <title>The erroneous pull</title> 6.1043 + 6.1044 + <para id="x_da">It's common practice with Mercurial to maintain separate 6.1045 + development branches of a project in different repositories. 6.1046 + Your development team might have one shared repository for 6.1047 + your project's <quote>0.9</quote> release, and another, 6.1048 + containing different changes, for the <quote>1.0</quote> 6.1049 + release.</para> 6.1050 + 6.1051 + <para id="x_db">Given this, you can imagine that the consequences could be 6.1052 + messy if you had a local <quote>0.9</quote> repository, and 6.1053 + accidentally pulled changes from the shared <quote>1.0</quote> 6.1054 + repository into it. At worst, you could be paying 6.1055 + insufficient attention, and push those changes into the shared 6.1056 + <quote>0.9</quote> tree, confusing your entire team (but don't 6.1057 + worry, we'll return to this horror scenario later). However, 6.1058 + it's more likely that you'll notice immediately, because 6.1059 + Mercurial will display the URL it's pulling from, or you will 6.1060 + see it pull a suspiciously large number of changes into the 6.1061 + repository.</para> 6.1062 + 6.1063 + <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 6.1064 + will work nicely to expunge all of the changesets that you 6.1065 + just pulled. Mercurial groups all changes from one <command 6.1066 + role="hg-cmd">hg pull</command> into a single transaction, 6.1067 + so one <command role="hg-cmd">hg rollback</command> is all you 6.1068 + need to undo this mistake.</para> 6.1069 + 6.1070 + </sect2> 6.1071 + <sect2 id="sec:undo:rollback-after-push"> 6.1072 + <title>Rolling back is useless once you've pushed</title> 6.1073 + 6.1074 + <para id="x_dd">The value of the <command role="hg-cmd">hg 6.1075 + rollback</command> command drops to zero once you've pushed 6.1076 + your changes to another repository. Rolling back a change 6.1077 + makes it disappear entirely, but <emphasis>only</emphasis> in 6.1078 + the repository in which you perform the <command 6.1079 + role="hg-cmd">hg rollback</command>. Because a rollback 6.1080 + eliminates history, there's no way for the disappearance of a 6.1081 + change to propagate between repositories.</para> 6.1082 + 6.1083 + <para id="x_de">If you've pushed a change to another 6.1084 + repository&emdash;particularly if it's a shared 6.1085 + repository&emdash;it has essentially <quote>escaped into the 6.1086 + wild,</quote> and you'll have to recover from your mistake 6.1087 + in a different way. If you push a changeset somewhere, then 6.1088 + roll it back, then pull from the repository you pushed to, the 6.1089 + changeset you thought you'd gotten rid of will simply reappear 6.1090 + in your repository.</para> 6.1091 + 6.1092 + <para id="x_df">(If you absolutely know for sure that the change 6.1093 + you want to roll back is the most recent change in the 6.1094 + repository that you pushed to, <emphasis>and</emphasis> you 6.1095 + know that nobody else could have pulled it from that 6.1096 + repository, you can roll back the changeset there, too, but 6.1097 + you really should not expect this to work reliably. Sooner or 6.1098 + later a change really will make it into a repository that you 6.1099 + don't directly control (or have forgotten about), and come 6.1100 + back to bite you.)</para> 6.1101 + 6.1102 + </sect2> 6.1103 + <sect2> 6.1104 + <title>You can only roll back once</title> 6.1105 + 6.1106 + <para id="x_e0">Mercurial stores exactly one transaction in its 6.1107 + transaction log; that transaction is the most recent one that 6.1108 + occurred in the repository. This means that you can only roll 6.1109 + back one transaction. If you expect to be able to roll back 6.1110 + one transaction, then its predecessor, this is not the 6.1111 + behavior you will get.</para> 6.1112 + 6.1113 + &interaction.rollback.twice; 6.1114 + 6.1115 + <para id="x_e1">Once you've rolled back one transaction in a repository, 6.1116 + you can't roll back again in that repository until you perform 6.1117 + another commit or pull.</para> 6.1118 + 6.1119 + </sect2> 6.1120 + </sect1> 6.1121 + <sect1> 6.1122 + <title>Reverting the mistaken change</title> 6.1123 + 6.1124 + <para id="x_e2">If you make a modification to a file, and decide that you 6.1125 + really didn't want to change the file at all, and you haven't 6.1126 + yet committed your changes, the <command role="hg-cmd">hg 6.1127 + revert</command> command is the one you'll need. It looks at 6.1128 + the changeset that's the parent of the working directory, and 6.1129 + restores the contents of the file to their state as of that 6.1130 + changeset. (That's a long-winded way of saying that, in the 6.1131 + normal case, it undoes your modifications.)</para> 6.1132 + 6.1133 + <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 6.1134 + revert</command> command works with yet another small example. 6.1135 + We'll begin by modifying a file that Mercurial is already 6.1136 + tracking.</para> 6.1137 + 6.1138 + &interaction.daily.revert.modify; 6.1139 + 6.1140 + <para id="x_e4">If we don't 6.1141 + want that change, we can simply <command role="hg-cmd">hg 6.1142 + revert</command> the file.</para> 6.1143 + 6.1144 + &interaction.daily.revert.unmodify; 6.1145 + 6.1146 + <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 6.1147 + provides us with an extra degree of safety by saving our 6.1148 + modified file with a <filename>.orig</filename> 6.1149 + extension.</para> 6.1150 + 6.1151 + &interaction.daily.revert.status; 6.1152 + 6.1153 + <tip> 6.1154 + <title>Be careful with <filename>.orig</filename> files</title> 6.1155 + 6.1156 + <para id="x_6b8">It's extremely unlikely that you are either using 6.1157 + Mercurial to manage files with <filename>.orig</filename> 6.1158 + extensions or that you even care about the contents of such 6.1159 + files. Just in case, though, it's useful to remember that 6.1160 + <command role="hg-cmd">hg revert</command> will 6.1161 + unconditionally overwrite an existing file with a 6.1162 + <filename>.orig</filename> extension. For instance, if you 6.1163 + already have a file named <filename>foo.orig</filename> when 6.1164 + you revert <filename>foo</filename>, the contents of 6.1165 + <filename>foo.orig</filename> will be clobbered.</para> 6.1166 + </tip> 6.1167 + 6.1168 + <para id="x_e6">Here is a summary of the cases that the <command 6.1169 + role="hg-cmd">hg revert</command> command can deal with. We 6.1170 + will describe each of these in more detail in the section that 6.1171 + follows.</para> 6.1172 + <itemizedlist> 6.1173 + <listitem><para id="x_e7">If you modify a file, it will restore the file 6.1174 + to its unmodified state.</para> 6.1175 + </listitem> 6.1176 + <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 6.1177 + file, it will undo the <quote>added</quote> state of the 6.1178 + file, but leave the file itself untouched.</para> 6.1179 + </listitem> 6.1180 + <listitem><para id="x_e9">If you delete a file without telling Mercurial, 6.1181 + it will restore the file to its unmodified contents.</para> 6.1182 + </listitem> 6.1183 + <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 6.1184 + remove</command> command to remove a file, it will undo 6.1185 + the <quote>removed</quote> state of the file, and restore 6.1186 + the file to its unmodified contents.</para> 6.1187 + </listitem></itemizedlist> 6.1188 + 6.1189 + <sect2 id="sec:undo:mgmt"> 6.1190 + <title>File management errors</title> 6.1191 + 6.1192 + <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 6.1193 + useful for more than just modified files. It lets you reverse 6.1194 + the results of all of Mercurial's file management 6.1195 + commands&emdash;<command role="hg-cmd">hg add</command>, 6.1196 + <command role="hg-cmd">hg remove</command>, and so on.</para> 6.1197 + 6.1198 + <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 6.1199 + then decide that in fact you don't want Mercurial to track it, 6.1200 + use <command role="hg-cmd">hg revert</command> to undo the 6.1201 + add. Don't worry; Mercurial will not modify the file in any 6.1202 + way. It will just <quote>unmark</quote> the file.</para> 6.1203 + 6.1204 + &interaction.daily.revert.add; 6.1205 + 6.1206 + <para id="x_ed">Similarly, if you ask Mercurial to <command 6.1207 + role="hg-cmd">hg remove</command> a file, you can use 6.1208 + <command role="hg-cmd">hg revert</command> to restore it to 6.1209 + the contents it had as of the parent of the working directory. 6.1210 + &interaction.daily.revert.remove; This works just as 6.1211 + well for a file that you deleted by hand, without telling 6.1212 + Mercurial (recall that in Mercurial terminology, this kind of 6.1213 + file is called <quote>missing</quote>).</para> 6.1214 + 6.1215 + &interaction.daily.revert.missing; 6.1216 + 6.1217 + <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 6.1218 + the copied-to file remains in your working directory 6.1219 + afterwards, untracked. Since a copy doesn't affect the 6.1220 + copied-from file in any way, Mercurial doesn't do anything 6.1221 + with the copied-from file.</para> 6.1222 + 6.1223 + &interaction.daily.revert.copy; 6.1224 + </sect2> 6.1225 + </sect1> 6.1226 + 6.1227 + <sect1> 6.1228 + <title>Dealing with committed changes</title> 6.1229 + 6.1230 + <para id="x_f5">Consider a case where you have committed a change 6.1231 + <emphasis>a</emphasis>, and another change 6.1232 + <emphasis>b</emphasis> on top of it; you then realise that 6.1233 + change <emphasis>a</emphasis> was incorrect. Mercurial lets you 6.1234 + <quote>back out</quote> an entire changeset automatically, and 6.1235 + building blocks that let you reverse part of a changeset by 6.1236 + hand.</para> 6.1237 + 6.1238 + <para id="x_f6">Before you read this section, here's something to 6.1239 + keep in mind: the <command role="hg-cmd">hg backout</command> 6.1240 + command undoes the effect of a change by 6.1241 + <emphasis>adding</emphasis> to your repository's history, not by 6.1242 + modifying or erasing it. It's the right tool to use if you're 6.1243 + fixing bugs, but not if you're trying to undo some change that 6.1244 + has catastrophic consequences. To deal with those, see 6.1245 + <xref linkend="sec:undo:aaaiiieee"/>.</para> 6.1246 + 6.1247 + <sect2> 6.1248 + <title>Backing out a changeset</title> 6.1249 + 6.1250 + <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 6.1251 + lets you <quote>undo</quote> the effects of an entire 6.1252 + changeset in an automated fashion. Because Mercurial's 6.1253 + history is immutable, this command <emphasis>does 6.1254 + not</emphasis> get rid of the changeset you want to undo. 6.1255 + Instead, it creates a new changeset that 6.1256 + <emphasis>reverses</emphasis> the effect of the to-be-undone 6.1257 + changeset.</para> 6.1258 + 6.1259 + <para id="x_f8">The operation of the <command role="hg-cmd">hg 6.1260 + backout</command> command is a little intricate, so let's 6.1261 + illustrate it with some examples. First, we'll create a 6.1262 + repository with some simple changes.</para> 6.1263 + 6.1264 + &interaction.backout.init; 6.1265 + 6.1266 + <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 6.1267 + takes a single changeset ID as its argument; this is the 6.1268 + changeset to back out. Normally, <command role="hg-cmd">hg 6.1269 + backout</command> will drop you into a text editor to write 6.1270 + a commit message, so you can record why you're backing the 6.1271 + change out. In this example, we provide a commit message on 6.1272 + the command line using the <option 6.1273 + role="hg-opt-backout">-m</option> option.</para> 6.1274 + 6.1275 + </sect2> 6.1276 + <sect2> 6.1277 + <title>Backing out the tip changeset</title> 6.1278 + 6.1279 + <para id="x_fa">We're going to start by backing out the last changeset we 6.1280 + committed.</para> 6.1281 + 6.1282 + &interaction.backout.simple; 6.1283 + 6.1284 + <para id="x_fb">You can see that the second line from 6.1285 + <filename>myfile</filename> is no longer present. Taking a 6.1286 + look at the output of <command role="hg-cmd">hg log</command> 6.1287 + gives us an idea of what the <command role="hg-cmd">hg 6.1288 + backout</command> command has done. 6.1289 + &interaction.backout.simple.log; Notice that the new changeset 6.1290 + that <command role="hg-cmd">hg backout</command> has created 6.1291 + is a child of the changeset we backed out. It's easier to see 6.1292 + this in <xref linkend="fig:undo:backout"/>, which presents a 6.1293 + graphical view of the change history. As you can see, the 6.1294 + history is nice and linear.</para> 6.1295 + 6.1296 + <figure id="fig:undo:backout"> 6.1297 + <title>Backing out a change using the <command 6.1298 + role="hg-cmd">hg backout</command> command</title> 6.1299 + <mediaobject> 6.1300 + <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject> 6.1301 + <textobject><phrase>XXX add text</phrase></textobject> 6.1302 + </mediaobject> 6.1303 + </figure> 6.1304 + 6.1305 + </sect2> 6.1306 + <sect2> 6.1307 + <title>Backing out a non-tip change</title> 6.1308 + 6.1309 + <para id="x_fd">If you want to back out a change other than the last one 6.1310 + you committed, pass the <option 6.1311 + role="hg-opt-backout">--merge</option> option to the 6.1312 + <command role="hg-cmd">hg backout</command> command.</para> 6.1313 + 6.1314 + &interaction.backout.non-tip.clone; 6.1315 + 6.1316 + <para id="x_fe">This makes backing out any changeset a 6.1317 + <quote>one-shot</quote> operation that's usually simple and 6.1318 + fast.</para> 6.1319 + 6.1320 + &interaction.backout.non-tip.backout; 6.1321 + 6.1322 + <para id="x_ff">If you take a look at the contents of 6.1323 + <filename>myfile</filename> after the backout finishes, you'll 6.1324 + see that the first and third changes are present, but not the 6.1325 + second.</para> 6.1326 + 6.1327 + &interaction.backout.non-tip.cat; 6.1328 + 6.1329 + <para id="x_100">As the graphical history in <xref 6.1330 + linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 6.1331 + still commits one change in this kind of situation (the 6.1332 + box-shaped node is the ones that Mercurial commits 6.1333 + automatically), but the revision graph now looks different. 6.1334 + Before Mercurial begins the backout process, it first 6.1335 + remembers what the current parent of the working directory is. 6.1336 + It then backs out the target changeset, and commits that as a 6.1337 + changeset. Finally, it merges back to the previous parent of 6.1338 + the working directory, but notice that it <emphasis>does not 6.1339 + commit</emphasis> the result of the merge. The repository 6.1340 + now contains two heads, and the working directory is in a 6.1341 + merge state.</para> 6.1342 + 6.1343 + <figure id="fig:undo:backout-non-tip"> 6.1344 + <title>Automated backout of a non-tip change using the 6.1345 + <command role="hg-cmd">hg backout</command> command</title> 6.1346 + <mediaobject> 6.1347 + <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject> 6.1348 + <textobject><phrase>XXX add text</phrase></textobject> 6.1349 + </mediaobject> 6.1350 + </figure> 6.1351 + 6.1352 + <para id="x_103">The result is that you end up <quote>back where you 6.1353 + were</quote>, only with some extra history that undoes the 6.1354 + effect of the changeset you wanted to back out.</para> 6.1355 + 6.1356 + <para id="x_6b9">You might wonder why Mercurial does not commit the result 6.1357 + of the merge that it performed. The reason lies in Mercurial 6.1358 + behaving conservatively: a merge naturally has more scope for 6.1359 + error than simply undoing the effect of the tip changeset, 6.1360 + so your work will be safest if you first inspect (and test!) 6.1361 + the result of the merge, <emphasis>then</emphasis> commit 6.1362 + it.</para> 6.1363 + 6.1364 + <sect3> 6.1365 + <title>Always use the <option 6.1366 + role="hg-opt-backout">--merge</option> option</title> 6.1367 + 6.1368 + <para id="x_104">In fact, since the <option 6.1369 + role="hg-opt-backout">--merge</option> option will do the 6.1370 + <quote>right thing</quote> whether or not the changeset 6.1371 + you're backing out is the tip (i.e. it won't try to merge if 6.1372 + it's backing out the tip, since there's no need), you should 6.1373 + <emphasis>always</emphasis> use this option when you run the 6.1374 + <command role="hg-cmd">hg backout</command> command.</para> 6.1375 + 6.1376 + </sect3> 6.1377 + </sect2> 6.1378 + <sect2> 6.1379 + <title>Gaining more control of the backout process</title> 6.1380 + 6.1381 + <para id="x_105">While I've recommended that you always use the <option 6.1382 + role="hg-opt-backout">--merge</option> option when backing 6.1383 + out a change, the <command role="hg-cmd">hg backout</command> 6.1384 + command lets you decide how to merge a backout changeset. 6.1385 + Taking control of the backout process by hand is something you 6.1386 + will rarely need to do, but it can be useful to understand 6.1387 + what the <command role="hg-cmd">hg backout</command> command 6.1388 + is doing for you automatically. To illustrate this, let's 6.1389 + clone our first repository, but omit the backout change that 6.1390 + it contains.</para> 6.1391 + 6.1392 + &interaction.backout.manual.clone; 6.1393 + 6.1394 + <para id="x_106">As with our 6.1395 + earlier example, We'll commit a third changeset, then back out 6.1396 + its parent, and see what happens.</para> 6.1397 + 6.1398 + &interaction.backout.manual.backout; 6.1399 + 6.1400 + <para id="x_107">Our new changeset is again a descendant of the changeset 6.1401 + we backout out; it's thus a new head, <emphasis>not</emphasis> 6.1402 + a descendant of the changeset that was the tip. The <command 6.1403 + role="hg-cmd">hg backout</command> command was quite 6.1404 + explicit in telling us this.</para> 6.1405 + 6.1406 + &interaction.backout.manual.log; 6.1407 + 6.1408 + <para id="x_108">Again, it's easier to see what has happened by looking at 6.1409 + a graph of the revision history, in <xref 6.1410 + linkend="fig:undo:backout-manual"/>. This makes it clear 6.1411 + that when we use <command role="hg-cmd">hg backout</command> 6.1412 + to back out a change other than the tip, Mercurial adds a new 6.1413 + head to the repository (the change it committed is 6.1414 + box-shaped).</para> 6.1415 + 6.1416 + <figure id="fig:undo:backout-manual"> 6.1417 + <title>Backing out a change using the <command 6.1418 + role="hg-cmd">hg backout</command> command</title> 6.1419 + <mediaobject> 6.1420 + <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject> 6.1421 + <textobject><phrase>XXX add text</phrase></textobject> 6.1422 + </mediaobject> 6.1423 + </figure> 6.1424 + 6.1425 + <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 6.1426 + command has completed, it leaves the new 6.1427 + <quote>backout</quote> changeset as the parent of the working 6.1428 + directory.</para> 6.1429 + 6.1430 + &interaction.backout.manual.parents; 6.1431 + 6.1432 + <para id="x_10b">Now we have two isolated sets of changes.</para> 6.1433 + 6.1434 + &interaction.backout.manual.heads; 6.1435 + 6.1436 + <para id="x_10c">Let's think about what we expect to see as the contents of 6.1437 + <filename>myfile</filename> now. The first change should be 6.1438 + present, because we've never backed it out. The second change 6.1439 + should be missing, as that's the change we backed out. Since 6.1440 + the history graph shows the third change as a separate head, 6.1441 + we <emphasis>don't</emphasis> expect to see the third change 6.1442 + present in <filename>myfile</filename>.</para> 6.1443 + 6.1444 + &interaction.backout.manual.cat; 6.1445 + 6.1446 + <para id="x_10d">To get the third change back into the file, we just do a 6.1447 + normal merge of our two heads.</para> 6.1448 + 6.1449 + &interaction.backout.manual.merge; 6.1450 + 6.1451 + <para id="x_10e">Afterwards, the graphical history of our 6.1452 + repository looks like 6.1453 + <xref linkend="fig:undo:backout-manual-merge"/>.</para> 6.1454 + 6.1455 + <figure id="fig:undo:backout-manual-merge"> 6.1456 + <title>Manually merging a backout change</title> 6.1457 + <mediaobject> 6.1458 + <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject> 6.1459 + <textobject><phrase>XXX add text</phrase></textobject> 6.1460 + </mediaobject> 6.1461 + </figure> 6.1462 + 6.1463 + </sect2> 6.1464 + <sect2> 6.1465 + <title>Why <command role="hg-cmd">hg backout</command> works as 6.1466 + it does</title> 6.1467 + 6.1468 + <para id="x_110">Here's a brief description of how the <command 6.1469 + role="hg-cmd">hg backout</command> command works.</para> 6.1470 + <orderedlist> 6.1471 + <listitem><para id="x_111">It ensures that the working directory is 6.1472 + <quote>clean</quote>, i.e. that the output of <command 6.1473 + role="hg-cmd">hg status</command> would be empty.</para> 6.1474 + </listitem> 6.1475 + <listitem><para id="x_112">It remembers the current parent of the working 6.1476 + directory. Let's call this changeset 6.1477 + <literal>orig</literal>.</para> 6.1478 + </listitem> 6.1479 + <listitem><para id="x_113">It does the equivalent of a <command 6.1480 + role="hg-cmd">hg update</command> to sync the working 6.1481 + directory to the changeset you want to back out. Let's 6.1482 + call this changeset <literal>backout</literal>.</para> 6.1483 + </listitem> 6.1484 + <listitem><para id="x_114">It finds the parent of that changeset. Let's 6.1485 + call that changeset <literal>parent</literal>.</para> 6.1486 + </listitem> 6.1487 + <listitem><para id="x_115">For each file that the 6.1488 + <literal>backout</literal> changeset affected, it does the 6.1489 + equivalent of a <command role="hg-cmd">hg revert -r 6.1490 + parent</command> on that file, to restore it to the 6.1491 + contents it had before that changeset was 6.1492 + committed.</para> 6.1493 + </listitem> 6.1494 + <listitem><para id="x_116">It commits the result as a new changeset. 6.1495 + This changeset has <literal>backout</literal> as its 6.1496 + parent.</para> 6.1497 + </listitem> 6.1498 + <listitem><para id="x_117">If you specify <option 6.1499 + role="hg-opt-backout">--merge</option> on the command 6.1500 + line, it merges with <literal>orig</literal>, and commits 6.1501 + the result of the merge.</para> 6.1502 + </listitem></orderedlist> 6.1503 + 6.1504 + <para id="x_118">An alternative way to implement the <command 6.1505 + role="hg-cmd">hg backout</command> command would be to 6.1506 + <command role="hg-cmd">hg export</command> the 6.1507 + to-be-backed-out changeset as a diff, then use the <option 6.1508 + role="cmd-opt-patch">--reverse</option> option to the 6.1509 + <command>patch</command> command to reverse the effect of the 6.1510 + change without fiddling with the working directory. This 6.1511 + sounds much simpler, but it would not work nearly as 6.1512 + well.</para> 6.1513 + 6.1514 + <para id="x_119">The reason that <command role="hg-cmd">hg 6.1515 + backout</command> does an update, a commit, a merge, and 6.1516 + another commit is to give the merge machinery the best chance 6.1517 + to do a good job when dealing with all the changes 6.1518 + <emphasis>between</emphasis> the change you're backing out and 6.1519 + the current tip.</para> 6.1520 + 6.1521 + <para id="x_11a">If you're backing out a changeset that's 100 revisions 6.1522 + back in your project's history, the chances that the 6.1523 + <command>patch</command> command will be able to apply a 6.1524 + reverse diff cleanly are not good, because intervening changes 6.1525 + are likely to have <quote>broken the context</quote> that 6.1526 + <command>patch</command> uses to determine whether it can 6.1527 + apply a patch (if this sounds like gibberish, see <xref 6.1528 + linkend="sec:mq:patch"/> for a 6.1529 + discussion of the <command>patch</command> command). Also, 6.1530 + Mercurial's merge machinery will handle files and directories 6.1531 + being renamed, permission changes, and modifications to binary 6.1532 + files, none of which <command>patch</command> can deal 6.1533 + with.</para> 6.1534 + 6.1535 + </sect2> 6.1536 + </sect1> 6.1537 + <sect1 id="sec:undo:aaaiiieee"> 6.1538 + <title>Changes that should never have been</title> 6.1539 + 6.1540 + <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 6.1541 + backout</command> command is exactly what you need if you want 6.1542 + to undo the effects of a change. It leaves a permanent record 6.1543 + of exactly what you did, both when committing the original 6.1544 + changeset and when you cleaned up after it.</para> 6.1545 + 6.1546 + <para id="x_11c">On rare occasions, though, you may find that you've 6.1547 + committed a change that really should not be present in the 6.1548 + repository at all. For example, it would be very unusual, and 6.1549 + usually considered a mistake, to commit a software project's 6.1550 + object files as well as its source files. Object files have 6.1551 + almost no intrinsic value, and they're <emphasis>big</emphasis>, 6.1552 + so they increase the size of the repository and the amount of 6.1553 + time it takes to clone or pull changes.</para> 6.1554 + 6.1555 + <para id="x_11d">Before I discuss the options that you have if you commit a 6.1556 + <quote>brown paper bag</quote> change (the kind that's so bad 6.1557 + that you want to pull a brown paper bag over your head), let me 6.1558 + first discuss some approaches that probably won't work.</para> 6.1559 + 6.1560 + <para id="x_11e">Since Mercurial treats history as 6.1561 + accumulative&emdash;every change builds on top of all changes 6.1562 + that preceded it&emdash;you generally can't just make disastrous 6.1563 + changes disappear. The one exception is when you've just 6.1564 + committed a change, and it hasn't been pushed or pulled into 6.1565 + another repository. That's when you can safely use the <command 6.1566 + role="hg-cmd">hg rollback</command> command, as I detailed in 6.1567 + <xref linkend="sec:undo:rollback"/>.</para> 6.1568 + 6.1569 + <para id="x_11f">After you've pushed a bad change to another repository, you 6.1570 + <emphasis>could</emphasis> still use <command role="hg-cmd">hg 6.1571 + rollback</command> to make your local copy of the change 6.1572 + disappear, but it won't have the consequences you want. The 6.1573 + change will still be present in the remote repository, so it 6.1574 + will reappear in your local repository the next time you 6.1575 + pull.</para> 6.1576 + 6.1577 + <para id="x_120">If a situation like this arises, and you know which 6.1578 + repositories your bad change has propagated into, you can 6.1579 + <emphasis>try</emphasis> to get rid of the change from 6.1580 + <emphasis>every</emphasis> one of those repositories. This is, 6.1581 + of course, not a satisfactory solution: if you miss even a 6.1582 + single repository while you're expunging, the change is still 6.1583 + <quote>in the wild</quote>, and could propagate further.</para> 6.1584 + 6.1585 + <para id="x_121">If you've committed one or more changes 6.1586 + <emphasis>after</emphasis> the change that you'd like to see 6.1587 + disappear, your options are further reduced. Mercurial doesn't 6.1588 + provide a way to <quote>punch a hole</quote> in history, leaving 6.1589 + changesets intact.</para> 6.1590 + 6.1591 + <sect2> 6.1592 + <title>Backing out a merge</title> 6.1593 + 6.1594 + <para id="x_6ba">Since merges are often complicated, it is not unheard of 6.1595 + for a merge to be mangled badly, but committed erroneously. 6.1596 + Mercurial provides an important safeguard against bad merges 6.1597 + by refusing to commit unresolved files, but human ingenuity 6.1598 + guarantees that it is still possible to mess a merge up and 6.1599 + commit it.</para> 6.1600 + 6.1601 + <para id="x_6bb">Given a bad merge that has been committed, usually the 6.1602 + best way to approach it is to simply try to repair the damage 6.1603 + by hand. A complete disaster that cannot be easily fixed up 6.1604 + by hand ought to be very rare, but the <command 6.1605 + role="hg-cmd">hg backout</command> command may help in 6.1606 + making the cleanup easier. It offers a <option 6.1607 + role="hg-opt-backout">--parent</option> option, which lets 6.1608 + you specify which parent to revert to when backing out a 6.1609 + merge.</para> 6.1610 + 6.1611 + <figure id="fig:undo:bad-merge-1"> 6.1612 + <title>A bad merge</title> 6.1613 + <mediaobject> 6.1614 + <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject> 6.1615 + <textobject><phrase>XXX add text</phrase></textobject> 6.1616 + </mediaobject> 6.1617 + </figure> 6.1618 + 6.1619 + <para id="x_6bc">Suppose we have a revision graph like that in <xref 6.1620 + linkend="fig:undo:bad-merge-1"/>. What we'd like is to 6.1621 + <emphasis>redo</emphasis> the merge of revisions 2 and 6.1622 + 3.</para> 6.1623 + 6.1624 + <para id="x_6bd">One way to do so would be as follows.</para> 6.1625 + 6.1626 + <orderedlist> 6.1627 + <listitem> 6.1628 + <para id="x_6be">Call <command role="hg-cmd">hg backout --rev=4 6.1629 + --parent=2</command>. This tells <command 6.1630 + role="hg-cmd">hg backout</command> to back out revision 6.1631 + 4, which is the bad merge, and to when deciding which 6.1632 + revision to prefer, to choose parent 2, one of the parents 6.1633 + of the merge. The effect can be seen in <xref 6.1634 + linkend="fig:undo:bad-merge-2"/>.</para> 6.1635 + <figure id="fig:undo:bad-merge-2"> 6.1636 + <title>Backing out the merge, favoring one parent</title> 6.1637 + <mediaobject> 6.1638 + <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject> 6.1639 + <textobject><phrase>XXX add text</phrase></textobject> 6.1640 + </mediaobject> 6.1641 + </figure> 6.1642 + </listitem> 6.1643 + 6.1644 + <listitem> 6.1645 + <para id="x_6bf">Call <command role="hg-cmd">hg backout --rev=4 6.1646 + --parent=3</command>. This tells <command 6.1647 + role="hg-cmd">hg backout</command> to back out revision 6.1648 + 4 again, but this time to choose parent 3, the other 6.1649 + parent of the merge. The result is visible in <xref 6.1650 + linkend="fig:undo:bad-merge-3"/>, in which the repository 6.1651 + now contains three heads.</para> 6.1652 + <figure id="fig:undo:bad-merge-3"> 6.1653 + <title>Backing out the merge, favoring the other 6.1654 + parent</title> 6.1655 + <mediaobject> 6.1656 + <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject> 6.1657 + <textobject><phrase>XXX add text</phrase></textobject> 6.1658 + </mediaobject> 6.1659 + </figure> 6.1660 + </listitem> 6.1661 + 6.1662 + <listitem> 6.1663 + <para id="x_6c0">Redo the bad merge by merging the two backout heads, 6.1664 + which reduces the number of heads in the repository to 6.1665 + two, as can be seen in <xref 6.1666 + linkend="fig:undo:bad-merge-4"/>.</para> 6.1667 + <figure id="fig:undo:bad-merge-4"> 6.1668 + <title>Merging the backouts</title> 6.1669 + <mediaobject> 6.1670 + <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject> 6.1671 + <textobject><phrase>XXX add text</phrase></textobject> 6.1672 + </mediaobject> 6.1673 + </figure> 6.1674 + </listitem> 6.1675 + 6.1676 + <listitem> 6.1677 + <para id="x_6c1">Merge with the commit that was made after the bad 6.1678 + merge, as shown in <xref 6.1679 + linkend="fig:undo:bad-merge-5"/>.</para> 6.1680 + <figure id="fig:undo:bad-merge-5"> 6.1681 + <title>Merging the backouts</title> 6.1682 + <mediaobject> 6.1683 + <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject> 6.1684 + <textobject><phrase>XXX add text</phrase></textobject> 6.1685 + </mediaobject> 6.1686 + </figure> 6.1687 + </listitem> 6.1688 + </orderedlist> 6.1689 + </sect2> 6.1690 + 6.1691 + <sect2> 6.1692 + <title>Protect yourself from <quote>escaped</quote> 6.1693 + changes</title> 6.1694 + 6.1695 + <para id="x_123">If you've committed some changes to your local repository 6.1696 + and they've been pushed or pulled somewhere else, this isn't 6.1697 + necessarily a disaster. You can protect yourself ahead of 6.1698 + time against some classes of bad changeset. This is 6.1699 + particularly easy if your team usually pulls changes from a 6.1700 + central repository.</para> 6.1701 + 6.1702 + <para id="x_124">By configuring some hooks on that repository to validate 6.1703 + incoming changesets (see chapter <xref linkend="chap:hook"/>), 6.1704 + you can 6.1705 + automatically prevent some kinds of bad changeset from being 6.1706 + pushed to the central repository at all. With such a 6.1707 + configuration in place, some kinds of bad changeset will 6.1708 + naturally tend to <quote>die out</quote> because they can't 6.1709 + propagate into the central repository. Better yet, this 6.1710 + happens without any need for explicit intervention.</para> 6.1711 + 6.1712 + <para id="x_125">For instance, an incoming change hook that 6.1713 + verifies that a changeset will actually compile can prevent 6.1714 + people from inadvertently <quote>breaking the 6.1715 + build</quote>.</para> 6.1716 + </sect2> 6.1717 + 6.1718 + <sect2> 6.1719 + <title>What to do about sensitive changes that escape</title> 6.1720 + 6.1721 + <para id="x_6c2">Even a carefully run project can suffer an unfortunate 6.1722 + event such as the committing and uncontrolled propagation of a 6.1723 + file that contains important passwords.</para> 6.1724 + 6.1725 + <para id="x_6c3">If something like this happens to you, and the information 6.1726 + that gets accidentally propagated is truly sensitive, your 6.1727 + first step should be to mitigate the effect of the leak 6.1728 + without trying to control the leak itself. If you are not 100% 6.1729 + certain that you know exactly who could have seen the changes, 6.1730 + you should immediately change passwords, cancel credit cards, 6.1731 + or find some other way to make sure that the information that 6.1732 + has leaked is no longer useful. In other words, assume that 6.1733 + the change has propagated far and wide, and that there's 6.1734 + nothing more you can do.</para> 6.1735 + 6.1736 + <para id="x_6c4">You might hope that there would be mechanisms you could 6.1737 + use to either figure out who has seen a change or to erase the 6.1738 + change permanently everywhere, but there are good reasons why 6.1739 + these are not possible.</para> 6.1740 + 6.1741 + <para id="x_6c5">Mercurial does not provide an audit trail of who has 6.1742 + pulled changes from a repository, because it is usually either 6.1743 + impossible to record such information or trivial to spoof it. 6.1744 + In a multi-user or networked environment, you should thus be 6.1745 + extremely skeptical of yourself if you think that you have 6.1746 + identified every place that a sensitive changeset has 6.1747 + propagated to. Don't forget that people can and will send 6.1748 + bundles by email, have their backup software save data 6.1749 + offsite, carry repositories on USB sticks, and find other 6.1750 + completely innocent ways to confound your attempts to track 6.1751 + down every copy of a problematic change.</para> 6.1752 + 6.1753 + <para id="x_6c6">Mercurial also does not provide a way to make a file or 6.1754 + changeset completely disappear from history, because there is 6.1755 + no way to enforce its disappearance; someone could easily 6.1756 + modify their copy of Mercurial to ignore such directives. In 6.1757 + addition, even if Mercurial provided such a capability, 6.1758 + someone who simply hadn't pulled a <quote>make this file 6.1759 + disappear</quote> changeset wouldn't be affected by it, nor 6.1760 + would web crawlers visiting at the wrong time, disk backups, 6.1761 + or other mechanisms. Indeed, no distributed revision control 6.1762 + system can make data reliably vanish. Providing the illusion 6.1763 + of such control could easily give a false sense of security, 6.1764 + and be worse than not providing it at all.</para> 6.1765 + </sect2> 6.1766 + </sect1> 6.1767 + 6.1768 + <sect1 id="sec:undo:bisect"> 6.1769 + <title>Finding the source of a bug</title> 6.1770 + 6.1771 + <para id="x_126">While it's all very well to be able to back out a changeset 6.1772 + that introduced a bug, this requires that you know which 6.1773 + changeset to back out. Mercurial provides an invaluable 6.1774 + command, called <command role="hg-cmd">hg bisect</command>, that 6.1775 + helps you to automate this process and accomplish it very 6.1776 + efficiently.</para> 6.1777 + 6.1778 + <para id="x_127">The idea behind the <command role="hg-cmd">hg 6.1779 + bisect</command> command is that a changeset has introduced 6.1780 + some change of behavior that you can identify with a simple 6.1781 + pass/fail test. You don't know which piece of code introduced the 6.1782 + change, but you know how to test for the presence of the bug. 6.1783 + The <command role="hg-cmd">hg bisect</command> command uses your 6.1784 + test to direct its search for the changeset that introduced the 6.1785 + code that caused the bug.</para> 6.1786 + 6.1787 + <para id="x_128">Here are a few scenarios to help you understand how you 6.1788 + might apply this command.</para> 6.1789 + <itemizedlist> 6.1790 + <listitem><para id="x_129">The most recent version of your software has a 6.1791 + bug that you remember wasn't present a few weeks ago, but 6.1792 + you don't know when it was introduced. Here, your binary 6.1793 + test checks for the presence of that bug.</para> 6.1794 + </listitem> 6.1795 + <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 6.1796 + close the entry in your team's bug database. The bug 6.1797 + database requires a changeset ID when you close an entry, 6.1798 + but you don't remember which changeset you fixed the bug in. 6.1799 + Once again, your binary test checks for the presence of the 6.1800 + bug.</para> 6.1801 + </listitem> 6.1802 + <listitem><para id="x_12b">Your software works correctly, but runs 15% 6.1803 + slower than the last time you measured it. You want to know 6.1804 + which changeset introduced the performance regression. In 6.1805 + this case, your binary test measures the performance of your 6.1806 + software, to see whether it's <quote>fast</quote> or 6.1807 + <quote>slow</quote>.</para> 6.1808 + </listitem> 6.1809 + <listitem><para id="x_12c">The sizes of the components of your project that 6.1810 + you ship exploded recently, and you suspect that something 6.1811 + changed in the way you build your project.</para> 6.1812 + </listitem></itemizedlist> 6.1813 + 6.1814 + <para id="x_12d">From these examples, it should be clear that the <command 6.1815 + role="hg-cmd">hg bisect</command> command is not useful only 6.1816 + for finding the sources of bugs. You can use it to find any 6.1817 + <quote>emergent property</quote> of a repository (anything that 6.1818 + you can't find from a simple text search of the files in the 6.1819 + tree) for which you can write a binary test.</para> 6.1820 + 6.1821 + <para id="x_12e">We'll introduce a little bit of terminology here, just to 6.1822 + make it clear which parts of the search process are your 6.1823 + responsibility, and which are Mercurial's. A 6.1824 + <emphasis>test</emphasis> is something that 6.1825 + <emphasis>you</emphasis> run when <command role="hg-cmd">hg 6.1826 + bisect</command> chooses a changeset. A 6.1827 + <emphasis>probe</emphasis> is what <command role="hg-cmd">hg 6.1828 + bisect</command> runs to tell whether a revision is good. 6.1829 + Finally, we'll use the word <quote>bisect</quote>, as both a 6.1830 + noun and a verb, to stand in for the phrase <quote>search using 6.1831 + the <command role="hg-cmd">hg bisect</command> 6.1832 + command</quote>.</para> 6.1833 + 6.1834 + <para id="x_12f">One simple way to automate the searching process would be 6.1835 + simply to probe every changeset. However, this scales poorly. 6.1836 + If it took ten minutes to test a single changeset, and you had 6.1837 + 10,000 changesets in your repository, the exhaustive approach 6.1838 + would take on average 35 <emphasis>days</emphasis> to find the 6.1839 + changeset that introduced a bug. Even if you knew that the bug 6.1840 + was introduced by one of the last 500 changesets, and limited 6.1841 + your search to those, you'd still be looking at over 40 hours to 6.1842 + find the changeset that introduced your bug.</para> 6.1843 + 6.1844 + <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 6.1845 + does is use its knowledge of the <quote>shape</quote> of your 6.1846 + project's revision history to perform a search in time 6.1847 + proportional to the <emphasis>logarithm</emphasis> of the number 6.1848 + of changesets to check (the kind of search it performs is called 6.1849 + a dichotomic search). With this approach, searching through 6.1850 + 10,000 changesets will take less than three hours, even at ten 6.1851 + minutes per test (the search will require about 14 tests). 6.1852 + Limit your search to the last hundred changesets, and it will 6.1853 + take only about an hour (roughly seven tests).</para> 6.1854 + 6.1855 + <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 6.1856 + aware of the <quote>branchy</quote> nature of a Mercurial 6.1857 + project's revision history, so it has no problems dealing with 6.1858 + branches, merges, or multiple heads in a repository. It can 6.1859 + prune entire branches of history with a single probe, which is 6.1860 + how it operates so efficiently.</para> 6.1861 + 6.1862 + <sect2> 6.1863 + <title>Using the <command role="hg-cmd">hg bisect</command> 6.1864 + command</title> 6.1865 + 6.1866 + <para id="x_132">Here's an example of <command role="hg-cmd">hg 6.1867 + bisect</command> in action.</para> 6.1868 + 6.1869 + <note> 6.1870 + <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 6.1871 + role="hg-cmd">hg bisect</command> was not a core command: 6.1872 + it was distributed with Mercurial as an extension. This 6.1873 + section describes the built-in command, not the old 6.1874 + extension.</para> 6.1875 + </note> 6.1876 + 6.1877 + <para id="x_134">Now let's create a repository, so that we can try out the 6.1878 + <command role="hg-cmd">hg bisect</command> command in 6.1879 + isolation.</para> 6.1880 + 6.1881 + &interaction.bisect.init; 6.1882 + 6.1883 + <para id="x_135">We'll simulate a project that has a bug in it in a 6.1884 + simple-minded way: create trivial changes in a loop, and 6.1885 + nominate one specific change that will have the 6.1886 + <quote>bug</quote>. This loop creates 35 changesets, each 6.1887 + adding a single file to the repository. We'll represent our 6.1888 + <quote>bug</quote> with a file that contains the text <quote>i 6.1889 + have a gub</quote>.</para> 6.1890 + 6.1891 + &interaction.bisect.commits; 6.1892 + 6.1893 + <para id="x_136">The next thing that we'd like to do is figure out how to 6.1894 + use the <command role="hg-cmd">hg bisect</command> command. 6.1895 + We can use Mercurial's normal built-in help mechanism for 6.1896 + this.</para> 6.1897 + 6.1898 + &interaction.bisect.help; 6.1899 + 6.1900 + <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 6.1901 + works in steps. Each step proceeds as follows.</para> 6.1902 + <orderedlist> 6.1903 + <listitem><para id="x_138">You run your binary test.</para> 6.1904 + <itemizedlist> 6.1905 + <listitem><para id="x_139">If the test succeeded, you tell <command 6.1906 + role="hg-cmd">hg bisect</command> by running the 6.1907 + <command role="hg-cmd">hg bisect --good</command> 6.1908 + command.</para> 6.1909 + </listitem> 6.1910 + <listitem><para id="x_13a">If it failed, run the <command 6.1911 + role="hg-cmd">hg bisect --bad</command> 6.1912 + command.</para></listitem></itemizedlist> 6.1913 + </listitem> 6.1914 + <listitem><para id="x_13b">The command uses your information to decide 6.1915 + which changeset to test next.</para> 6.1916 + </listitem> 6.1917 + <listitem><para id="x_13c">It updates the working directory to that 6.1918 + changeset, and the process begins again.</para> 6.1919 + </listitem></orderedlist> 6.1920 + <para id="x_13d">The process ends when <command role="hg-cmd">hg 6.1921 + bisect</command> identifies a unique changeset that marks 6.1922 + the point where your test transitioned from 6.1923 + <quote>succeeding</quote> to <quote>failing</quote>.</para> 6.1924 + 6.1925 + <para id="x_13e">To start the search, we must run the <command 6.1926 + role="hg-cmd">hg bisect --reset</command> command.</para> 6.1927 + 6.1928 + &interaction.bisect.search.init; 6.1929 + 6.1930 + <para id="x_13f">In our case, the binary test we use is simple: we check to 6.1931 + see if any file in the repository contains the string <quote>i 6.1932 + have a gub</quote>. If it does, this changeset contains the 6.1933 + change that <quote>caused the bug</quote>. By convention, a 6.1934 + changeset that has the property we're searching for is 6.1935 + <quote>bad</quote>, while one that doesn't is 6.1936 + <quote>good</quote>.</para> 6.1937 + 6.1938 + <para id="x_140">Most of the time, the revision to which the working 6.1939 + directory is synced (usually the tip) already exhibits the 6.1940 + problem introduced by the buggy change, so we'll mark it as 6.1941 + <quote>bad</quote>.</para> 6.1942 + 6.1943 + &interaction.bisect.search.bad-init; 6.1944 + 6.1945 + <para id="x_141">Our next task is to nominate a changeset that we know 6.1946 + <emphasis>doesn't</emphasis> have the bug; the <command 6.1947 + role="hg-cmd">hg bisect</command> command will 6.1948 + <quote>bracket</quote> its search between the first pair of 6.1949 + good and bad changesets. In our case, we know that revision 6.1950 + 10 didn't have the bug. (I'll have more words about choosing 6.1951 + the first <quote>good</quote> changeset later.)</para> 6.1952 + 6.1953 + &interaction.bisect.search.good-init; 6.1954 + 6.1955 + <para id="x_142">Notice that this command printed some output.</para> 6.1956 + <itemizedlist> 6.1957 + <listitem><para id="x_143">It told us how many changesets it must 6.1958 + consider before it can identify the one that introduced 6.1959 + the bug, and how many tests that will require.</para> 6.1960 + </listitem> 6.1961 + <listitem><para id="x_144">It updated the working directory to the next 6.1962 + changeset to test, and told us which changeset it's 6.1963 + testing.</para> 6.1964 + </listitem></itemizedlist> 6.1965 + 6.1966 + <para id="x_145">We now run our test in the working directory. We use the 6.1967 + <command>grep</command> command to see if our 6.1968 + <quote>bad</quote> file is present in the working directory. 6.1969 + If it is, this revision is bad; if not, this revision is good. 6.1970 + &interaction.bisect.search.step1;</para> 6.1971 + 6.1972 + <para id="x_146">This test looks like a perfect candidate for automation, 6.1973 + so let's turn it into a shell function.</para> 6.1974 + &interaction.bisect.search.mytest; 6.1975 + 6.1976 + <para id="x_147">We can now run an entire test step with a single command, 6.1977 + <literal>mytest</literal>.</para> 6.1978 + 6.1979 + &interaction.bisect.search.step2; 6.1980 + 6.1981 + <para id="x_148">A few more invocations of our canned test step command, 6.1982 + and we're done.</para> 6.1983 + 6.1984 + &interaction.bisect.search.rest; 6.1985 + 6.1986 + <para id="x_149">Even though we had 40 changesets to search through, the 6.1987 + <command role="hg-cmd">hg bisect</command> command let us find 6.1988 + the changeset that introduced our <quote>bug</quote> with only 6.1989 + five tests. Because the number of tests that the <command 6.1990 + role="hg-cmd">hg bisect</command> command performs grows 6.1991 + logarithmically with the number of changesets to search, the 6.1992 + advantage that it has over the <quote>brute force</quote> 6.1993 + search approach increases with every changeset you add.</para> 6.1994 + 6.1995 + </sect2> 6.1996 + <sect2> 6.1997 + <title>Cleaning up after your search</title> 6.1998 + 6.1999 + <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 6.2000 + bisect</command> command in a repository, you can use the 6.2001 + <command role="hg-cmd">hg bisect --reset</command> command to 6.2002 + drop the information it was using to drive your search. The 6.2003 + command doesn't use much space, so it doesn't matter if you 6.2004 + forget to run this command. However, <command 6.2005 + role="hg-cmd">hg bisect</command> won't let you start a new 6.2006 + search in that repository until you do a <command 6.2007 + role="hg-cmd">hg bisect --reset</command>.</para> 6.2008 + 6.2009 + &interaction.bisect.search.reset; 6.2010 + 6.2011 + </sect2> 6.2012 + </sect1> 6.2013 + <sect1> 6.2014 + <title>Tips for finding bugs effectively</title> 6.2015 + 6.2016 + <sect2> 6.2017 + <title>Give consistent input</title> 6.2018 + 6.2019 + <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 6.2020 + requires that you correctly report the result of every test 6.2021 + you perform. If you tell it that a test failed when it really 6.2022 + succeeded, it <emphasis>might</emphasis> be able to detect the 6.2023 + inconsistency. If it can identify an inconsistency in your 6.2024 + reports, it will tell you that a particular changeset is both 6.2025 + good and bad. However, it can't do this perfectly; it's about 6.2026 + as likely to report the wrong changeset as the source of the 6.2027 + bug.</para> 6.2028 + 6.2029 + </sect2> 6.2030 + <sect2> 6.2031 + <title>Automate as much as possible</title> 6.2032 + 6.2033 + <para id="x_14c">When I started using the <command role="hg-cmd">hg 6.2034 + bisect</command> command, I tried a few times to run my 6.2035 + tests by hand, on the command line. This is an approach that 6.2036 + I, at least, am not suited to. After a few tries, I found 6.2037 + that I was making enough mistakes that I was having to restart 6.2038 + my searches several times before finally getting correct 6.2039 + results.</para> 6.2040 + 6.2041 + <para id="x_14d">My initial problems with driving the <command 6.2042 + role="hg-cmd">hg bisect</command> command by hand occurred 6.2043 + even with simple searches on small repositories; if the 6.2044 + problem you're looking for is more subtle, or the number of 6.2045 + tests that <command role="hg-cmd">hg bisect</command> must 6.2046 + perform increases, the likelihood of operator error ruining 6.2047 + the search is much higher. Once I started automating my 6.2048 + tests, I had much better results.</para> 6.2049 + 6.2050 + <para id="x_14e">The key to automated testing is twofold:</para> 6.2051 + <itemizedlist> 6.2052 + <listitem><para id="x_14f">always test for the same symptom, and</para> 6.2053 + </listitem> 6.2054 + <listitem><para id="x_150">always feed consistent input to the <command 6.2055 + role="hg-cmd">hg bisect</command> command.</para> 6.2056 + </listitem></itemizedlist> 6.2057 + <para id="x_151">In my tutorial example above, the <command>grep</command> 6.2058 + command tests for the symptom, and the <literal>if</literal> 6.2059 + statement takes the result of this check and ensures that we 6.2060 + always feed the same input to the <command role="hg-cmd">hg 6.2061 + bisect</command> command. The <literal>mytest</literal> 6.2062 + function marries these together in a reproducible way, so that 6.2063 + every test is uniform and consistent.</para> 6.2064 + 6.2065 + </sect2> 6.2066 + <sect2> 6.2067 + <title>Check your results</title> 6.2068 + 6.2069 + <para id="x_152">Because the output of a <command role="hg-cmd">hg 6.2070 + bisect</command> search is only as good as the input you 6.2071 + give it, don't take the changeset it reports as the absolute 6.2072 + truth. A simple way to cross-check its report is to manually 6.2073 + run your test at each of the following changesets:</para> 6.2074 + <itemizedlist> 6.2075 + <listitem><para id="x_153">The changeset that it reports as the first bad 6.2076 + revision. Your test should still report this as 6.2077 + bad.</para> 6.2078 + </listitem> 6.2079 + <listitem><para id="x_154">The parent of that changeset (either parent, 6.2080 + if it's a merge). Your test should report this changeset 6.2081 + as good.</para> 6.2082 + </listitem> 6.2083 + <listitem><para id="x_155">A child of that changeset. Your test should 6.2084 + report this changeset as bad.</para> 6.2085 + </listitem></itemizedlist> 6.2086 + 6.2087 + </sect2> 6.2088 + <sect2> 6.2089 + <title>Beware interference between bugs</title> 6.2090 + 6.2091 + <para id="x_156">It's possible that your search for one bug could be 6.2092 + disrupted by the presence of another. For example, let's say 6.2093 + your software crashes at revision 100, and worked correctly at 6.2094 + revision 50. Unknown to you, someone else introduced a 6.2095 + different crashing bug at revision 60, and fixed it at 6.2096 + revision 80. This could distort your results in one of 6.2097 + several ways.</para> 6.2098 + 6.2099 + <para id="x_157">It is possible that this other bug completely 6.2100 + <quote>masks</quote> yours, which is to say that it occurs 6.2101 + before your bug has a chance to manifest itself. If you can't 6.2102 + avoid that other bug (for example, it prevents your project 6.2103 + from building), and so can't tell whether your bug is present 6.2104 + in a particular changeset, the <command role="hg-cmd">hg 6.2105 + bisect</command> command cannot help you directly. Instead, 6.2106 + you can mark a changeset as untested by running <command 6.2107 + role="hg-cmd">hg bisect --skip</command>.</para> 6.2108 + 6.2109 + <para id="x_158">A different problem could arise if your test for a bug's 6.2110 + presence is not specific enough. If you check for <quote>my 6.2111 + program crashes</quote>, then both your crashing bug and an 6.2112 + unrelated crashing bug that masks it will look like the same 6.2113 + thing, and mislead <command role="hg-cmd">hg 6.2114 + bisect</command>.</para> 6.2115 + 6.2116 + <para id="x_159">Another useful situation in which to use <command 6.2117 + role="hg-cmd">hg bisect --skip</command> is if you can't 6.2118 + test a revision because your project was in a broken and hence 6.2119 + untestable state at that revision, perhaps because someone 6.2120 + checked in a change that prevented the project from 6.2121 + building.</para> 6.2122 + 6.2123 + </sect2> 6.2124 + <sect2> 6.2125 + <title>Bracket your search lazily</title> 6.2126 + 6.2127 + <para id="x_15a">Choosing the first <quote>good</quote> and 6.2128 + <quote>bad</quote> changesets that will mark the end points of 6.2129 + your search is often easy, but it bears a little discussion 6.2130 + nevertheless. From the perspective of <command 6.2131 + role="hg-cmd">hg bisect</command>, the <quote>newest</quote> 6.2132 + changeset is conventionally <quote>bad</quote>, and the older 6.2133 + changeset is <quote>good</quote>.</para> 6.2134 + 6.2135 + <para id="x_15b">If you're having trouble remembering when a suitable 6.2136 + <quote>good</quote> change was, so that you can tell <command 6.2137 + role="hg-cmd">hg bisect</command>, you could do worse than 6.2138 + testing changesets at random. Just remember to eliminate 6.2139 + contenders that can't possibly exhibit the bug (perhaps 6.2140 + because the feature with the bug isn't present yet) and those 6.2141 + where another problem masks the bug (as I discussed 6.2142 + above).</para> 6.2143 + 6.2144 + <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 6.2145 + changesets or months of history, you will only add a handful 6.2146 + of tests to the total number that <command role="hg-cmd">hg 6.2147 + bisect</command> must perform, thanks to its logarithmic 6.2148 + behavior.</para> 6.2149 + 6.2150 + </sect2> 6.2151 + </sect1> 6.2152 </chapter> 6.2153 6.2154 <!-- 6.2155 local variables: 6.2156 sgml-parent-document: ("00book.xml" "book" "chapter") 6.2157 end: 6.2158 ---> 6.2159 \ No newline at end of file 6.2160 +-->
7.1 --- a/fr/ch10-hook.xml Wed Sep 09 15:25:09 2009 +0200 7.2 +++ b/fr/ch10-hook.xml Wed Sep 09 16:07:36 2009 +0200 7.3 @@ -1,1883 +1,1928 @@ 7.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 7.5 7.6 -<chapter> 7.7 -<title>Handling repository events with hooks</title> 7.8 -<para>\label{chap:hook}</para> 7.9 - 7.10 -<para>Mercurial offers a powerful mechanism to let you perform automated 7.11 -actions in response to events that occur in a repository. In some 7.12 -cases, you can even control Mercurial's response to those events.</para> 7.13 - 7.14 -<para>The name Mercurial uses for one of these actions is a <emphasis>hook</emphasis>. 7.15 -Hooks are called <quote>triggers</quote> in some revision control systems, but 7.16 -the two names refer to the same idea.</para> 7.17 - 7.18 -<sect1> 7.19 -<title>An overview of hooks in Mercurial</title> 7.20 - 7.21 -<para>Here is a brief list of the hooks that Mercurial supports. We will 7.22 -revisit each of these hooks in more detail later, in 7.23 -section <xref linkend="sec:hook:ref"/>.</para> 7.24 - 7.25 -<itemizedlist> 7.26 -<listitem><para><literal role="hook">changegroup</literal>: This is run after a group of 7.27 - changesets has been brought into the repository from elsewhere.</para> 7.28 -</listitem> 7.29 -<listitem><para><literal role="hook">commit</literal>: This is run after a new changeset has been 7.30 - created in the local repository.</para> 7.31 -</listitem> 7.32 -<listitem><para><literal role="hook">incoming</literal>: This is run once for each new changeset 7.33 - that is brought into the repository from elsewhere. Notice the 7.34 - difference from <literal role="hook">changegroup</literal>, which is run once per 7.35 - <emphasis>group</emphasis> of changesets brought in.</para> 7.36 -</listitem> 7.37 -<listitem><para><literal role="hook">outgoing</literal>: This is run after a group of changesets 7.38 - has been transmitted from this repository.</para> 7.39 -</listitem> 7.40 -<listitem><para><literal role="hook">prechangegroup</literal>: This is run before starting to 7.41 - bring a group of changesets into the repository. 7.42 -</para> 7.43 -</listitem> 7.44 -<listitem><para><literal role="hook">precommit</literal>: Controlling. This is run before starting 7.45 - a commit. 7.46 -</para> 7.47 -</listitem> 7.48 -<listitem><para><literal role="hook">preoutgoing</literal>: Controlling. This is run before 7.49 - starting to transmit a group of changesets from this repository. 7.50 -</para> 7.51 -</listitem> 7.52 -<listitem><para><literal role="hook">pretag</literal>: Controlling. This is run before creating a tag. 7.53 -</para> 7.54 -</listitem> 7.55 -<listitem><para><literal role="hook">pretxnchangegroup</literal>: Controlling. This is run after a 7.56 - group of changesets has been brought into the local repository from 7.57 - another, but before the transaction completes that will make the 7.58 - changes permanent in the repository. 7.59 -</para> 7.60 -</listitem> 7.61 -<listitem><para><literal role="hook">pretxncommit</literal>: Controlling. This is run after a new 7.62 - changeset has been created in the local repository, but before the 7.63 - transaction completes that will make it permanent. 7.64 -</para> 7.65 -</listitem> 7.66 -<listitem><para><literal role="hook">preupdate</literal>: Controlling. This is run before starting 7.67 - an update or merge of the working directory. 7.68 -</para> 7.69 -</listitem> 7.70 -<listitem><para><literal role="hook">tag</literal>: This is run after a tag is created. 7.71 -</para> 7.72 -</listitem> 7.73 -<listitem><para><literal role="hook">update</literal>: This is run after an update or merge of the 7.74 - working directory has finished. 7.75 -</para> 7.76 -</listitem></itemizedlist> 7.77 -<para>Each of the hooks whose description begins with the word 7.78 -<quote>Controlling</quote> has the ability to determine whether an activity can 7.79 -proceed. If the hook succeeds, the activity may proceed; if it fails, 7.80 -the activity is either not permitted or undone, depending on the hook. 7.81 -</para> 7.82 - 7.83 -</sect1> 7.84 -<sect1> 7.85 -<title>Hooks and security</title> 7.86 - 7.87 -<sect2> 7.88 -<title>Hooks are run with your privileges</title> 7.89 - 7.90 -<para>When you run a Mercurial command in a repository, and the command 7.91 -causes a hook to run, that hook runs on <emphasis>your</emphasis> system, under 7.92 -<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> privilege level. Since 7.93 -hooks are arbitrary pieces of executable code, you should treat them 7.94 -with an appropriate level of suspicion. Do not install a hook unless 7.95 -you are confident that you know who created it and what it does. 7.96 -</para> 7.97 - 7.98 -<para>In some cases, you may be exposed to hooks that you did not install 7.99 -yourself. If you work with Mercurial on an unfamiliar system, 7.100 -Mercurial will run hooks defined in that system's global <filename role="special"> /.hgrc</filename>\ file. 7.101 -</para> 7.102 - 7.103 -<para>If you are working with a repository owned by another user, Mercurial 7.104 -can run hooks defined in that user's repository, but it will still run 7.105 -them as <quote>you</quote>. For example, if you <command role="hg-cmd">hg pull</command> from that 7.106 -repository, and its <filename role="special">.hg/hgrc</filename> defines a local 7.107 -<literal role="hook">outgoing</literal> hook, that hook will run under your user account, even 7.108 -though you don't own that repository. 7.109 -</para> 7.110 - 7.111 -<note> 7.112 -<para> This only applies if you are pulling from a repository on a local or 7.113 - network filesystem. If you're pulling over http or ssh, any 7.114 - <literal role="hook">outgoing</literal> hook will run under whatever account is executing 7.115 - the server process, on the server. 7.116 -</para> 7.117 -</note> 7.118 - 7.119 -<para>XXX To see what hooks are defined in a repository, use the 7.120 -<command role="hg-cmd">hg config hooks</command> command. If you are working in one 7.121 -repository, but talking to another that you do not own (e.g. using 7.122 -<command role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg incoming</command>), remember that it is the other 7.123 -repository's hooks you should be checking, not your own. 7.124 -</para> 7.125 - 7.126 -</sect2> 7.127 -<sect2> 7.128 -<title>Hooks do not propagate</title> 7.129 - 7.130 -<para>In Mercurial, hooks are not revision controlled, and do not propagate 7.131 -when you clone, or pull from, a repository. The reason for this is 7.132 -simple: a hook is a completely arbitrary piece of executable code. It 7.133 -runs under your user identity, with your privilege level, on your 7.134 -machine. 7.135 -</para> 7.136 - 7.137 -<para>It would be extremely reckless for any distributed revision control 7.138 -system to implement revision-controlled hooks, as this would offer an 7.139 -easily exploitable way to subvert the accounts of users of the 7.140 -revision control system. 7.141 -</para> 7.142 - 7.143 -<para>Since Mercurial does not propagate hooks, if you are collaborating 7.144 -with other people on a common project, you should not assume that they 7.145 -are using the same Mercurial hooks as you are, or that theirs are 7.146 -correctly configured. You should document the hooks you expect people 7.147 -to use. 7.148 -</para> 7.149 - 7.150 -<para>In a corporate intranet, this is somewhat easier to control, as you 7.151 -can for example provide a <quote>standard</quote> installation of Mercurial on an 7.152 -NFS filesystem, and use a site-wide <filename role="special"> /.hgrc</filename>\ file to define hooks that 7.153 -all users will see. However, this too has its limits; see below. 7.154 -</para> 7.155 - 7.156 -</sect2> 7.157 -<sect2> 7.158 -<title>Hooks can be overridden</title> 7.159 - 7.160 -<para>Mercurial allows you to override a hook definition by redefining the 7.161 -hook. You can disable it by setting its value to the empty string, or 7.162 -change its behaviour as you wish. 7.163 -</para> 7.164 - 7.165 -<para>If you deploy a system- or site-wide <filename role="special"> /.hgrc</filename>\ file that defines some 7.166 -hooks, you should thus understand that your users can disable or 7.167 -override those hooks. 7.168 -</para> 7.169 - 7.170 -</sect2> 7.171 -<sect2> 7.172 -<title>Ensuring that critical hooks are run</title> 7.173 - 7.174 -<para>Sometimes you may want to enforce a policy that you do not want others 7.175 -to be able to work around. For example, you may have a requirement 7.176 -that every changeset must pass a rigorous set of tests. Defining this 7.177 -requirement via a hook in a site-wide <filename role="special"> /.hgrc</filename>\ won't work for remote 7.178 -users on laptops, and of course local users can subvert it at will by 7.179 -overriding the hook. 7.180 -</para> 7.181 - 7.182 -<para>Instead, you can set up your policies for use of Mercurial so that 7.183 -people are expected to propagate changes through a well-known 7.184 -<quote>canonical</quote> server that you have locked down and configured 7.185 -appropriately. 7.186 -</para> 7.187 - 7.188 -<para>One way to do this is via a combination of social engineering and 7.189 -technology. Set up a restricted-access account; users can push 7.190 -changes over the network to repositories managed by this account, but 7.191 -they cannot log into the account and run normal shell commands. In 7.192 -this scenario, a user can commit a changeset that contains any old 7.193 -garbage they want. 7.194 -</para> 7.195 - 7.196 -<para>When someone pushes a changeset to the server that everyone pulls 7.197 -from, the server will test the changeset before it accepts it as 7.198 -permanent, and reject it if it fails to pass the test suite. If 7.199 -people only pull changes from this filtering server, it will serve to 7.200 -ensure that all changes that people pull have been automatically 7.201 -vetted. 7.202 -</para> 7.203 - 7.204 -</sect2> 7.205 -</sect1> 7.206 -<sect1> 7.207 -<title>Care with <literal>pretxn</literal> hooks in a shared-access repository</title> 7.208 - 7.209 -<para>If you want to use hooks to do some automated work in a repository 7.210 -that a number of people have shared access to, you need to be careful 7.211 -in how you do this. 7.212 -</para> 7.213 - 7.214 -<para>Mercurial only locks a repository when it is writing to the 7.215 -repository, and only the parts of Mercurial that write to the 7.216 -repository pay attention to locks. Write locks are necessary to 7.217 -prevent multiple simultaneous writers from scribbling on each other's 7.218 -work, corrupting the repository. 7.219 -</para> 7.220 - 7.221 -<para>Because Mercurial is careful with the order in which it reads and 7.222 -writes data, it does not need to acquire a lock when it wants to read 7.223 -data from the repository. The parts of Mercurial that read from the 7.224 -repository never pay attention to locks. This lockless reading scheme 7.225 -greatly increases performance and concurrency. 7.226 -</para> 7.227 - 7.228 -<para>With great performance comes a trade-off, though, one which has the 7.229 -potential to cause you trouble unless you're aware of it. To describe 7.230 -this requires a little detail about how Mercurial adds changesets to a 7.231 -repository and reads those changes. 7.232 -</para> 7.233 - 7.234 -<para>When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight into the 7.235 -destination file. It writes file data first, then manifest data 7.236 -(which contains pointers to the new file data), then changelog data 7.237 -(which contains pointers to the new manifest data). Before the first 7.238 -write to each file, it stores a record of where the end of the file 7.239 -was in its transaction log. If the transaction must be rolled back, 7.240 -Mercurial simply truncates each file back to the size it was before the 7.241 -transaction began. 7.242 -</para> 7.243 - 7.244 -<para>When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog first, 7.245 -then everything else. Since a reader will only access parts of the 7.246 -manifest or file metadata that it can see in the changelog, it can 7.247 -never see partially written data. 7.248 -</para> 7.249 - 7.250 -<para>Some controlling hooks (<literal role="hook">pretxncommit</literal> and 7.251 -<literal role="hook">pretxnchangegroup</literal>) run when a transaction is almost complete. 7.252 -All of the metadata has been written, but Mercurial can still roll the 7.253 -transaction back and cause the newly-written data to disappear. 7.254 -</para> 7.255 - 7.256 -<para>If one of these hooks runs for long, it opens a window of time during 7.257 -which a reader can see the metadata for changesets that are not yet 7.258 -permanent, and should not be thought of as <quote>really there</quote>. The 7.259 -longer the hook runs, the longer that window is open. 7.260 -</para> 7.261 - 7.262 -<sect2> 7.263 -<title>The problem illustrated</title> 7.264 - 7.265 -<para>In principle, a good use for the <literal role="hook">pretxnchangegroup</literal> hook would 7.266 -be to automatically build and test incoming changes before they are 7.267 -accepted into a central repository. This could let you guarantee that 7.268 -nobody can push changes to this repository that <quote>break the build</quote>. 7.269 -But if a client can pull changes while they're being tested, the 7.270 -usefulness of the test is zero; an unsuspecting someone can pull 7.271 -untested changes, potentially breaking their build. 7.272 -</para> 7.273 - 7.274 -<para>The safest technological answer to this challenge is to set up such a 7.275 -<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>. Let it take 7.276 -changes pushed in from the outside, but do not allow anyone to pull 7.277 -changes from it (use the <literal role="hook">preoutgoing</literal> hook to lock it down). 7.278 -Configure a <literal role="hook">changegroup</literal> hook so that if a build or test 7.279 -succeeds, the hook will push the new changes out to another repository 7.280 -that people <emphasis>can</emphasis> pull from. 7.281 -</para> 7.282 - 7.283 -<para>In practice, putting a centralised bottleneck like this in place is 7.284 -not often a good idea, and transaction visibility has nothing to do 7.285 -with the problem. As the size of a project&emdash;and the time it takes to 7.286 -build and test&emdash;grows, you rapidly run into a wall with this <quote>try 7.287 -before you buy</quote> approach, where you have more changesets to test than 7.288 -time in which to deal with them. The inevitable result is frustration 7.289 -on the part of all involved. 7.290 -</para> 7.291 - 7.292 -<para>An approach that scales better is to get people to build and test 7.293 -before they push, then run automated builds and tests centrally 7.294 -<emphasis>after</emphasis> a push, to be sure all is well. The advantage of this 7.295 -approach is that it does not impose a limit on the rate at which the 7.296 -repository can accept changes. 7.297 -</para> 7.298 - 7.299 -</sect2> 7.300 -</sect1> 7.301 -<sect1> 7.302 -<title>A short tutorial on using hooks</title> 7.303 -<para>\label{sec:hook:simple} 7.304 -</para> 7.305 - 7.306 -<para>It is easy to write a Mercurial hook. Let's start with a hook that 7.307 -runs when you finish a <command role="hg-cmd">hg commit</command>, and simply prints the hash of 7.308 -the changeset you just created. The hook is called <literal role="hook">commit</literal>. 7.309 -</para> 7.310 - 7.311 -<informalfigure> 7.312 -<para> <!-- &interaction.hook.simple.init; --> 7.313 - <caption><para>A simple hook that runs when a changeset is committed</para></caption> 7.314 - \label{ex:hook:init} 7.315 -</para> 7.316 -</informalfigure> 7.317 - 7.318 -<para>All hooks follow the pattern in example <xref linkend="ex:hook:init"/>. You add 7.319 -an entry to the <literal role="rc-hooks">hooks</literal> section of your <filename role="special"> /.hgrc</filename>. On the left 7.320 -is the name of the event to trigger on; on the right is the action to 7.321 -take. As you can see, you can run an arbitrary shell command in a 7.322 -hook. Mercurial passes extra information to the hook using 7.323 -environment variables (look for <envar>HG_NODE</envar> in the example). 7.324 -</para> 7.325 - 7.326 -<sect2> 7.327 -<title>Performing multiple actions per event</title> 7.328 - 7.329 -<para>Quite often, you will want to define more than one hook for a 7.330 -particular kind of event, as shown in example <xref linkend="ex:hook:ext"/>. 7.331 -Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the end of 7.332 -a hook's name. You extend a hook's name by giving the name of the 7.333 -hook, followed by a full stop (the <quote><literal>.</literal></quote> character), followed 7.334 -by some more text of your choosing. For example, Mercurial will run 7.335 -both <literal>commit.foo</literal> and <literal>commit.bar</literal> when the 7.336 -<literal>commit</literal> event occurs. 7.337 -</para> 7.338 - 7.339 -<informalfigure> 7.340 -<para> <!-- &interaction.hook.simple.ext; --> 7.341 - <caption><para>Defining a second <literal role="hook">commit</para></caption> hook</literal> 7.342 - \label{ex:hook:ext} 7.343 -</para> 7.344 -</informalfigure> 7.345 - 7.346 -<para>To give a well-defined order of execution when there are multiple 7.347 -hooks defined for an event, Mercurial sorts hooks by extension, and 7.348 -executes the hook commands in this sorted order. In the above 7.349 -example, it will execute <literal>commit.bar</literal> before 7.350 -<literal>commit.foo</literal>, and <literal>commit</literal> before both. 7.351 -</para> 7.352 - 7.353 -<para>It is a good idea to use a somewhat descriptive extension when you 7.354 -define a new hook. This will help you to remember what the hook was 7.355 -for. If the hook fails, you'll get an error message that contains the 7.356 -hook name and extension, so using a descriptive extension could give 7.357 -you an immediate hint as to why the hook failed (see 7.358 -section <xref linkend="sec:hook:perm"/> for an example). 7.359 -</para> 7.360 - 7.361 -</sect2> 7.362 -<sect2> 7.363 -<title>Controlling whether an activity can proceed</title> 7.364 -<para>\label{sec:hook:perm} 7.365 -</para> 7.366 - 7.367 -<para>In our earlier examples, we used the <literal role="hook">commit</literal> hook, which is 7.368 -run after a commit has completed. This is one of several Mercurial 7.369 -hooks that run after an activity finishes. Such hooks have no way of 7.370 -influencing the activity itself. 7.371 -</para> 7.372 - 7.373 -<para>Mercurial defines a number of events that occur before an activity 7.374 -starts; or after it starts, but before it finishes. Hooks that 7.375 -trigger on these events have the added ability to choose whether the 7.376 -activity can continue, or will abort. 7.377 -</para> 7.378 - 7.379 -<para>The <literal role="hook">pretxncommit</literal> hook runs after a commit has all but 7.380 -completed. In other words, the metadata representing the changeset 7.381 -has been written out to disk, but the transaction has not yet been 7.382 -allowed to complete. The <literal role="hook">pretxncommit</literal> hook has the ability to 7.383 -decide whether the transaction can complete, or must be rolled back. 7.384 -</para> 7.385 - 7.386 -<para>If the <literal role="hook">pretxncommit</literal> hook exits with a status code of zero, the 7.387 -transaction is allowed to complete; the commit finishes; and the 7.388 -<literal role="hook">commit</literal> hook is run. If the <literal role="hook">pretxncommit</literal> hook exits with 7.389 -a non-zero status code, the transaction is rolled back; the metadata 7.390 -representing the changeset is erased; and the <literal role="hook">commit</literal> hook is 7.391 -not run. 7.392 -</para> 7.393 - 7.394 -<informalfigure> 7.395 -<para> <!-- &interaction.hook.simple.pretxncommit; --> 7.396 - <caption><para>Using the <literal role="hook">pretxncommit</para></caption> hook to control commits</literal> 7.397 - \label{ex:hook:pretxncommit} 7.398 -</para> 7.399 -</informalfigure> 7.400 - 7.401 -<para>The hook in example <xref linkend="ex:hook:pretxncommit"/> checks that a commit 7.402 -comment contains a bug ID. If it does, the commit can complete. If 7.403 -not, the commit is rolled back. 7.404 -</para> 7.405 - 7.406 -</sect2> 7.407 -</sect1> 7.408 -<sect1> 7.409 -<title>Writing your own hooks</title> 7.410 - 7.411 -<para>When you are writing a hook, you might find it useful to run Mercurial 7.412 -either with the <option role="hg-opt-global">-v</option> option, or the <envar role="rc-item-ui">verbose</envar> config 7.413 -item set to <quote>true</quote>. When you do so, Mercurial will print a message 7.414 -before it calls each hook. 7.415 -</para> 7.416 - 7.417 -<sect2> 7.418 -<title>Choosing how your hook should run</title> 7.419 -<para>\label{sec:hook:lang} 7.420 -</para> 7.421 - 7.422 -<para>You can write a hook either as a normal program&emdash;typically a shell 7.423 -script&emdash;or as a Python function that is executed within the Mercurial 7.424 -process. 7.425 -</para> 7.426 - 7.427 -<para>Writing a hook as an external program has the advantage that it 7.428 -requires no knowledge of Mercurial's internals. You can call normal 7.429 -Mercurial commands to get any added information you need. The 7.430 -trade-off is that external hooks are slower than in-process hooks. 7.431 -</para> 7.432 - 7.433 -<para>An in-process Python hook has complete access to the Mercurial API, 7.434 -and does not <quote>shell out</quote> to another process, so it is inherently 7.435 -faster than an external hook. It is also easier to obtain much of the 7.436 -information that a hook requires by using the Mercurial API than by 7.437 -running Mercurial commands. 7.438 -</para> 7.439 - 7.440 -<para>If you are comfortable with Python, or require high performance, 7.441 -writing your hooks in Python may be a good choice. However, when you 7.442 -have a straightforward hook to write and you don't need to care about 7.443 -performance (probably the majority of hooks), a shell script is 7.444 -perfectly fine. 7.445 -</para> 7.446 - 7.447 -</sect2> 7.448 -<sect2> 7.449 -<title>Hook parameters</title> 7.450 -<para>\label{sec:hook:param} 7.451 -</para> 7.452 - 7.453 -<para>Mercurial calls each hook with a set of well-defined parameters. In 7.454 -Python, a parameter is passed as a keyword argument to your hook 7.455 -function. For an external program, a parameter is passed as an 7.456 -environment variable. 7.457 -</para> 7.458 - 7.459 -<para>Whether your hook is written in Python or as a shell script, the 7.460 -hook-specific parameter names and values will be the same. A boolean 7.461 -parameter will be represented as a boolean value in Python, but as the 7.462 -number 1 (for <quote>true</quote>) or 0 (for <quote>false</quote>) as an environment 7.463 -variable for an external hook. If a hook parameter is named 7.464 -<literal>foo</literal>, the keyword argument for a Python hook will also be 7.465 -named <literal>foo</literal>, while the environment variable for an external 7.466 -hook will be named <literal>HG_FOO</literal>. 7.467 -</para> 7.468 - 7.469 -</sect2> 7.470 -<sect2> 7.471 -<title>Hook return values and activity control</title> 7.472 - 7.473 -<para>A hook that executes successfully must exit with a status of zero if 7.474 -external, or return boolean <quote>false</quote> if in-process. Failure is 7.475 -indicated with a non-zero exit status from an external hook, or an 7.476 -in-process hook returning boolean <quote>true</quote>. If an in-process hook 7.477 -raises an exception, the hook is considered to have failed. 7.478 -</para> 7.479 - 7.480 -<para>For a hook that controls whether an activity can proceed, zero/false 7.481 -means <quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>. 7.482 -</para> 7.483 - 7.484 -</sect2> 7.485 -<sect2> 7.486 -<title>Writing an external hook</title> 7.487 - 7.488 -<para>When you define an external hook in your <filename role="special"> /.hgrc</filename>\ and the hook is run, 7.489 -its value is passed to your shell, which interprets it. This means 7.490 -that you can use normal shell constructs in the body of the hook. 7.491 -</para> 7.492 - 7.493 -<para>An executable hook is always run with its current directory set to a 7.494 -repository's root directory. 7.495 -</para> 7.496 - 7.497 -<para>Each hook parameter is passed in as an environment variable; the name 7.498 -is upper-cased, and prefixed with the string <quote><literal>HG_</literal></quote>. 7.499 -</para> 7.500 - 7.501 -<para>With the exception of hook parameters, Mercurial does not set or 7.502 -modify any environment variables when running a hook. This is useful 7.503 -to remember if you are writing a site-wide hook that may be run by a 7.504 -number of different users with differing environment variables set. 7.505 -In multi-user situations, you should not rely on environment variables 7.506 -being set to the values you have in your environment when testing the 7.507 -hook. 7.508 -</para> 7.509 - 7.510 -</sect2> 7.511 -<sect2> 7.512 -<title>Telling Mercurial to use an in-process hook</title> 7.513 - 7.514 -<para>The <filename role="special"> /.hgrc</filename>\ syntax for defining an in-process hook is slightly 7.515 -different than for an executable hook. The value of the hook must 7.516 -start with the text <quote><literal>python:</literal></quote>, and continue with the 7.517 -fully-qualified name of a callable object to use as the hook's value. 7.518 -</para> 7.519 - 7.520 -<para>The module in which a hook lives is automatically imported when a hook 7.521 -is run. So long as you have the module name and <envar>PYTHONPATH</envar> 7.522 -right, it should <quote>just work</quote>. 7.523 -</para> 7.524 - 7.525 -<para>The following <filename role="special"> /.hgrc</filename>\ example snippet illustrates the syntax and 7.526 -meaning of the notions we just described. 7.527 -</para> 7.528 -<programlisting> 7.529 -<para> [hooks] 7.530 - commit.example = python:mymodule.submodule.myhook 7.531 -</para> 7.532 -</programlisting> 7.533 -<para>When Mercurial runs the <literal>commit.example</literal> hook, it imports 7.534 -<literal>mymodule.submodule</literal>, looks for the callable object named 7.535 -<literal>myhook</literal>, and calls it. 7.536 -</para> 7.537 - 7.538 -</sect2> 7.539 -<sect2> 7.540 -<title>Writing an in-process hook</title> 7.541 - 7.542 -<para>The simplest in-process hook does nothing, but illustrates the basic 7.543 -shape of the hook API: 7.544 -</para> 7.545 -<programlisting> 7.546 -<para> def myhook(ui, repo, **kwargs): 7.547 - pass 7.548 -</para> 7.549 -</programlisting> 7.550 -<para>The first argument to a Python hook is always a 7.551 -<literal role="py-mod-mercurial.ui">ui</literal> object. The second is a repository object; 7.552 -at the moment, it is always an instance of 7.553 -<literal role="py-mod-mercurial.localrepo">localrepository</literal>. Following these two 7.554 -arguments are other keyword arguments. Which ones are passed in 7.555 -depends on the hook being called, but a hook can ignore arguments it 7.556 -doesn't care about by dropping them into a keyword argument dict, as 7.557 -with <literal>**kwargs</literal> above. 7.558 -</para> 7.559 - 7.560 -</sect2> 7.561 -</sect1> 7.562 -<sect1> 7.563 -<title>Some hook examples</title> 7.564 - 7.565 -<sect2> 7.566 -<title>Writing meaningful commit messages</title> 7.567 - 7.568 -<para>It's hard to imagine a useful commit message being very short. The 7.569 -simple <literal role="hook">pretxncommit</literal> hook of figure <xref linkend="ex:hook:msglen.go"/> 7.570 -will prevent you from committing a changeset with a message that is 7.571 -less than ten bytes long. 7.572 -</para> 7.573 - 7.574 -<informalfigure> 7.575 -<para> <!-- &interaction.hook.msglen.go; --> 7.576 - <caption><para>A hook that forbids overly short commit messages</para></caption> 7.577 - \label{ex:hook:msglen.go} 7.578 -</para> 7.579 -</informalfigure> 7.580 - 7.581 -</sect2> 7.582 -<sect2> 7.583 -<title>Checking for trailing whitespace</title> 7.584 - 7.585 -<para>An interesting use of a commit-related hook is to help you to write 7.586 -cleaner code. A simple example of <quote>cleaner code</quote> is the dictum that 7.587 -a change should not add any new lines of text that contain <quote>trailing 7.588 -whitespace</quote>. Trailing whitespace is a series of space and tab 7.589 -characters at the end of a line of text. In most cases, trailing 7.590 -whitespace is unnecessary, invisible noise, but it is occasionally 7.591 -problematic, and people often prefer to get rid of it. 7.592 -</para> 7.593 - 7.594 -<para>You can use either the <literal role="hook">precommit</literal> or <literal role="hook">pretxncommit</literal> hook to 7.595 -tell whether you have a trailing whitespace problem. If you use the 7.596 -<literal role="hook">precommit</literal> hook, the hook will not know which files you are 7.597 -committing, so it will have to check every modified file in the 7.598 -repository for trailing white space. If you want to commit a change 7.599 -to just the file <filename>foo</filename>, but the file <filename>bar</filename> contains 7.600 -trailing whitespace, doing a check in the <literal role="hook">precommit</literal> hook will 7.601 -prevent you from committing <filename>foo</filename> due to the problem with 7.602 -<filename>bar</filename>. This doesn't seem right. 7.603 -</para> 7.604 - 7.605 -<para>Should you choose the <literal role="hook">pretxncommit</literal> hook, the check won't occur 7.606 -until just before the transaction for the commit completes. This will 7.607 -allow you to check for problems only the exact files that are being 7.608 -committed. However, if you entered the commit message interactively 7.609 -and the hook fails, the transaction will roll back; you'll have to 7.610 -re-enter the commit message after you fix the trailing whitespace and 7.611 -run <command role="hg-cmd">hg commit</command> again. 7.612 -</para> 7.613 - 7.614 -<informalfigure> 7.615 -<para> <!-- &interaction.hook.ws.simple; --> 7.616 - <caption><para>A simple hook that checks for trailing whitespace</para></caption> 7.617 - \label{ex:hook:ws.simple} 7.618 -</para> 7.619 -</informalfigure> 7.620 - 7.621 -<para>Figure <xref linkend="ex:hook:ws.simple"/> introduces a simple <literal role="hook">pretxncommit</literal> 7.622 -hook that checks for trailing whitespace. This hook is short, but not 7.623 -very helpful. It exits with an error status if a change adds a line 7.624 -with trailing whitespace to any file, but does not print any 7.625 -information that might help us to identify the offending file or 7.626 -line. It also has the nice property of not paying attention to 7.627 -unmodified lines; only lines that introduce new trailing whitespace 7.628 -cause problems. 7.629 -</para> 7.630 - 7.631 -<informalfigure> 7.632 -<para> <!-- &interaction.hook.ws.better; --> 7.633 - <caption><para>A better trailing whitespace hook</para></caption> 7.634 - \label{ex:hook:ws.better} 7.635 -</para> 7.636 -</informalfigure> 7.637 - 7.638 -<para>The example of figure <xref linkend="ex:hook:ws.better"/> is much more complex, 7.639 -but also more useful. It parses a unified diff to see if any lines 7.640 -add trailing whitespace, and prints the name of the file and the line 7.641 -number of each such occurrence. Even better, if the change adds 7.642 -trailing whitespace, this hook saves the commit comment and prints the 7.643 -name of the save file before exiting and telling Mercurial to roll the 7.644 -transaction back, so you can use 7.645 -<command role="hg-cmd">hg commit <option role="hg-opt-commit">-l</option> <emphasis>filename</emphasis></command> to reuse the 7.646 -saved commit message once you've corrected the problem. 7.647 -</para> 7.648 - 7.649 -<para>As a final aside, note in figure <xref linkend="ex:hook:ws.better"/> the use of 7.650 -<command>perl</command>'s in-place editing feature to get rid of trailing 7.651 -whitespace from a file. This is concise and useful enough that I will 7.652 -reproduce it here. 7.653 -</para> 7.654 -<programlisting> 7.655 -<para> perl -pi -e 's,\textbackslash{}s+$,,' filename 7.656 -</para> 7.657 -</programlisting> 7.658 - 7.659 -</sect2> 7.660 -</sect1> 7.661 -<sect1> 7.662 -<title>Bundled hooks</title> 7.663 - 7.664 -<para>Mercurial ships with several bundled hooks. You can find them in the 7.665 -<filename class="directory">hgext</filename> directory of a Mercurial source tree. If you are 7.666 -using a Mercurial binary package, the hooks will be located in the 7.667 -<filename class="directory">hgext</filename> directory of wherever your package installer put 7.668 -Mercurial. 7.669 -</para> 7.670 - 7.671 -<sect2> 7.672 -<title><literal role="hg-ext">acl</literal>&emdash;access control for parts of a repository</title> 7.673 - 7.674 -<para>The <literal role="hg-ext">acl</literal> extension lets you control which remote users are 7.675 -allowed to push changesets to a networked server. You can protect any 7.676 -portion of a repository (including the entire repo), so that a 7.677 -specific remote user can push changes that do not affect the protected 7.678 -portion. 7.679 -</para> 7.680 - 7.681 -<para>This extension implements access control based on the identity of the 7.682 -user performing a push, <emphasis>not</emphasis> on who committed the changesets 7.683 -they're pushing. It makes sense to use this hook only if you have a 7.684 -locked-down server environment that authenticates remote users, and 7.685 -you want to be sure that only specific users are allowed to push 7.686 -changes to that server. 7.687 -</para> 7.688 - 7.689 -<sect3> 7.690 -<title>Configuring the <literal role="hook">acl</literal> hook</title> 7.691 - 7.692 -<para>In order to manage incoming changesets, the <literal role="hg-ext">acl</literal> hook must be 7.693 -used as a <literal role="hook">pretxnchangegroup</literal> hook. This lets it see which files 7.694 -are modified by each incoming changeset, and roll back a group of 7.695 -changesets if they modify <quote>forbidden</quote> files. Example: 7.696 -</para> 7.697 -<programlisting> 7.698 -<para> [hooks] 7.699 - pretxnchangegroup.acl = python:hgext.acl.hook 7.700 -</para> 7.701 -</programlisting> 7.702 - 7.703 -<para>The <literal role="hg-ext">acl</literal> extension is configured using three sections. 7.704 -</para> 7.705 - 7.706 -<para>The <literal role="rc-acl">acl</literal> section has only one entry, <envar role="rc-item-acl">sources</envar>, 7.707 -which lists the sources of incoming changesets that the hook should 7.708 -pay attention to. You don't normally need to configure this section. 7.709 -</para> 7.710 -<itemizedlist> 7.711 -<listitem><para><envar role="rc-item-acl">serve</envar>: Control incoming changesets that are arriving 7.712 - from a remote repository over http or ssh. This is the default 7.713 - value of <envar role="rc-item-acl">sources</envar>, and usually the only setting you'll 7.714 - need for this configuration item. 7.715 -</para> 7.716 -</listitem> 7.717 -<listitem><para><envar role="rc-item-acl">pull</envar>: Control incoming changesets that are 7.718 - arriving via a pull from a local repository. 7.719 -</para> 7.720 -</listitem> 7.721 -<listitem><para><envar role="rc-item-acl">push</envar>: Control incoming changesets that are 7.722 - arriving via a push from a local repository. 7.723 -</para> 7.724 -</listitem> 7.725 -<listitem><para><envar role="rc-item-acl">bundle</envar>: Control incoming changesets that are 7.726 - arriving from another repository via a bundle. 7.727 -</para> 7.728 -</listitem></itemizedlist> 7.729 - 7.730 -<para>The <literal role="rc-acl.allow">acl.allow</literal> section controls the users that are allowed to 7.731 -add changesets to the repository. If this section is not present, all 7.732 -users that are not explicitly denied are allowed. If this section is 7.733 -present, all users that are not explicitly allowed are denied (so an 7.734 -empty section means that all users are denied). 7.735 -</para> 7.736 - 7.737 -<para>The <literal role="rc-acl.deny">acl.deny</literal> section determines which users are denied 7.738 -from adding changesets to the repository. If this section is not 7.739 -present or is empty, no users are denied. 7.740 -</para> 7.741 - 7.742 -<para>The syntaxes for the <literal role="rc-acl.allow">acl.allow</literal> and <literal role="rc-acl.deny">acl.deny</literal> 7.743 -sections are identical. On the left of each entry is a glob pattern 7.744 -that matches files or directories, relative to the root of the 7.745 -repository; on the right, a user name. 7.746 -</para> 7.747 - 7.748 -<para>In the following example, the user <literal>docwriter</literal> can only push 7.749 -changes to the <filename class="directory">docs</filename> subtree of the repository, while 7.750 -<literal>intern</literal> can push changes to any file or directory except 7.751 -<filename class="directory">source/sensitive</filename>. 7.752 -</para> 7.753 -<programlisting> 7.754 -<para> [acl.allow] 7.755 - docs/** = docwriter 7.756 -</para> 7.757 - 7.758 -<para> [acl.deny] 7.759 - source/sensitive/** = intern 7.760 -</para> 7.761 -</programlisting> 7.762 - 7.763 -</sect3> 7.764 -<sect3> 7.765 -<title>Testing and troubleshooting</title> 7.766 - 7.767 -<para>If you want to test the <literal role="hg-ext">acl</literal> hook, run it with Mercurial's 7.768 -debugging output enabled. Since you'll probably be running it on a 7.769 -server where it's not convenient (or sometimes possible) to pass in 7.770 -the <option role="hg-opt-global">--debug</option> option, don't forget that you can enable 7.771 -debugging output in your <filename role="special"> /.hgrc</filename>: 7.772 -</para> 7.773 -<programlisting> 7.774 -<para> [ui] 7.775 - debug = true 7.776 -</para> 7.777 -</programlisting> 7.778 -<para>With this enabled, the <literal role="hg-ext">acl</literal> hook will print enough information 7.779 -to let you figure out why it is allowing or forbidding pushes from 7.780 -specific users. 7.781 -</para> 7.782 - 7.783 -</sect3> 7.784 -</sect2> 7.785 -<sect2> 7.786 -<title><literal role="hg-ext">bugzilla</literal>&emdash;integration with Bugzilla</title> 7.787 - 7.788 -<para>The <literal role="hg-ext">bugzilla</literal> extension adds a comment to a Bugzilla bug 7.789 -whenever it finds a reference to that bug ID in a commit comment. You 7.790 -can install this hook on a shared server, so that any time a remote 7.791 -user pushes changes to this server, the hook gets run. 7.792 -</para> 7.793 - 7.794 -<para>It adds a comment to the bug that looks like this (you can configure 7.795 -the contents of the comment&emdash;see below): 7.796 -</para> 7.797 -<programlisting> 7.798 -<para> Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in 7.799 - the frobnitz repository, refers to this bug. 7.800 -</para> 7.801 - 7.802 -<para> For complete details, see 7.803 - http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 7.804 -</para> 7.805 - 7.806 -<para> Changeset description: 7.807 - Fix bug 10483 by guarding against some NULL pointers 7.808 -</para> 7.809 -</programlisting> 7.810 -<para>The value of this hook is that it automates the process of updating a 7.811 -bug any time a changeset refers to it. If you configure the hook 7.812 -properly, it makes it easy for people to browse straight from a 7.813 -Bugzilla bug to a changeset that refers to that bug. 7.814 -</para> 7.815 - 7.816 -<para>You can use the code in this hook as a starting point for some more 7.817 -exotic Bugzilla integration recipes. Here are a few possibilities: 7.818 -</para> 7.819 -<itemizedlist> 7.820 -<listitem><para>Require that every changeset pushed to the server have a valid 7.821 - bug ID in its commit comment. In this case, you'd want to configure 7.822 - the hook as a <literal role="hook">pretxncommit</literal> hook. This would allow the hook 7.823 - to reject changes that didn't contain bug IDs. 7.824 -</para> 7.825 -</listitem> 7.826 -<listitem><para>Allow incoming changesets to automatically modify the 7.827 - <emphasis>state</emphasis> of a bug, as well as simply adding a comment. For 7.828 - example, the hook could recognise the string <quote>fixed bug 31337</quote> as 7.829 - indicating that it should update the state of bug 31337 to 7.830 - <quote>requires testing</quote>. 7.831 -</para> 7.832 -</listitem></itemizedlist> 7.833 - 7.834 -<sect3> 7.835 -<title>Configuring the <literal role="hook">bugzilla</literal> hook</title> 7.836 -<para>\label{sec:hook:bugzilla:config} 7.837 -</para> 7.838 - 7.839 -<para>You should configure this hook in your server's <filename role="special"> /.hgrc</filename>\ as an 7.840 -<literal role="hook">incoming</literal> hook, for example as follows: 7.841 -</para> 7.842 -<programlisting> 7.843 -<para> [hooks] 7.844 - incoming.bugzilla = python:hgext.bugzilla.hook 7.845 -</para> 7.846 -</programlisting> 7.847 - 7.848 -<para>Because of the specialised nature of this hook, and because Bugzilla 7.849 -was not written with this kind of integration in mind, configuring 7.850 -this hook is a somewhat involved process. 7.851 -</para> 7.852 - 7.853 -<para>Before you begin, you must install the MySQL bindings for Python on 7.854 -the host(s) where you'll be running the hook. If this is not 7.855 -available as a binary package for your system, you can download it 7.856 -from <citation>web:mysql-python</citation>. 7.857 -</para> 7.858 - 7.859 -<para>Configuration information for this hook lives in the 7.860 -<literal role="rc-bugzilla">bugzilla</literal> section of your <filename role="special"> /.hgrc</filename>. 7.861 -</para> 7.862 -<itemizedlist> 7.863 -<listitem><para><envar role="rc-item-bugzilla">version</envar>: The version of Bugzilla installed on 7.864 - the server. The database schema that Bugzilla uses changes 7.865 - occasionally, so this hook has to know exactly which schema to use. 7.866 - At the moment, the only version supported is <literal>2.16</literal>. 7.867 -</para> 7.868 -</listitem> 7.869 -<listitem><para><envar role="rc-item-bugzilla">host</envar>: The hostname of the MySQL server that 7.870 - stores your Bugzilla data. The database must be configured to allow 7.871 - connections from whatever host you are running the <literal role="hook">bugzilla</literal> 7.872 - hook on. 7.873 -</para> 7.874 -</listitem> 7.875 -<listitem><para><envar role="rc-item-bugzilla">user</envar>: The username with which to connect to 7.876 - the MySQL server. The database must be configured to allow this 7.877 - user to connect from whatever host you are running the 7.878 - <literal role="hook">bugzilla</literal> hook on. This user must be able to access and 7.879 - modify Bugzilla tables. The default value of this item is 7.880 - <literal>bugs</literal>, which is the standard name of the Bugzilla user in a 7.881 - MySQL database. 7.882 -</para> 7.883 -</listitem> 7.884 -<listitem><para><envar role="rc-item-bugzilla">password</envar>: The MySQL password for the user you 7.885 - configured above. This is stored as plain text, so you should make 7.886 - sure that unauthorised users cannot read the <filename role="special"> /.hgrc</filename>\ file where you 7.887 - store this information. 7.888 -</para> 7.889 -</listitem> 7.890 -<listitem><para><envar role="rc-item-bugzilla">db</envar>: The name of the Bugzilla database on the 7.891 - MySQL server. The default value of this item is <literal>bugs</literal>, 7.892 - which is the standard name of the MySQL database where Bugzilla 7.893 - stores its data. 7.894 -</para> 7.895 -</listitem> 7.896 -<listitem><para><envar role="rc-item-bugzilla">notify</envar>: If you want Bugzilla to send out a 7.897 - notification email to subscribers after this hook has added a 7.898 - comment to a bug, you will need this hook to run a command whenever 7.899 - it updates the database. The command to run depends on where you 7.900 - have installed Bugzilla, but it will typically look something like 7.901 - this, if you have Bugzilla installed in 7.902 - <filename class="directory">/var/www/html/bugzilla</filename>: 7.903 -</para> 7.904 -</listitem><programlisting> 7.905 -<listitem><para> cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com 7.906 -</para> 7.907 -</listitem></programlisting> 7.908 -<listitem><para> The Bugzilla <literal>processmail</literal> program expects to be given a 7.909 - bug ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID) and an 7.910 - email address. It also expects to be able to write to some files in 7.911 - the directory that it runs in. If Bugzilla and this hook are not 7.912 - installed on the same machine, you will need to find a way to run 7.913 - <literal>processmail</literal> on the server where Bugzilla is installed. 7.914 -</para> 7.915 -</listitem></itemizedlist> 7.916 - 7.917 -</sect3> 7.918 -<sect3> 7.919 -<title>Mapping committer names to Bugzilla user names</title> 7.920 - 7.921 -<para>By default, the <literal role="hg-ext">bugzilla</literal> hook tries to use the email address 7.922 -of a changeset's committer as the Bugzilla user name with which to 7.923 -update a bug. If this does not suit your needs, you can map committer 7.924 -email addresses to Bugzilla user names using a <literal role="rc-usermap">usermap</literal> 7.925 -section. 7.926 -</para> 7.927 - 7.928 -<para>Each item in the <literal role="rc-usermap">usermap</literal> section contains an email address 7.929 -on the left, and a Bugzilla user name on the right. 7.930 -</para> 7.931 -<programlisting> 7.932 -<para> [usermap] 7.933 - jane.user@example.com = jane 7.934 -</para> 7.935 -</programlisting> 7.936 -<para>You can either keep the <literal role="rc-usermap">usermap</literal> data in a normal <filename role="special"> /.hgrc</filename>, or 7.937 -tell the <literal role="hg-ext">bugzilla</literal> hook to read the information from an 7.938 -external <filename>usermap</filename> file. In the latter case, you can store 7.939 -<filename>usermap</filename> data by itself in (for example) a user-modifiable 7.940 -repository. This makes it possible to let your users maintain their 7.941 -own <envar role="rc-item-bugzilla">usermap</envar> entries. The main <filename role="special"> /.hgrc</filename>\ file might 7.942 -look like this: 7.943 -</para> 7.944 -<programlisting> 7.945 -<para> # regular hgrc file refers to external usermap file 7.946 - [bugzilla] 7.947 - usermap = /home/hg/repos/userdata/bugzilla-usermap.conf 7.948 -</para> 7.949 -</programlisting> 7.950 -<para>While the <filename>usermap</filename> file that it refers to might look like 7.951 -this: 7.952 -</para> 7.953 -<programlisting> 7.954 -<para> # bugzilla-usermap.conf - inside a hg repository 7.955 - [usermap] 7.956 - stephanie@example.com = steph 7.957 -</para> 7.958 -</programlisting> 7.959 - 7.960 -</sect3> 7.961 -<sect3> 7.962 -<title>Configuring the text that gets added to a bug</title> 7.963 - 7.964 -<para>You can configure the text that this hook adds as a comment; you 7.965 -specify it in the form of a Mercurial template. Several <filename role="special"> /.hgrc</filename>\ 7.966 -entries (still in the <literal role="rc-bugzilla">bugzilla</literal> section) control this 7.967 -behaviour. 7.968 -</para> 7.969 -<itemizedlist> 7.970 -<listitem><para><literal>strip</literal>: The number of leading path elements to strip 7.971 - from a repository's path name to construct a partial path for a URL. 7.972 - For example, if the repositories on your server live under 7.973 - <filename class="directory">/home/hg/repos</filename>, and you have a repository whose path is 7.974 - <filename class="directory">/home/hg/repos/app/tests</filename>, then setting <literal>strip</literal> to 7.975 - <literal>4</literal> will give a partial path of <filename class="directory">app/tests</filename>. The 7.976 - hook will make this partial path available when expanding a 7.977 - template, as <literal>webroot</literal>. 7.978 -</para> 7.979 -</listitem> 7.980 -<listitem><para><literal>template</literal>: The text of the template to use. In addition 7.981 - to the usual changeset-related variables, this template can use 7.982 - <literal>hgweb</literal> (the value of the <literal>hgweb</literal> configuration item 7.983 - above) and <literal>webroot</literal> (the path constructed using 7.984 - <literal>strip</literal> above). 7.985 -</para> 7.986 -</listitem></itemizedlist> 7.987 - 7.988 -<para>In addition, you can add a <envar role="rc-item-web">baseurl</envar> item to the 7.989 -<literal role="rc-web">web</literal> section of your <filename role="special"> /.hgrc</filename>. The <literal role="hg-ext">bugzilla</literal> hook will 7.990 -make this available when expanding a template, as the base string to 7.991 -use when constructing a URL that will let users browse from a Bugzilla 7.992 -comment to view a changeset. Example: 7.993 -</para> 7.994 -<programlisting> 7.995 -<para> [web] 7.996 - baseurl = http://hg.domain.com/ 7.997 -</para> 7.998 -</programlisting> 7.999 - 7.1000 -<para>Here is an example set of <literal role="hg-ext">bugzilla</literal> hook config information. 7.1001 -</para> 7.1002 -<programlisting> 7.1003 -<para> [bugzilla] 7.1004 - host = bugzilla.example.com 7.1005 - password = mypassword 7.1006 - version = 2.16 7.1007 - # server-side repos live in /home/hg/repos, so strip 4 leading 7.1008 - # separators 7.1009 - strip = 4 7.1010 - hgweb = http://hg.example.com/ 7.1011 - usermap = /home/hg/repos/notify/bugzilla.conf 7.1012 - template = Changeset {node|short}, made by {author} in the {webroot} 7.1013 - repo, refers to this bug.\\nFor complete details, see 7.1014 - {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset 7.1015 - description:\\n\\t{desc|tabindent} 7.1016 -</para> 7.1017 -</programlisting> 7.1018 - 7.1019 -</sect3> 7.1020 -<sect3> 7.1021 -<title>Testing and troubleshooting</title> 7.1022 - 7.1023 -<para>The most common problems with configuring the <literal role="hg-ext">bugzilla</literal> hook 7.1024 -relate to running Bugzilla's <filename>processmail</filename> script and mapping 7.1025 -committer names to user names. 7.1026 -</para> 7.1027 - 7.1028 -<para>Recall from section <xref linkend="sec:hook:bugzilla:config"/> above that the user 7.1029 -that runs the Mercurial process on the server is also the one that 7.1030 -will run the <filename>processmail</filename> script. The 7.1031 -<filename>processmail</filename> script sometimes causes Bugzilla to write to 7.1032 -files in its configuration directory, and Bugzilla's configuration 7.1033 -files are usually owned by the user that your web server runs under. 7.1034 -</para> 7.1035 - 7.1036 -<para>You can cause <filename>processmail</filename> to be run with the suitable 7.1037 -user's identity using the <command>sudo</command> command. Here is an example 7.1038 -entry for a <filename>sudoers</filename> file. 7.1039 -</para> 7.1040 -<programlisting> 7.1041 -<para> hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s 7.1042 -</para> 7.1043 -</programlisting> 7.1044 -<para>This allows the <literal>hg_user</literal> user to run a 7.1045 -<filename>processmail-wrapper</filename> program under the identity of 7.1046 -<literal>httpd_user</literal>. 7.1047 -</para> 7.1048 - 7.1049 -<para>This indirection through a wrapper script is necessary, because 7.1050 -<filename>processmail</filename> expects to be run with its current directory 7.1051 -set to wherever you installed Bugzilla; you can't specify that kind of 7.1052 -constraint in a <filename>sudoers</filename> file. The contents of the wrapper 7.1053 -script are simple: 7.1054 -</para> 7.1055 -<programlisting> 7.1056 -<para> #!/bin/sh 7.1057 - cd `dirname $0` && ./processmail "$1" nobody@example.com 7.1058 -</para> 7.1059 -</programlisting> 7.1060 -<para>It doesn't seem to matter what email address you pass to 7.1061 -<filename>processmail</filename>. 7.1062 -</para> 7.1063 - 7.1064 -<para>If your <literal role="rc-usermap">usermap</literal> is not set up correctly, users will see an 7.1065 -error message from the <literal role="hg-ext">bugzilla</literal> hook when they push changes 7.1066 -to the server. The error message will look like this: 7.1067 -</para> 7.1068 -<programlisting> 7.1069 -<para> cannot find bugzilla user id for john.q.public@example.com 7.1070 -</para> 7.1071 -</programlisting> 7.1072 -<para>What this means is that the committer's address, 7.1073 -<literal>john.q.public@example.com</literal>, is not a valid Bugzilla user name, 7.1074 -nor does it have an entry in your <literal role="rc-usermap">usermap</literal> that maps it to 7.1075 -a valid Bugzilla user name. 7.1076 -</para> 7.1077 - 7.1078 -</sect3> 7.1079 -</sect2> 7.1080 -<sect2> 7.1081 -<title><literal role="hg-ext">notify</literal>&emdash;send email notifications</title> 7.1082 - 7.1083 -<para>Although Mercurial's built-in web server provides RSS feeds of changes 7.1084 -in every repository, many people prefer to receive change 7.1085 -notifications via email. The <literal role="hg-ext">notify</literal> hook lets you send out 7.1086 -notifications to a set of email addresses whenever changesets arrive 7.1087 -that those subscribers are interested in. 7.1088 -</para> 7.1089 - 7.1090 -<para>As with the <literal role="hg-ext">bugzilla</literal> hook, the <literal role="hg-ext">notify</literal> hook is 7.1091 -template-driven, so you can customise the contents of the notification 7.1092 -messages that it sends. 7.1093 -</para> 7.1094 - 7.1095 -<para>By default, the <literal role="hg-ext">notify</literal> hook includes a diff of every changeset 7.1096 -that it sends out; you can limit the size of the diff, or turn this 7.1097 -feature off entirely. It is useful for letting subscribers review 7.1098 -changes immediately, rather than clicking to follow a URL. 7.1099 -</para> 7.1100 - 7.1101 -<sect3> 7.1102 -<title>Configuring the <literal role="hg-ext">notify</literal> hook</title> 7.1103 - 7.1104 -<para>You can set up the <literal role="hg-ext">notify</literal> hook to send one email message per 7.1105 -incoming changeset, or one per incoming group of changesets (all those 7.1106 -that arrived in a single pull or push). 7.1107 -</para> 7.1108 -<programlisting> 7.1109 -<para> [hooks] 7.1110 - # send one email per group of changes 7.1111 - changegroup.notify = python:hgext.notify.hook 7.1112 - # send one email per change 7.1113 - incoming.notify = python:hgext.notify.hook 7.1114 -</para> 7.1115 -</programlisting> 7.1116 - 7.1117 -<para>Configuration information for this hook lives in the 7.1118 -<literal role="rc-notify">notify</literal> section of a <filename role="special"> /.hgrc</filename>\ file. 7.1119 -</para> 7.1120 -<itemizedlist> 7.1121 -<listitem><para><envar role="rc-item-notify">test</envar>: By default, this hook does not send out 7.1122 - email at all; instead, it prints the message that it <emphasis>would</emphasis> 7.1123 - send. Set this item to <literal>false</literal> to allow email to be sent. 7.1124 - The reason that sending of email is turned off by default is that it 7.1125 - takes several tries to configure this extension exactly as you would 7.1126 - like, and it would be bad form to spam subscribers with a number of 7.1127 - <quote>broken</quote> notifications while you debug your configuration. 7.1128 -</para> 7.1129 -</listitem> 7.1130 -<listitem><para><envar role="rc-item-notify">config</envar>: The path to a configuration file that 7.1131 - contains subscription information. This is kept separate from the 7.1132 - main <filename role="special"> /.hgrc</filename>\ so that you can maintain it in a repository of its own. 7.1133 - People can then clone that repository, update their subscriptions, 7.1134 - and push the changes back to your server. 7.1135 -</para> 7.1136 -</listitem> 7.1137 -<listitem><para><envar role="rc-item-notify">strip</envar>: The number of leading path separator 7.1138 - characters to strip from a repository's path, when deciding whether 7.1139 - a repository has subscribers. For example, if the repositories on 7.1140 - your server live in <filename class="directory">/home/hg/repos</filename>, and <literal role="hg-ext">notify</literal> is 7.1141 - considering a repository named <filename class="directory">/home/hg/repos/shared/test</filename>, 7.1142 - setting <envar role="rc-item-notify">strip</envar> to <literal>4</literal> will cause 7.1143 - <literal role="hg-ext">notify</literal> to trim the path it considers down to 7.1144 - <filename class="directory">shared/test</filename>, and it will match subscribers against that. 7.1145 -</para> 7.1146 -</listitem> 7.1147 -<listitem><para><envar role="rc-item-notify">template</envar>: The template text to use when sending 7.1148 - messages. This specifies both the contents of the message header 7.1149 - and its body. 7.1150 -</para> 7.1151 -</listitem> 7.1152 -<listitem><para><envar role="rc-item-notify">maxdiff</envar>: The maximum number of lines of diff 7.1153 - data to append to the end of a message. If a diff is longer than 7.1154 - this, it is truncated. By default, this is set to 300. Set this to 7.1155 - <literal>0</literal> to omit diffs from notification emails. 7.1156 -</para> 7.1157 -</listitem> 7.1158 -<listitem><para><envar role="rc-item-notify">sources</envar>: A list of sources of changesets to 7.1159 - consider. This lets you limit <literal role="hg-ext">notify</literal> to only sending out 7.1160 - email about changes that remote users pushed into this repository 7.1161 - via a server, for example. See section <xref linkend="sec:hook:sources"/> for 7.1162 - the sources you can specify here. 7.1163 -</para> 7.1164 -</listitem></itemizedlist> 7.1165 - 7.1166 -<para>If you set the <envar role="rc-item-web">baseurl</envar> item in the <literal role="rc-web">web</literal> 7.1167 -section, you can use it in a template; it will be available as 7.1168 -<literal>webroot</literal>. 7.1169 -</para> 7.1170 - 7.1171 -<para>Here is an example set of <literal role="hg-ext">notify</literal> configuration information. 7.1172 -</para> 7.1173 -<programlisting> 7.1174 -<para> [notify] 7.1175 - # really send email 7.1176 - test = false 7.1177 - # subscriber data lives in the notify repo 7.1178 - config = /home/hg/repos/notify/notify.conf 7.1179 - # repos live in /home/hg/repos on server, so strip 4 "/" chars 7.1180 - strip = 4 7.1181 - template = X-Hg-Repo: {webroot} 7.1182 - Subject: {webroot}: {desc|firstline|strip} 7.1183 - From: {author} 7.1184 -</para> 7.1185 - 7.1186 -<para> changeset {node|short} in {root} 7.1187 - details: {baseurl}{webroot}?cmd=changeset;node={node|short} 7.1188 - description: 7.1189 - {desc|tabindent|strip} 7.1190 -</para> 7.1191 - 7.1192 -<para> [web] 7.1193 - baseurl = http://hg.example.com/ 7.1194 -</para> 7.1195 -</programlisting> 7.1196 - 7.1197 -<para>This will produce a message that looks like the following: 7.1198 -</para> 7.1199 -<programlisting> 7.1200 -<para> X-Hg-Repo: tests/slave 7.1201 - Subject: tests/slave: Handle error case when slave has no buffers 7.1202 - Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT) 7.1203 -</para> 7.1204 - 7.1205 -<para> changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave 7.1206 - details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 7.1207 - description: 7.1208 - Handle error case when slave has no buffers 7.1209 - diffs (54 lines): 7.1210 -</para> 7.1211 - 7.1212 -<para> diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h 7.1213 - &emdash; a/include/tests.h Wed Aug 02 15:19:52 2006 -0700 7.1214 - +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700 7.1215 - @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h) 7.1216 - [...snip...] 7.1217 -</para> 7.1218 -</programlisting> 7.1219 - 7.1220 -</sect3> 7.1221 -<sect3> 7.1222 -<title>Testing and troubleshooting</title> 7.1223 - 7.1224 -<para>Do not forget that by default, the <literal role="hg-ext">notify</literal> extension \emph{will 7.1225 - not send any mail} until you explicitly configure it to do so, by 7.1226 -setting <envar role="rc-item-notify">test</envar> to <literal>false</literal>. Until you do that, 7.1227 -it simply prints the message it <emphasis>would</emphasis> send. 7.1228 -</para> 7.1229 - 7.1230 -</sect3> 7.1231 -</sect2> 7.1232 -</sect1> 7.1233 -<sect1> 7.1234 -<title>Information for writers of hooks</title> 7.1235 -<para>\label{sec:hook:ref} 7.1236 -</para> 7.1237 - 7.1238 -<sect2> 7.1239 -<title>In-process hook execution</title> 7.1240 - 7.1241 -<para>An in-process hook is called with arguments of the following form: 7.1242 -</para> 7.1243 -<programlisting> 7.1244 -<para> def myhook(ui, repo, **kwargs): 7.1245 - pass 7.1246 -</para> 7.1247 -</programlisting> 7.1248 -<para>The <literal>ui</literal> parameter is a <literal role="py-mod-mercurial.ui">ui</literal> object. 7.1249 -The <literal>repo</literal> parameter is a 7.1250 -<literal role="py-mod-mercurial.localrepo">localrepository</literal> object. The 7.1251 -names and values of the <literal>**kwargs</literal> parameters depend on the 7.1252 -hook being invoked, with the following common features: 7.1253 -</para> 7.1254 -<itemizedlist> 7.1255 -<listitem><para>If a parameter is named <literal>node</literal> or 7.1256 - <literal>parent<emphasis>N</emphasis></literal>, it will contain a hexadecimal changeset ID. 7.1257 - The empty string is used to represent <quote>null changeset ID</quote> instead 7.1258 - of a string of zeroes. 7.1259 -</para> 7.1260 -</listitem> 7.1261 -<listitem><para>If a parameter is named <literal>url</literal>, it will contain the URL of 7.1262 - a remote repository, if that can be determined. 7.1263 -</para> 7.1264 -</listitem> 7.1265 -<listitem><para>Boolean-valued parameters are represented as Python 7.1266 - <literal>bool</literal> objects. 7.1267 -</para> 7.1268 -</listitem></itemizedlist> 7.1269 - 7.1270 -<para>An in-process hook is called without a change to the process's working 7.1271 -directory (unlike external hooks, which are run in the root of the 7.1272 -repository). It must not change the process's working directory, or 7.1273 -it will cause any calls it makes into the Mercurial API to fail. 7.1274 -</para> 7.1275 - 7.1276 -<para>If a hook returns a boolean <quote>false</quote> value, it is considered to have 7.1277 -succeeded. If it returns a boolean <quote>true</quote> value or raises an 7.1278 -exception, it is considered to have failed. A useful way to think of 7.1279 -the calling convention is <quote>tell me if you fail</quote>. 7.1280 -</para> 7.1281 - 7.1282 -<para>Note that changeset IDs are passed into Python hooks as hexadecimal 7.1283 -strings, not the binary hashes that Mercurial's APIs normally use. To 7.1284 -convert a hash from hex to binary, use the 7.1285 -\pymodfunc{mercurial.node}{bin} function. 7.1286 -</para> 7.1287 - 7.1288 -</sect2> 7.1289 -<sect2> 7.1290 -<title>External hook execution</title> 7.1291 - 7.1292 -<para>An external hook is passed to the shell of the user running Mercurial. 7.1293 -Features of that shell, such as variable substitution and command 7.1294 -redirection, are available. The hook is run in the root directory of 7.1295 -the repository (unlike in-process hooks, which are run in the same 7.1296 -directory that Mercurial was run in). 7.1297 -</para> 7.1298 - 7.1299 -<para>Hook parameters are passed to the hook as environment variables. Each 7.1300 -environment variable's name is converted in upper case and prefixed 7.1301 -with the string <quote><literal>HG_</literal></quote>. For example, if the name of a 7.1302 -parameter is <quote><literal>node</literal></quote>, the name of the environment variable 7.1303 -representing that parameter will be <quote><literal>HG_NODE</literal></quote>. 7.1304 -</para> 7.1305 - 7.1306 -<para>A boolean parameter is represented as the string <quote><literal>1</literal></quote> for 7.1307 -<quote>true</quote>, <quote><literal>0</literal></quote> for <quote>false</quote>. If an environment variable is 7.1308 -named <envar>HG_NODE</envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 7.1309 -contains a changeset ID represented as a hexadecimal string. The 7.1310 -empty string is used to represent <quote>null changeset ID</quote> instead of a 7.1311 -string of zeroes. If an environment variable is named 7.1312 -<envar>HG_URL</envar>, it will contain the URL of a remote repository, if 7.1313 -that can be determined. 7.1314 -</para> 7.1315 - 7.1316 -<para>If a hook exits with a status of zero, it is considered to have 7.1317 -succeeded. If it exits with a non-zero status, it is considered to 7.1318 -have failed. 7.1319 -</para> 7.1320 - 7.1321 -</sect2> 7.1322 -<sect2> 7.1323 -<title>Finding out where changesets come from</title> 7.1324 - 7.1325 -<para>A hook that involves the transfer of changesets between a local 7.1326 -repository and another may be able to find out information about the 7.1327 -<quote>far side</quote>. Mercurial knows <emphasis>how</emphasis> changes are being 7.1328 -transferred, and in many cases <emphasis>where</emphasis> they are being transferred 7.1329 -to or from. 7.1330 -</para> 7.1331 - 7.1332 -<sect3> 7.1333 -<title>Sources of changesets</title> 7.1334 -<para>\label{sec:hook:sources} 7.1335 -</para> 7.1336 - 7.1337 -<para>Mercurial will tell a hook what means are, or were, used to transfer 7.1338 -changesets between repositories. This is provided by Mercurial in a 7.1339 -Python parameter named <literal>source</literal>, or an environment variable named 7.1340 -<envar>HG_SOURCE</envar>. 7.1341 -</para> 7.1342 - 7.1343 -<itemizedlist> 7.1344 -<listitem><para><literal>serve</literal>: Changesets are transferred to or from a remote 7.1345 - repository over http or ssh. 7.1346 -</para> 7.1347 -</listitem> 7.1348 -<listitem><para><literal>pull</literal>: Changesets are being transferred via a pull from 7.1349 - one repository into another. 7.1350 -</para> 7.1351 -</listitem> 7.1352 -<listitem><para><literal>push</literal>: Changesets are being transferred via a push from 7.1353 - one repository into another. 7.1354 -</para> 7.1355 -</listitem> 7.1356 -<listitem><para><literal>bundle</literal>: Changesets are being transferred to or from a 7.1357 - bundle. 7.1358 -</para> 7.1359 -</listitem></itemizedlist> 7.1360 - 7.1361 -</sect3> 7.1362 -<sect3> 7.1363 -<title>Where changes are going&emdash;remote repository URLs</title> 7.1364 -<para>\label{sec:hook:url} 7.1365 -</para> 7.1366 - 7.1367 -<para>When possible, Mercurial will tell a hook the location of the <quote>far 7.1368 -side</quote> of an activity that transfers changeset data between 7.1369 -repositories. This is provided by Mercurial in a Python parameter 7.1370 -named <literal>url</literal>, or an environment variable named <envar>HG_URL</envar>. 7.1371 -</para> 7.1372 - 7.1373 -<para>This information is not always known. If a hook is invoked in a 7.1374 -repository that is being served via http or ssh, Mercurial cannot tell 7.1375 -where the remote repository is, but it may know where the client is 7.1376 -connecting from. In such cases, the URL will take one of the 7.1377 -following forms: 7.1378 -</para> 7.1379 -<itemizedlist> 7.1380 -<listitem><para><literal>remote:ssh:<emphasis>ip-address</emphasis></literal>&emdash;remote ssh client, at 7.1381 - the given IP address. 7.1382 -</para> 7.1383 -</listitem> 7.1384 -<listitem><para><literal>remote:http:<emphasis>ip-address</emphasis></literal>&emdash;remote http client, at 7.1385 - the given IP address. If the client is using SSL, this will be of 7.1386 - the form <literal>remote:https:<emphasis>ip-address</emphasis></literal>. 7.1387 -</para> 7.1388 -</listitem> 7.1389 -<listitem><para>Empty&emdash;no information could be discovered about the remote 7.1390 - client. 7.1391 -</para> 7.1392 -</listitem></itemizedlist> 7.1393 - 7.1394 -</sect3> 7.1395 -</sect2> 7.1396 -</sect1> 7.1397 -<sect1> 7.1398 -<title>Hook reference</title> 7.1399 - 7.1400 -<sect2> 7.1401 -<title><literal role="hook">changegroup</literal>&emdash;after remote changesets added</title> 7.1402 -<para>\label{sec:hook:changegroup} 7.1403 -</para> 7.1404 - 7.1405 -<para>This hook is run after a group of pre-existing changesets has been 7.1406 -added to the repository, for example via a <command role="hg-cmd">hg pull</command> or 7.1407 -<command role="hg-cmd">hg unbundle</command>. This hook is run once per operation that added one 7.1408 -or more changesets. This is in contrast to the <literal role="hook">incoming</literal> hook, 7.1409 -which is run once per changeset, regardless of whether the changesets 7.1410 -arrive in a group. 7.1411 -</para> 7.1412 - 7.1413 -<para>Some possible uses for this hook include kicking off an automated 7.1414 -build or test of the added changesets, updating a bug database, or 7.1415 -notifying subscribers that a repository contains new changes. 7.1416 -</para> 7.1417 - 7.1418 -<para>Parameters to this hook: 7.1419 -</para> 7.1420 -<itemizedlist> 7.1421 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 7.1422 - changeset in the group that was added. All changesets between this 7.1423 - and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by 7.1424 - a single <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg unbundle</command>. 7.1425 -</para> 7.1426 -</listitem> 7.1427 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 7.1428 - section <xref linkend="sec:hook:sources"/> for details. 7.1429 -</para> 7.1430 -</listitem> 7.1431 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1432 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1433 -</para> 7.1434 -</listitem></itemizedlist> 7.1435 - 7.1436 -<para>See also: <literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), 7.1437 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>), 7.1438 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>) 7.1439 -</para> 7.1440 - 7.1441 -</sect2> 7.1442 -<sect2> 7.1443 -<title><literal role="hook">commit</literal>&emdash;after a new changeset is created</title> 7.1444 -<para>\label{sec:hook:commit} 7.1445 -</para> 7.1446 - 7.1447 -<para>This hook is run after a new changeset has been created. 7.1448 -</para> 7.1449 - 7.1450 -<para>Parameters to this hook: 7.1451 -</para> 7.1452 -<itemizedlist> 7.1453 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the newly 7.1454 - committed changeset. 7.1455 -</para> 7.1456 -</listitem> 7.1457 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 7.1458 - parent of the newly committed changeset. 7.1459 -</para> 7.1460 -</listitem> 7.1461 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 7.1462 - parent of the newly committed changeset. 7.1463 -</para> 7.1464 -</listitem></itemizedlist> 7.1465 - 7.1466 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>), 7.1467 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>) 7.1468 -</para> 7.1469 - 7.1470 -</sect2> 7.1471 -<sect2> 7.1472 -<title><literal role="hook">incoming</literal>&emdash;after one remote changeset is added</title> 7.1473 -<para>\label{sec:hook:incoming} 7.1474 -</para> 7.1475 - 7.1476 -<para>This hook is run after a pre-existing changeset has been added to the 7.1477 -repository, for example via a <command role="hg-cmd">hg push</command>. If a group of changesets 7.1478 -was added in a single operation, this hook is called once for each 7.1479 -added changeset. 7.1480 -</para> 7.1481 - 7.1482 -<para>You can use this hook for the same purposes as the <literal role="hook">changegroup</literal> 7.1483 -hook (section <xref linkend="sec:hook:changegroup"/>); it's simply more convenient 7.1484 -sometimes to run a hook once per group of changesets, while other 7.1485 -times it's handier once per changeset. 7.1486 -</para> 7.1487 - 7.1488 -<para>Parameters to this hook: 7.1489 -</para> 7.1490 -<itemizedlist> 7.1491 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the newly added 7.1492 - changeset. 7.1493 -</para> 7.1494 -</listitem> 7.1495 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 7.1496 - section <xref linkend="sec:hook:sources"/> for details. 7.1497 -</para> 7.1498 -</listitem> 7.1499 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1500 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1501 -</para> 7.1502 -</listitem></itemizedlist> 7.1503 - 7.1504 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>) <literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>), <literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>) 7.1505 -</para> 7.1506 - 7.1507 -</sect2> 7.1508 -<sect2> 7.1509 -<title><literal role="hook">outgoing</literal>&emdash;after changesets are propagated</title> 7.1510 -<para>\label{sec:hook:outgoing} 7.1511 -</para> 7.1512 - 7.1513 -<para>This hook is run after a group of changesets has been propagated out 7.1514 -of this repository, for example by a <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg bundle</command> 7.1515 -command. 7.1516 -</para> 7.1517 - 7.1518 -<para>One possible use for this hook is to notify administrators that 7.1519 -changes have been pulled. 7.1520 -</para> 7.1521 - 7.1522 -<para>Parameters to this hook: 7.1523 -</para> 7.1524 -<itemizedlist> 7.1525 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 7.1526 - changeset of the group that was sent. 7.1527 -</para> 7.1528 -</listitem> 7.1529 -<listitem><para><literal>source</literal>: A string. The source of the of the operation 7.1530 - (see section <xref linkend="sec:hook:sources"/>). If a remote client pulled 7.1531 - changes from this repository, <literal>source</literal> will be 7.1532 - <literal>serve</literal>. If the client that obtained changes from this 7.1533 - repository was local, <literal>source</literal> will be <literal>bundle</literal>, 7.1534 - <literal>pull</literal>, or <literal>push</literal>, depending on the operation the 7.1535 - client performed. 7.1536 -</para> 7.1537 -</listitem> 7.1538 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1539 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1540 -</para> 7.1541 -</listitem></itemizedlist> 7.1542 - 7.1543 -<para>See also: <literal role="hook">preoutgoing</literal> (section <xref linkend="sec:hook:preoutgoing"/>) 7.1544 -</para> 7.1545 - 7.1546 -</sect2> 7.1547 -<sect2> 7.1548 -<title><literal role="hook">prechangegroup</literal>&emdash;before starting to add remote changesets</title> 7.1549 -<para>\label{sec:hook:prechangegroup} 7.1550 -</para> 7.1551 - 7.1552 -<para>This controlling hook is run before Mercurial begins to add a group of 7.1553 -changesets from another repository. 7.1554 -</para> 7.1555 - 7.1556 -<para>This hook does not have any information about the changesets to be 7.1557 -added, because it is run before transmission of those changesets is 7.1558 -allowed to begin. If this hook fails, the changesets will not be 7.1559 -transmitted. 7.1560 -</para> 7.1561 - 7.1562 -<para>One use for this hook is to prevent external changes from being added 7.1563 -to a repository. For example, you could use this to <quote>freeze</quote> a 7.1564 -server-hosted branch temporarily or permanently so that users cannot 7.1565 -push to it, while still allowing a local administrator to modify the 7.1566 -repository. 7.1567 -</para> 7.1568 - 7.1569 -<para>Parameters to this hook: 7.1570 -</para> 7.1571 -<itemizedlist> 7.1572 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 7.1573 - section <xref linkend="sec:hook:sources"/> for details. 7.1574 -</para> 7.1575 -</listitem> 7.1576 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1577 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1578 -</para> 7.1579 -</listitem></itemizedlist> 7.1580 - 7.1581 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>), 7.1582 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), , 7.1583 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>) 7.1584 -</para> 7.1585 - 7.1586 -</sect2> 7.1587 -<sect2> 7.1588 -<title><literal role="hook">precommit</literal>&emdash;before starting to commit a changeset</title> 7.1589 -<para>\label{sec:hook:precommit} 7.1590 -</para> 7.1591 - 7.1592 -<para>This hook is run before Mercurial begins to commit a new changeset. 7.1593 -It is run before Mercurial has any of the metadata for the commit, 7.1594 -such as the files to be committed, the commit message, or the commit 7.1595 -date. 7.1596 -</para> 7.1597 - 7.1598 -<para>One use for this hook is to disable the ability to commit new 7.1599 -changesets, while still allowing incoming changesets. Another is to 7.1600 -run a build or test, and only allow the commit to begin if the build 7.1601 -or test succeeds. 7.1602 -</para> 7.1603 - 7.1604 -<para>Parameters to this hook: 7.1605 -</para> 7.1606 -<itemizedlist> 7.1607 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 7.1608 - parent of the working directory. 7.1609 -</para> 7.1610 -</listitem> 7.1611 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 7.1612 - parent of the working directory. 7.1613 -</para> 7.1614 -</listitem></itemizedlist> 7.1615 -<para>If the commit proceeds, the parents of the working directory will 7.1616 -become the parents of the new changeset. 7.1617 -</para> 7.1618 - 7.1619 -<para>See also: <literal role="hook">commit</literal> (section <xref linkend="sec:hook:commit"/>), 7.1620 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>) 7.1621 -</para> 7.1622 - 7.1623 -</sect2> 7.1624 -<sect2> 7.1625 -<title><literal role="hook">preoutgoing</literal>&emdash;before starting to propagate changesets</title> 7.1626 -<para>\label{sec:hook:preoutgoing} 7.1627 -</para> 7.1628 - 7.1629 -<para>This hook is invoked before Mercurial knows the identities of the 7.1630 -changesets to be transmitted. 7.1631 -</para> 7.1632 - 7.1633 -<para>One use for this hook is to prevent changes from being transmitted to 7.1634 -another repository. 7.1635 -</para> 7.1636 - 7.1637 -<para>Parameters to this hook: 7.1638 -</para> 7.1639 -<itemizedlist> 7.1640 -<listitem><para><literal>source</literal>: A string. The source of the operation that is 7.1641 - attempting to obtain changes from this repository (see 7.1642 - section <xref linkend="sec:hook:sources"/>). See the documentation for the 7.1643 - <literal>source</literal> parameter to the <literal role="hook">outgoing</literal> hook, in 7.1644 - section <xref linkend="sec:hook:outgoing"/>, for possible values of this 7.1645 - parameter. 7.1646 -</para> 7.1647 -</listitem> 7.1648 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1649 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1650 -</para> 7.1651 -</listitem></itemizedlist> 7.1652 - 7.1653 -<para>See also: <literal role="hook">outgoing</literal> (section <xref linkend="sec:hook:outgoing"/>) 7.1654 -</para> 7.1655 - 7.1656 -</sect2> 7.1657 -<sect2> 7.1658 -<title><literal role="hook">pretag</literal>&emdash;before tagging a changeset</title> 7.1659 -<para>\label{sec:hook:pretag} 7.1660 -</para> 7.1661 - 7.1662 -<para>This controlling hook is run before a tag is created. If the hook 7.1663 -succeeds, creation of the tag proceeds. If the hook fails, the tag is 7.1664 -not created. 7.1665 -</para> 7.1666 - 7.1667 -<para>Parameters to this hook: 7.1668 -</para> 7.1669 -<itemizedlist> 7.1670 -<listitem><para><literal>local</literal>: A boolean. Whether the tag is local to this 7.1671 - repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or 7.1672 - managed by Mercurial (stored in <filename role="special">.hgtags</filename>). 7.1673 -</para> 7.1674 -</listitem> 7.1675 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the changeset to be tagged. 7.1676 -</para> 7.1677 -</listitem> 7.1678 -<listitem><para><literal>tag</literal>: A string. The name of the tag to be created. 7.1679 -</para> 7.1680 -</listitem></itemizedlist> 7.1681 - 7.1682 -<para>If the tag to be created is revision-controlled, the <literal role="hook">precommit</literal> 7.1683 -and <literal role="hook">pretxncommit</literal> hooks (sections <xref linkend="sec:hook:commit"/> 7.1684 -and <xref linkend="sec:hook:pretxncommit"/>) will also be run. 7.1685 -</para> 7.1686 - 7.1687 -<para>See also: <literal role="hook">tag</literal> (section <xref linkend="sec:hook:tag"/>) 7.1688 -</para> 7.1689 - 7.1690 -<para>\subsection{<literal role="hook">pretxnchangegroup</literal>&emdash;before completing addition of 7.1691 - remote changesets} 7.1692 -\label{sec:hook:pretxnchangegroup} 7.1693 -</para> 7.1694 - 7.1695 -<para>This controlling hook is run before a transaction&emdash;that manages the 7.1696 -addition of a group of new changesets from outside the 7.1697 -repository&emdash;completes. If the hook succeeds, the transaction 7.1698 -completes, and all of the changesets become permanent within this 7.1699 -repository. If the hook fails, the transaction is rolled back, and 7.1700 -the data for the changesets is erased. 7.1701 -</para> 7.1702 - 7.1703 -<para>This hook can access the metadata associated with the almost-added 7.1704 -changesets, but it should not do anything permanent with this data. 7.1705 -It must also not modify the working directory. 7.1706 -</para> 7.1707 - 7.1708 -<para>While this hook is running, if other Mercurial processes access this 7.1709 -repository, they will be able to see the almost-added changesets as if 7.1710 -they are permanent. This may lead to race conditions if you do not 7.1711 -take steps to avoid them. 7.1712 -</para> 7.1713 - 7.1714 -<para>This hook can be used to automatically vet a group of changesets. If 7.1715 -the hook fails, all of the changesets are <quote>rejected</quote> when the 7.1716 -transaction rolls back. 7.1717 -</para> 7.1718 - 7.1719 -<para>Parameters to this hook: 7.1720 -</para> 7.1721 -<itemizedlist> 7.1722 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 7.1723 - changeset in the group that was added. All changesets between this 7.1724 - and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by 7.1725 - a single <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg unbundle</command>. 7.1726 -</para> 7.1727 -</listitem> 7.1728 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 7.1729 - section <xref linkend="sec:hook:sources"/> for details. 7.1730 -</para> 7.1731 -</listitem> 7.1732 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 7.1733 - known. See section <xref linkend="sec:hook:url"/> for more information. 7.1734 -</para> 7.1735 -</listitem></itemizedlist> 7.1736 - 7.1737 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>), 7.1738 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), 7.1739 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>) 7.1740 -</para> 7.1741 - 7.1742 -</sect2> 7.1743 -<sect2> 7.1744 -<title><literal role="hook">pretxncommit</literal>&emdash;before completing commit of new changeset</title> 7.1745 -<para>\label{sec:hook:pretxncommit} 7.1746 -</para> 7.1747 - 7.1748 -<para>This controlling hook is run before a transaction&emdash;that manages a new 7.1749 -commit&emdash;completes. If the hook succeeds, the transaction completes 7.1750 -and the changeset becomes permanent within this repository. If the 7.1751 -hook fails, the transaction is rolled back, and the commit data is 7.1752 -erased. 7.1753 -</para> 7.1754 - 7.1755 -<para>This hook can access the metadata associated with the almost-new 7.1756 -changeset, but it should not do anything permanent with this data. It 7.1757 -must also not modify the working directory. 7.1758 -</para> 7.1759 - 7.1760 -<para>While this hook is running, if other Mercurial processes access this 7.1761 -repository, they will be able to see the almost-new changeset as if it 7.1762 -is permanent. This may lead to race conditions if you do not take 7.1763 -steps to avoid them. 7.1764 -</para> 7.1765 - 7.1766 -<para>Parameters to this hook: 7.1767 -</para> 7.1768 -<itemizedlist> 7.1769 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the newly 7.1770 - committed changeset. 7.1771 -</para> 7.1772 -</listitem> 7.1773 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 7.1774 - parent of the newly committed changeset. 7.1775 -</para> 7.1776 -</listitem> 7.1777 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 7.1778 - parent of the newly committed changeset. 7.1779 -</para> 7.1780 -</listitem></itemizedlist> 7.1781 - 7.1782 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>) 7.1783 -</para> 7.1784 - 7.1785 -</sect2> 7.1786 -<sect2> 7.1787 -<title><literal role="hook">preupdate</literal>&emdash;before updating or merging working directory</title> 7.1788 -<para>\label{sec:hook:preupdate} 7.1789 -</para> 7.1790 - 7.1791 -<para>This controlling hook is run before an update or merge of the working 7.1792 -directory begins. It is run only if Mercurial's normal pre-update 7.1793 -checks determine that the update or merge can proceed. If the hook 7.1794 -succeeds, the update or merge may proceed; if it fails, the update or 7.1795 -merge does not start. 7.1796 -</para> 7.1797 - 7.1798 -<para>Parameters to this hook: 7.1799 -</para> 7.1800 -<itemizedlist> 7.1801 -<listitem><para><literal>parent1</literal>: A changeset ID. The ID of the parent that the 7.1802 - working directory is to be updated to. If the working directory is 7.1803 - being merged, it will not change this parent. 7.1804 -</para> 7.1805 -</listitem> 7.1806 -<listitem><para><literal>parent2</literal>: A changeset ID. Only set if the working 7.1807 - directory is being merged. The ID of the revision that the working 7.1808 - directory is being merged with. 7.1809 -</para> 7.1810 -</listitem></itemizedlist> 7.1811 - 7.1812 -<para>See also: <literal role="hook">update</literal> (section <xref linkend="sec:hook:update"/>) 7.1813 -</para> 7.1814 - 7.1815 -</sect2> 7.1816 -<sect2> 7.1817 -<title><literal role="hook">tag</literal>&emdash;after tagging a changeset</title> 7.1818 -<para>\label{sec:hook:tag} 7.1819 -</para> 7.1820 - 7.1821 -<para>This hook is run after a tag has been created. 7.1822 -</para> 7.1823 - 7.1824 -<para>Parameters to this hook: 7.1825 -</para> 7.1826 -<itemizedlist> 7.1827 -<listitem><para><literal>local</literal>: A boolean. Whether the new tag is local to this 7.1828 - repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or 7.1829 - managed by Mercurial (stored in <filename role="special">.hgtags</filename>). 7.1830 -</para> 7.1831 -</listitem> 7.1832 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the changeset that was 7.1833 - tagged. 7.1834 -</para> 7.1835 -</listitem> 7.1836 -<listitem><para><literal>tag</literal>: A string. The name of the tag that was created. 7.1837 -</para> 7.1838 -</listitem></itemizedlist> 7.1839 - 7.1840 -<para>If the created tag is revision-controlled, the <literal role="hook">commit</literal> hook 7.1841 -(section <xref linkend="sec:hook:commit"/>) is run before this hook. 7.1842 -</para> 7.1843 - 7.1844 -<para>See also: <literal role="hook">pretag</literal> (section <xref linkend="sec:hook:pretag"/>) 7.1845 -</para> 7.1846 - 7.1847 -</sect2> 7.1848 -<sect2> 7.1849 -<title><literal role="hook">update</literal>&emdash;after updating or merging working directory</title> 7.1850 -<para>\label{sec:hook:update} 7.1851 -</para> 7.1852 - 7.1853 -<para>This hook is run after an update or merge of the working directory 7.1854 -completes. Since a merge can fail (if the external <command>hgmerge</command> 7.1855 -command fails to resolve conflicts in a file), this hook communicates 7.1856 -whether the update or merge completed cleanly. 7.1857 -</para> 7.1858 - 7.1859 -<itemizedlist> 7.1860 -<listitem><para><literal>error</literal>: A boolean. Indicates whether the update or 7.1861 - merge completed successfully. 7.1862 -</para> 7.1863 -</listitem> 7.1864 -<listitem><para><literal>parent1</literal>: A changeset ID. The ID of the parent that the 7.1865 - working directory was updated to. If the working directory was 7.1866 - merged, it will not have changed this parent. 7.1867 -</para> 7.1868 -</listitem> 7.1869 -<listitem><para><literal>parent2</literal>: A changeset ID. Only set if the working 7.1870 - directory was merged. The ID of the revision that the working 7.1871 - directory was merged with. 7.1872 -</para> 7.1873 -</listitem></itemizedlist> 7.1874 - 7.1875 -<para>See also: <literal role="hook">preupdate</literal> (section <xref linkend="sec:hook:preupdate"/>) 7.1876 -</para> 7.1877 - 7.1878 -</sect2> 7.1879 -</sect1> 7.1880 +<chapter id="chap:hook"> 7.1881 + <?dbhtml filename="handling-repository-events-with-hooks.html"?> 7.1882 + <title>Handling repository events with hooks</title> 7.1883 + 7.1884 + <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform 7.1885 + automated actions in response to events that occur in a 7.1886 + repository. In some cases, you can even control Mercurial's 7.1887 + response to those events.</para> 7.1888 + 7.1889 + <para id="x_1e7">The name Mercurial uses for one of these actions is a 7.1890 + <emphasis>hook</emphasis>. Hooks are called 7.1891 + <quote>triggers</quote> in some revision control systems, but the 7.1892 + two names refer to the same idea.</para> 7.1893 + 7.1894 + <sect1> 7.1895 + <title>An overview of hooks in Mercurial</title> 7.1896 + 7.1897 + <para id="x_1e8">Here is a brief list of the hooks that Mercurial 7.1898 + supports. We will revisit each of these hooks in more detail 7.1899 + later, in <xref linkend="sec:hook:ref"/>.</para> 7.1900 + 7.1901 + <para id="x_1f6">Each of the hooks whose description begins with the word 7.1902 + <quote>Controlling</quote> has the ability to determine whether 7.1903 + an activity can proceed. If the hook succeeds, the activity may 7.1904 + proceed; if it fails, the activity is either not permitted or 7.1905 + undone, depending on the hook.</para> 7.1906 + 7.1907 + <itemizedlist> 7.1908 + <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This 7.1909 + is run after a group of changesets has been brought into the 7.1910 + repository from elsewhere.</para> 7.1911 + </listitem> 7.1912 + <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is 7.1913 + run after a new changeset has been created in the local 7.1914 + repository.</para> 7.1915 + </listitem> 7.1916 + <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is 7.1917 + run once for each new changeset that is brought into the 7.1918 + repository from elsewhere. Notice the difference from 7.1919 + <literal role="hook">changegroup</literal>, which is run 7.1920 + once per <emphasis>group</emphasis> of changesets brought 7.1921 + in.</para> 7.1922 + </listitem> 7.1923 + <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is 7.1924 + run after a group of changesets has been transmitted from 7.1925 + this repository.</para> 7.1926 + </listitem> 7.1927 + <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: 7.1928 + This is run before starting to bring a group of changesets 7.1929 + into the repository. 7.1930 + </para> 7.1931 + </listitem> 7.1932 + <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: 7.1933 + Controlling. This is run before starting a commit. 7.1934 + </para> 7.1935 + </listitem> 7.1936 + <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: 7.1937 + Controlling. This is run before starting to transmit a group 7.1938 + of changesets from this repository. 7.1939 + </para> 7.1940 + </listitem> 7.1941 + <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: 7.1942 + Controlling. This is run before creating a tag. 7.1943 + </para> 7.1944 + </listitem> 7.1945 + <listitem><para id="x_1f1"><literal 7.1946 + role="hook">pretxnchangegroup</literal>: Controlling. This 7.1947 + is run after a group of changesets has been brought into the 7.1948 + local repository from another, but before the transaction 7.1949 + completes that will make the changes permanent in the 7.1950 + repository. 7.1951 + </para> 7.1952 + </listitem> 7.1953 + <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: 7.1954 + Controlling. This is run after a new changeset has been 7.1955 + created in the local repository, but before the transaction 7.1956 + completes that will make it permanent. 7.1957 + </para> 7.1958 + </listitem> 7.1959 + <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: 7.1960 + Controlling. This is run before starting an update or merge 7.1961 + of the working directory. 7.1962 + </para> 7.1963 + </listitem> 7.1964 + <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run 7.1965 + after a tag is created. 7.1966 + </para> 7.1967 + </listitem> 7.1968 + <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is 7.1969 + run after an update or merge of the working directory has 7.1970 + finished. 7.1971 + </para> 7.1972 + </listitem></itemizedlist> 7.1973 + 7.1974 + </sect1> 7.1975 + <sect1> 7.1976 + <title>Hooks and security</title> 7.1977 + 7.1978 + <sect2> 7.1979 + <title>Hooks are run with your privileges</title> 7.1980 + 7.1981 + <para id="x_1f7">When you run a Mercurial command in a repository, and the 7.1982 + command causes a hook to run, that hook runs on 7.1983 + <emphasis>your</emphasis> system, under 7.1984 + <emphasis>your</emphasis> user account, with 7.1985 + <emphasis>your</emphasis> privilege level. Since hooks are 7.1986 + arbitrary pieces of executable code, you should treat them 7.1987 + with an appropriate level of suspicion. Do not install a hook 7.1988 + unless you are confident that you know who created it and what 7.1989 + it does. 7.1990 + </para> 7.1991 + 7.1992 + <para id="x_1f8">In some cases, you may be exposed to hooks that you did 7.1993 + not install yourself. If you work with Mercurial on an 7.1994 + unfamiliar system, Mercurial will run hooks defined in that 7.1995 + system's global <filename role="special">~/.hgrc</filename> 7.1996 + file. 7.1997 + </para> 7.1998 + 7.1999 + <para id="x_1f9">If you are working with a repository owned by another 7.2000 + user, Mercurial can run hooks defined in that user's 7.2001 + repository, but it will still run them as <quote>you</quote>. 7.2002 + For example, if you <command role="hg-cmd">hg pull</command> 7.2003 + from that repository, and its <filename 7.2004 + role="special">.hg/hgrc</filename> defines a local <literal 7.2005 + role="hook">outgoing</literal> hook, that hook will run 7.2006 + under your user account, even though you don't own that 7.2007 + repository. 7.2008 + </para> 7.2009 + 7.2010 + <note> 7.2011 + <para id="x_1fa"> This only applies if you are pulling from a repository 7.2012 + on a local or network filesystem. If you're pulling over 7.2013 + http or ssh, any <literal role="hook">outgoing</literal> 7.2014 + hook will run under whatever account is executing the server 7.2015 + process, on the server. 7.2016 + </para> 7.2017 + </note> 7.2018 + 7.2019 + <para id="x_1fb">To see what hooks are defined in a repository, 7.2020 + use the <command role="hg-cmd">hg showconfig hooks</command> 7.2021 + command. If you are working in one repository, but talking to 7.2022 + another that you do not own (e.g. using <command 7.2023 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 7.2024 + incoming</command>), remember that it is the other 7.2025 + repository's hooks you should be checking, not your own. 7.2026 + </para> 7.2027 + </sect2> 7.2028 + 7.2029 + <sect2> 7.2030 + <title>Hooks do not propagate</title> 7.2031 + 7.2032 + <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do 7.2033 + not propagate when you clone, or pull from, a repository. The 7.2034 + reason for this is simple: a hook is a completely arbitrary 7.2035 + piece of executable code. It runs under your user identity, 7.2036 + with your privilege level, on your machine. 7.2037 + </para> 7.2038 + 7.2039 + <para id="x_1fd">It would be extremely reckless for any distributed 7.2040 + revision control system to implement revision-controlled 7.2041 + hooks, as this would offer an easily exploitable way to 7.2042 + subvert the accounts of users of the revision control system. 7.2043 + </para> 7.2044 + 7.2045 + <para id="x_1fe">Since Mercurial does not propagate hooks, if you are 7.2046 + collaborating with other people on a common project, you 7.2047 + should not assume that they are using the same Mercurial hooks 7.2048 + as you are, or that theirs are correctly configured. You 7.2049 + should document the hooks you expect people to use. 7.2050 + </para> 7.2051 + 7.2052 + <para id="x_1ff">In a corporate intranet, this is somewhat easier to 7.2053 + control, as you can for example provide a 7.2054 + <quote>standard</quote> installation of Mercurial on an NFS 7.2055 + filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 7.2056 + see. However, this too has its limits; see below. 7.2057 + </para> 7.2058 + </sect2> 7.2059 + 7.2060 + <sect2> 7.2061 + <title>Hooks can be overridden</title> 7.2062 + 7.2063 + <para id="x_200">Mercurial allows you to override a hook definition by 7.2064 + redefining the hook. You can disable it by setting its value 7.2065 + to the empty string, or change its behavior as you wish. 7.2066 + </para> 7.2067 + 7.2068 + <para id="x_201">If you deploy a system- or site-wide <filename 7.2069 + role="special">~/.hgrc</filename> file that defines some 7.2070 + hooks, you should thus understand that your users can disable 7.2071 + or override those hooks. 7.2072 + </para> 7.2073 + </sect2> 7.2074 + 7.2075 + <sect2> 7.2076 + <title>Ensuring that critical hooks are run</title> 7.2077 + 7.2078 + <para id="x_202">Sometimes you may want to enforce a policy that you do not 7.2079 + want others to be able to work around. For example, you may 7.2080 + have a requirement that every changeset must pass a rigorous 7.2081 + set of tests. Defining this requirement via a hook in a 7.2082 + site-wide <filename role="special">~/.hgrc</filename> won't 7.2083 + work for remote users on laptops, and of course local users 7.2084 + can subvert it at will by overriding the hook. 7.2085 + </para> 7.2086 + 7.2087 + <para id="x_203">Instead, you can set up your policies for use of Mercurial 7.2088 + so that people are expected to propagate changes through a 7.2089 + well-known <quote>canonical</quote> server that you have 7.2090 + locked down and configured appropriately. 7.2091 + </para> 7.2092 + 7.2093 + <para id="x_204">One way to do this is via a combination of social 7.2094 + engineering and technology. Set up a restricted-access 7.2095 + account; users can push changes over the network to 7.2096 + repositories managed by this account, but they cannot log into 7.2097 + the account and run normal shell commands. In this scenario, 7.2098 + a user can commit a changeset that contains any old garbage 7.2099 + they want. 7.2100 + </para> 7.2101 + 7.2102 + <para id="x_205">When someone pushes a changeset to the server that 7.2103 + everyone pulls from, the server will test the changeset before 7.2104 + it accepts it as permanent, and reject it if it fails to pass 7.2105 + the test suite. If people only pull changes from this 7.2106 + filtering server, it will serve to ensure that all changes 7.2107 + that people pull have been automatically vetted. 7.2108 + </para> 7.2109 + 7.2110 + </sect2> 7.2111 + </sect1> 7.2112 + 7.2113 + <sect1 id="sec:hook:simple"> 7.2114 + <title>A short tutorial on using hooks</title> 7.2115 + 7.2116 + <para id="x_212">It is easy to write a Mercurial hook. Let's start with a 7.2117 + hook that runs when you finish a <command role="hg-cmd">hg 7.2118 + commit</command>, and simply prints the hash of the changeset 7.2119 + you just created. The hook is called <literal 7.2120 + role="hook">commit</literal>. 7.2121 + </para> 7.2122 + 7.2123 + <para id="x_213">All hooks follow the pattern in this example.</para> 7.2124 + 7.2125 +&interaction.hook.simple.init; 7.2126 + 7.2127 + <para id="x_214">You add an entry to the <literal 7.2128 + role="rc-hooks">hooks</literal> section of your <filename 7.2129 + role="special">~/.hgrc</filename>. On the left is the name of 7.2130 + the event to trigger on; on the right is the action to take. As 7.2131 + you can see, you can run an arbitrary shell command in a hook. 7.2132 + Mercurial passes extra information to the hook using environment 7.2133 + variables (look for <envar>HG_NODE</envar> in the example). 7.2134 + </para> 7.2135 + 7.2136 + <sect2> 7.2137 + <title>Performing multiple actions per event</title> 7.2138 + 7.2139 + <para id="x_215">Quite often, you will want to define more than one hook 7.2140 + for a particular kind of event, as shown below.</para> 7.2141 + 7.2142 +&interaction.hook.simple.ext; 7.2143 + 7.2144 + <para id="x_216">Mercurial lets you do this by adding an 7.2145 + <emphasis>extension</emphasis> to the end of a hook's name. 7.2146 + You extend a hook's name by giving the name of the hook, 7.2147 + followed by a full stop (the 7.2148 + <quote><literal>.</literal></quote> character), followed by 7.2149 + some more text of your choosing. For example, Mercurial will 7.2150 + run both <literal>commit.foo</literal> and 7.2151 + <literal>commit.bar</literal> when the 7.2152 + <literal>commit</literal> event occurs. 7.2153 + </para> 7.2154 + 7.2155 + <para id="x_217">To give a well-defined order of execution when there are 7.2156 + multiple hooks defined for an event, Mercurial sorts hooks by 7.2157 + extension, and executes the hook commands in this sorted 7.2158 + order. In the above example, it will execute 7.2159 + <literal>commit.bar</literal> before 7.2160 + <literal>commit.foo</literal>, and <literal>commit</literal> 7.2161 + before both. 7.2162 + </para> 7.2163 + 7.2164 + <para id="x_218">It is a good idea to use a somewhat descriptive 7.2165 + extension when you define a new hook. This will help you to 7.2166 + remember what the hook was for. If the hook fails, you'll get 7.2167 + an error message that contains the hook name and extension, so 7.2168 + using a descriptive extension could give you an immediate hint 7.2169 + as to why the hook failed (see <xref 7.2170 + linkend="sec:hook:perm"/> for an example). 7.2171 + </para> 7.2172 + 7.2173 + </sect2> 7.2174 + <sect2 id="sec:hook:perm"> 7.2175 + <title>Controlling whether an activity can proceed</title> 7.2176 + 7.2177 + <para id="x_219">In our earlier examples, we used the <literal 7.2178 + role="hook">commit</literal> hook, which is run after a 7.2179 + commit has completed. This is one of several Mercurial hooks 7.2180 + that run after an activity finishes. Such hooks have no way 7.2181 + of influencing the activity itself. 7.2182 + </para> 7.2183 + 7.2184 + <para id="x_21a">Mercurial defines a number of events that occur before an 7.2185 + activity starts; or after it starts, but before it finishes. 7.2186 + Hooks that trigger on these events have the added ability to 7.2187 + choose whether the activity can continue, or will abort. 7.2188 + </para> 7.2189 + 7.2190 + <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs 7.2191 + after a commit has all but completed. In other words, the 7.2192 + metadata representing the changeset has been written out to 7.2193 + disk, but the transaction has not yet been allowed to 7.2194 + complete. The <literal role="hook">pretxncommit</literal> 7.2195 + hook has the ability to decide whether the transaction can 7.2196 + complete, or must be rolled back. 7.2197 + </para> 7.2198 + 7.2199 + <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook 7.2200 + exits with a status code of zero, the transaction is allowed 7.2201 + to complete; the commit finishes; and the <literal 7.2202 + role="hook">commit</literal> hook is run. If the <literal 7.2203 + role="hook">pretxncommit</literal> hook exits with a 7.2204 + non-zero status code, the transaction is rolled back; the 7.2205 + metadata representing the changeset is erased; and the 7.2206 + <literal role="hook">commit</literal> hook is not run. 7.2207 + </para> 7.2208 + 7.2209 +&interaction.hook.simple.pretxncommit; 7.2210 + 7.2211 + <para id="x_21d">The hook in the example above checks that a commit comment 7.2212 + contains a bug ID. If it does, the commit can complete. If 7.2213 + not, the commit is rolled back. 7.2214 + </para> 7.2215 + 7.2216 + </sect2> 7.2217 + </sect1> 7.2218 + <sect1> 7.2219 + <title>Writing your own hooks</title> 7.2220 + 7.2221 + <para id="x_21e">When you are writing a hook, you might find it useful to run 7.2222 + Mercurial either with the <option 7.2223 + role="hg-opt-global">-v</option> option, or the <envar 7.2224 + role="rc-item-ui">verbose</envar> config item set to 7.2225 + <quote>true</quote>. When you do so, Mercurial will print a 7.2226 + message before it calls each hook. 7.2227 + </para> 7.2228 + 7.2229 + <sect2 id="sec:hook:lang"> 7.2230 + <title>Choosing how your hook should run</title> 7.2231 + 7.2232 + <para id="x_21f">You can write a hook either as a normal 7.2233 + program&emdash;typically a shell script&emdash;or as a Python 7.2234 + function that is executed within the Mercurial process. 7.2235 + </para> 7.2236 + 7.2237 + <para id="x_220">Writing a hook as an external program has the advantage 7.2238 + that it requires no knowledge of Mercurial's internals. You 7.2239 + can call normal Mercurial commands to get any added 7.2240 + information you need. The trade-off is that external hooks 7.2241 + are slower than in-process hooks. 7.2242 + </para> 7.2243 + 7.2244 + <para id="x_221">An in-process Python hook has complete access to the 7.2245 + Mercurial API, and does not <quote>shell out</quote> to 7.2246 + another process, so it is inherently faster than an external 7.2247 + hook. It is also easier to obtain much of the information 7.2248 + that a hook requires by using the Mercurial API than by 7.2249 + running Mercurial commands. 7.2250 + </para> 7.2251 + 7.2252 + <para id="x_222">If you are comfortable with Python, or require high 7.2253 + performance, writing your hooks in Python may be a good 7.2254 + choice. However, when you have a straightforward hook to 7.2255 + write and you don't need to care about performance (probably 7.2256 + the majority of hooks), a shell script is perfectly fine. 7.2257 + </para> 7.2258 + 7.2259 + </sect2> 7.2260 + <sect2 id="sec:hook:param"> 7.2261 + <title>Hook parameters</title> 7.2262 + 7.2263 + <para id="x_223">Mercurial calls each hook with a set of well-defined 7.2264 + parameters. In Python, a parameter is passed as a keyword 7.2265 + argument to your hook function. For an external program, a 7.2266 + parameter is passed as an environment variable. 7.2267 + </para> 7.2268 + 7.2269 + <para id="x_224">Whether your hook is written in Python or as a shell 7.2270 + script, the hook-specific parameter names and values will be 7.2271 + the same. A boolean parameter will be represented as a 7.2272 + boolean value in Python, but as the number 1 (for 7.2273 + <quote>true</quote>) or 0 (for <quote>false</quote>) as an 7.2274 + environment variable for an external hook. If a hook 7.2275 + parameter is named <literal>foo</literal>, the keyword 7.2276 + argument for a Python hook will also be named 7.2277 + <literal>foo</literal>, while the environment variable for an 7.2278 + external hook will be named <literal>HG_FOO</literal>. 7.2279 + </para> 7.2280 + </sect2> 7.2281 + 7.2282 + <sect2> 7.2283 + <title>Hook return values and activity control</title> 7.2284 + 7.2285 + <para id="x_225">A hook that executes successfully must exit with a status 7.2286 + of zero if external, or return boolean <quote>false</quote> if 7.2287 + in-process. Failure is indicated with a non-zero exit status 7.2288 + from an external hook, or an in-process hook returning boolean 7.2289 + <quote>true</quote>. If an in-process hook raises an 7.2290 + exception, the hook is considered to have failed. 7.2291 + </para> 7.2292 + 7.2293 + <para id="x_226">For a hook that controls whether an activity can proceed, 7.2294 + zero/false means <quote>allow</quote>, while 7.2295 + non-zero/true/exception means <quote>deny</quote>. 7.2296 + </para> 7.2297 + </sect2> 7.2298 + 7.2299 + <sect2> 7.2300 + <title>Writing an external hook</title> 7.2301 + 7.2302 + <para id="x_227">When you define an external hook in your <filename 7.2303 + role="special">~/.hgrc</filename> and the hook is run, its 7.2304 + value is passed to your shell, which interprets it. This 7.2305 + means that you can use normal shell constructs in the body of 7.2306 + the hook. 7.2307 + </para> 7.2308 + 7.2309 + <para id="x_228">An executable hook is always run with its current 7.2310 + directory set to a repository's root directory. 7.2311 + </para> 7.2312 + 7.2313 + <para id="x_229">Each hook parameter is passed in as an environment 7.2314 + variable; the name is upper-cased, and prefixed with the 7.2315 + string <quote><literal>HG_</literal></quote>. 7.2316 + </para> 7.2317 + 7.2318 + <para id="x_22a">With the exception of hook parameters, Mercurial does not 7.2319 + set or modify any environment variables when running a hook. 7.2320 + This is useful to remember if you are writing a site-wide hook 7.2321 + that may be run by a number of different users with differing 7.2322 + environment variables set. In multi-user situations, you 7.2323 + should not rely on environment variables being set to the 7.2324 + values you have in your environment when testing the hook. 7.2325 + </para> 7.2326 + </sect2> 7.2327 + 7.2328 + <sect2> 7.2329 + <title>Telling Mercurial to use an in-process hook</title> 7.2330 + 7.2331 + <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax 7.2332 + for defining an in-process hook is slightly different than for 7.2333 + an executable hook. The value of the hook must start with the 7.2334 + text <quote><literal>python:</literal></quote>, and continue 7.2335 + with the fully-qualified name of a callable object to use as 7.2336 + the hook's value. 7.2337 + </para> 7.2338 + 7.2339 + <para id="x_22c">The module in which a hook lives is automatically imported 7.2340 + when a hook is run. So long as you have the module name and 7.2341 + <envar>PYTHONPATH</envar> right, it should <quote>just 7.2342 + work</quote>. 7.2343 + </para> 7.2344 + 7.2345 + <para id="x_22d">The following <filename role="special">~/.hgrc</filename> 7.2346 + example snippet illustrates the syntax and meaning of the 7.2347 + notions we just described. 7.2348 + </para> 7.2349 + <programlisting>[hooks] 7.2350 +commit.example = python:mymodule.submodule.myhook</programlisting> 7.2351 + <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> 7.2352 + hook, it imports <literal>mymodule.submodule</literal>, looks 7.2353 + for the callable object named <literal>myhook</literal>, and 7.2354 + calls it. 7.2355 + </para> 7.2356 + </sect2> 7.2357 + 7.2358 + <sect2> 7.2359 + <title>Writing an in-process hook</title> 7.2360 + 7.2361 + <para id="x_22f">The simplest in-process hook does nothing, but illustrates 7.2362 + the basic shape of the hook API: 7.2363 + </para> 7.2364 + <programlisting>def myhook(ui, repo, **kwargs): 7.2365 + pass</programlisting> 7.2366 + <para id="x_230">The first argument to a Python hook is always a <literal 7.2367 + role="py-mod-mercurial.ui">ui</literal> object. The second 7.2368 + is a repository object; at the moment, it is always an 7.2369 + instance of <literal 7.2370 + role="py-mod-mercurial.localrepo">localrepository</literal>. 7.2371 + Following these two arguments are other keyword arguments. 7.2372 + Which ones are passed in depends on the hook being called, but 7.2373 + a hook can ignore arguments it doesn't care about by dropping 7.2374 + them into a keyword argument dict, as with 7.2375 + <literal>**kwargs</literal> above. 7.2376 + </para> 7.2377 + 7.2378 + </sect2> 7.2379 + </sect1> 7.2380 + <sect1> 7.2381 + <title>Some hook examples</title> 7.2382 + 7.2383 + <sect2> 7.2384 + <title>Writing meaningful commit messages</title> 7.2385 + 7.2386 + <para id="x_231">It's hard to imagine a useful commit message being very 7.2387 + short. The simple <literal role="hook">pretxncommit</literal> 7.2388 + hook of the example below will prevent you from committing a 7.2389 + changeset with a message that is less than ten bytes long. 7.2390 + </para> 7.2391 + 7.2392 +&interaction.hook.msglen.go; 7.2393 + </sect2> 7.2394 + 7.2395 + <sect2> 7.2396 + <title>Checking for trailing whitespace</title> 7.2397 + 7.2398 + <para id="x_232">An interesting use of a commit-related hook is to help you 7.2399 + to write cleaner code. A simple example of <quote>cleaner 7.2400 + code</quote> is the dictum that a change should not add any 7.2401 + new lines of text that contain <quote>trailing 7.2402 + whitespace</quote>. Trailing whitespace is a series of 7.2403 + space and tab characters at the end of a line of text. In 7.2404 + most cases, trailing whitespace is unnecessary, invisible 7.2405 + noise, but it is occasionally problematic, and people often 7.2406 + prefer to get rid of it. 7.2407 + </para> 7.2408 + 7.2409 + <para id="x_233">You can use either the <literal 7.2410 + role="hook">precommit</literal> or <literal 7.2411 + role="hook">pretxncommit</literal> hook to tell whether you 7.2412 + have a trailing whitespace problem. If you use the <literal 7.2413 + role="hook">precommit</literal> hook, the hook will not know 7.2414 + which files you are committing, so it will have to check every 7.2415 + modified file in the repository for trailing white space. If 7.2416 + you want to commit a change to just the file 7.2417 + <filename>foo</filename>, but the file 7.2418 + <filename>bar</filename> contains trailing whitespace, doing a 7.2419 + check in the <literal role="hook">precommit</literal> hook 7.2420 + will prevent you from committing <filename>foo</filename> due 7.2421 + to the problem with <filename>bar</filename>. This doesn't 7.2422 + seem right. 7.2423 + </para> 7.2424 + 7.2425 + <para id="x_234">Should you choose the <literal 7.2426 + role="hook">pretxncommit</literal> hook, the check won't 7.2427 + occur until just before the transaction for the commit 7.2428 + completes. This will allow you to check for problems only the 7.2429 + exact files that are being committed. However, if you entered 7.2430 + the commit message interactively and the hook fails, the 7.2431 + transaction will roll back; you'll have to re-enter the commit 7.2432 + message after you fix the trailing whitespace and run <command 7.2433 + role="hg-cmd">hg commit</command> again. 7.2434 + </para> 7.2435 + 7.2436 + &interaction.ch09-hook.ws.simple; 7.2437 + 7.2438 + <para id="x_235">In this example, we introduce a simple <literal 7.2439 + role="hook">pretxncommit</literal> hook that checks for 7.2440 + trailing whitespace. This hook is short, but not very 7.2441 + helpful. It exits with an error status if a change adds a 7.2442 + line with trailing whitespace to any file, but does not print 7.2443 + any information that might help us to identify the offending 7.2444 + file or line. It also has the nice property of not paying 7.2445 + attention to unmodified lines; only lines that introduce new 7.2446 + trailing whitespace cause problems. 7.2447 + </para> 7.2448 + 7.2449 + &ch09-check_whitespace.py.lst; 7.2450 + 7.2451 + <para id="x_236">The above version is much more complex, but also more 7.2452 + useful. It parses a unified diff to see if any lines add 7.2453 + trailing whitespace, and prints the name of the file and the 7.2454 + line number of each such occurrence. Even better, if the 7.2455 + change adds trailing whitespace, this hook saves the commit 7.2456 + comment and prints the name of the save file before exiting 7.2457 + and telling Mercurial to roll the transaction back, so you can 7.2458 + use the <option role="hg-opt-commit">-l filename</option> 7.2459 + option to <command role="hg-cmd">hg commit</command> to reuse 7.2460 + the saved commit message once you've corrected the problem. 7.2461 + </para> 7.2462 + 7.2463 + &interaction.ch09-hook.ws.better; 7.2464 + 7.2465 + <para id="x_237">As a final aside, note in the example above the 7.2466 + use of <command>sed</command>'s in-place editing feature to 7.2467 + get rid of trailing whitespace from a file. This is concise 7.2468 + and useful enough that I will reproduce it here (using 7.2469 + <command>perl</command> for good measure).</para> 7.2470 + <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> 7.2471 + 7.2472 + </sect2> 7.2473 + </sect1> 7.2474 + <sect1> 7.2475 + <title>Bundled hooks</title> 7.2476 + 7.2477 + <para id="x_238">Mercurial ships with several bundled hooks. You can find 7.2478 + them in the <filename class="directory">hgext</filename> 7.2479 + directory of a Mercurial source tree. If you are using a 7.2480 + Mercurial binary package, the hooks will be located in the 7.2481 + <filename class="directory">hgext</filename> directory of 7.2482 + wherever your package installer put Mercurial. 7.2483 + </para> 7.2484 + 7.2485 + <sect2> 7.2486 + <title><literal role="hg-ext">acl</literal>&emdash;access 7.2487 + control for parts of a repository</title> 7.2488 + 7.2489 + <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets 7.2490 + you control which remote users are allowed to push changesets 7.2491 + to a networked server. You can protect any portion of a 7.2492 + repository (including the entire repo), so that a specific 7.2493 + remote user can push changes that do not affect the protected 7.2494 + portion. 7.2495 + </para> 7.2496 + 7.2497 + <para id="x_23a">This extension implements access control based on the 7.2498 + identity of the user performing a push, 7.2499 + <emphasis>not</emphasis> on who committed the changesets 7.2500 + they're pushing. It makes sense to use this hook only if you 7.2501 + have a locked-down server environment that authenticates 7.2502 + remote users, and you want to be sure that only specific users 7.2503 + are allowed to push changes to that server. 7.2504 + </para> 7.2505 + 7.2506 + <sect3> 7.2507 + <title>Configuring the <literal role="hook">acl</literal> 7.2508 + hook</title> 7.2509 + 7.2510 + <para id="x_23b">In order to manage incoming changesets, the <literal 7.2511 + role="hg-ext">acl</literal> hook must be used as a 7.2512 + <literal role="hook">pretxnchangegroup</literal> hook. This 7.2513 + lets it see which files are modified by each incoming 7.2514 + changeset, and roll back a group of changesets if they 7.2515 + modify <quote>forbidden</quote> files. Example: 7.2516 + </para> 7.2517 + <programlisting>[hooks] 7.2518 +pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> 7.2519 + 7.2520 + <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is 7.2521 + configured using three sections. 7.2522 + </para> 7.2523 + 7.2524 + <para id="x_23d">The <literal role="rc-acl">acl</literal> section has 7.2525 + only one entry, <envar role="rc-item-acl">sources</envar>, 7.2526 + which lists the sources of incoming changesets that the hook 7.2527 + should pay attention to. You don't normally need to 7.2528 + configure this section. 7.2529 + </para> 7.2530 + <itemizedlist> 7.2531 + <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: 7.2532 + Control incoming changesets that are arriving from a 7.2533 + remote repository over http or ssh. This is the default 7.2534 + value of <envar role="rc-item-acl">sources</envar>, and 7.2535 + usually the only setting you'll need for this 7.2536 + configuration item. 7.2537 + </para> 7.2538 + </listitem> 7.2539 + <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: 7.2540 + Control incoming changesets that are arriving via a pull 7.2541 + from a local repository. 7.2542 + </para> 7.2543 + </listitem> 7.2544 + <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: 7.2545 + Control incoming changesets that are arriving via a push 7.2546 + from a local repository. 7.2547 + </para> 7.2548 + </listitem> 7.2549 + <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: 7.2550 + Control incoming changesets that are arriving from 7.2551 + another repository via a bundle. 7.2552 + </para> 7.2553 + </listitem></itemizedlist> 7.2554 + 7.2555 + <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> 7.2556 + section controls the users that are allowed to add 7.2557 + changesets to the repository. If this section is not 7.2558 + present, all users that are not explicitly denied are 7.2559 + allowed. If this section is present, all users that are not 7.2560 + explicitly allowed are denied (so an empty section means 7.2561 + that all users are denied). 7.2562 + </para> 7.2563 + 7.2564 + <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> 7.2565 + section determines which users are denied from adding 7.2566 + changesets to the repository. If this section is not 7.2567 + present or is empty, no users are denied. 7.2568 + </para> 7.2569 + 7.2570 + <para id="x_244">The syntaxes for the <literal 7.2571 + role="rc-acl.allow">acl.allow</literal> and <literal 7.2572 + role="rc-acl.deny">acl.deny</literal> sections are 7.2573 + identical. On the left of each entry is a glob pattern that 7.2574 + matches files or directories, relative to the root of the 7.2575 + repository; on the right, a user name. 7.2576 + </para> 7.2577 + 7.2578 + <para id="x_245">In the following example, the user 7.2579 + <literal>docwriter</literal> can only push changes to the 7.2580 + <filename class="directory">docs</filename> subtree of the 7.2581 + repository, while <literal>intern</literal> can push changes 7.2582 + to any file or directory except <filename 7.2583 + class="directory">source/sensitive</filename>. 7.2584 + </para> 7.2585 + <programlisting>[acl.allow] 7.2586 +docs/** = docwriter 7.2587 +[acl.deny] 7.2588 +source/sensitive/** = intern</programlisting> 7.2589 + 7.2590 + </sect3> 7.2591 + <sect3> 7.2592 + <title>Testing and troubleshooting</title> 7.2593 + 7.2594 + <para id="x_246">If you want to test the <literal 7.2595 + role="hg-ext">acl</literal> hook, run it with Mercurial's 7.2596 + debugging output enabled. Since you'll probably be running 7.2597 + it on a server where it's not convenient (or sometimes 7.2598 + possible) to pass in the <option 7.2599 + role="hg-opt-global">--debug</option> option, don't forget 7.2600 + that you can enable debugging output in your <filename 7.2601 + role="special">~/.hgrc</filename>: 7.2602 + </para> 7.2603 + <programlisting>[ui] 7.2604 +debug = true</programlisting> 7.2605 + <para id="x_247">With this enabled, the <literal 7.2606 + role="hg-ext">acl</literal> hook will print enough 7.2607 + information to let you figure out why it is allowing or 7.2608 + forbidding pushes from specific users. 7.2609 + </para> 7.2610 + 7.2611 + </sect3> </sect2> 7.2612 + 7.2613 + <sect2> 7.2614 + <title><literal 7.2615 + role="hg-ext">bugzilla</literal>&emdash;integration with 7.2616 + Bugzilla</title> 7.2617 + 7.2618 + <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension 7.2619 + adds a comment to a Bugzilla bug whenever it finds a reference 7.2620 + to that bug ID in a commit comment. You can install this hook 7.2621 + on a shared server, so that any time a remote user pushes 7.2622 + changes to this server, the hook gets run. 7.2623 + </para> 7.2624 + 7.2625 + <para id="x_249">It adds a comment to the bug that looks like this (you can 7.2626 + configure the contents of the comment&emdash;see below): 7.2627 + </para> 7.2628 + <programlisting>Changeset aad8b264143a, made by Joe User 7.2629 + <joe.user@domain.com> in the frobnitz repository, refers 7.2630 + to this bug. For complete details, see 7.2631 + http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 7.2632 + Changeset description: Fix bug 10483 by guarding against some 7.2633 + NULL pointers</programlisting> 7.2634 + <para id="x_24a">The value of this hook is that it automates the process of 7.2635 + updating a bug any time a changeset refers to it. If you 7.2636 + configure the hook properly, it makes it easy for people to 7.2637 + browse straight from a Bugzilla bug to a changeset that refers 7.2638 + to that bug. 7.2639 + </para> 7.2640 + 7.2641 + <para id="x_24b">You can use the code in this hook as a starting point for 7.2642 + some more exotic Bugzilla integration recipes. Here are a few 7.2643 + possibilities: 7.2644 + </para> 7.2645 + <itemizedlist> 7.2646 + <listitem><para id="x_24c">Require that every changeset pushed to the 7.2647 + server have a valid bug ID in its commit comment. In this 7.2648 + case, you'd want to configure the hook as a <literal 7.2649 + role="hook">pretxncommit</literal> hook. This would 7.2650 + allow the hook to reject changes that didn't contain bug 7.2651 + IDs. 7.2652 + </para> 7.2653 + </listitem> 7.2654 + <listitem><para id="x_24d">Allow incoming changesets to automatically 7.2655 + modify the <emphasis>state</emphasis> of a bug, as well as 7.2656 + simply adding a comment. For example, the hook could 7.2657 + recognise the string <quote>fixed bug 31337</quote> as 7.2658 + indicating that it should update the state of bug 31337 to 7.2659 + <quote>requires testing</quote>. 7.2660 + </para> 7.2661 + </listitem></itemizedlist> 7.2662 + 7.2663 + <sect3 id="sec:hook:bugzilla:config"> 7.2664 + <title>Configuring the <literal role="hook">bugzilla</literal> 7.2665 + hook</title> 7.2666 + 7.2667 + <para id="x_24e">You should configure this hook in your server's 7.2668 + <filename role="special">~/.hgrc</filename> as an <literal 7.2669 + role="hook">incoming</literal> hook, for example as 7.2670 + follows: 7.2671 + </para> 7.2672 + <programlisting>[hooks] 7.2673 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> 7.2674 + 7.2675 + <para id="x_24f">Because of the specialised nature of this hook, and 7.2676 + because Bugzilla was not written with this kind of 7.2677 + integration in mind, configuring this hook is a somewhat 7.2678 + involved process. 7.2679 + </para> 7.2680 + 7.2681 + <para id="x_250">Before you begin, you must install the MySQL bindings 7.2682 + for Python on the host(s) where you'll be running the hook. 7.2683 + If this is not available as a binary package for your 7.2684 + system, you can download it from 7.2685 + <citation>web:mysql-python</citation>. 7.2686 + </para> 7.2687 + 7.2688 + <para id="x_251">Configuration information for this hook lives in the 7.2689 + <literal role="rc-bugzilla">bugzilla</literal> section of 7.2690 + your <filename role="special">~/.hgrc</filename>. 7.2691 + </para> 7.2692 + <itemizedlist> 7.2693 + <listitem><para id="x_252"><envar 7.2694 + role="rc-item-bugzilla">version</envar>: The version 7.2695 + of Bugzilla installed on the server. The database 7.2696 + schema that Bugzilla uses changes occasionally, so this 7.2697 + hook has to know exactly which schema to use.</para> 7.2698 + </listitem> 7.2699 + <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: 7.2700 + The hostname of the MySQL server that stores your 7.2701 + Bugzilla data. The database must be configured to allow 7.2702 + connections from whatever host you are running the 7.2703 + <literal role="hook">bugzilla</literal> hook on. 7.2704 + </para> 7.2705 + </listitem> 7.2706 + <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: 7.2707 + The username with which to connect to the MySQL server. 7.2708 + The database must be configured to allow this user to 7.2709 + connect from whatever host you are running the <literal 7.2710 + role="hook">bugzilla</literal> hook on. This user 7.2711 + must be able to access and modify Bugzilla tables. The 7.2712 + default value of this item is <literal>bugs</literal>, 7.2713 + which is the standard name of the Bugzilla user in a 7.2714 + MySQL database. 7.2715 + </para> 7.2716 + </listitem> 7.2717 + <listitem><para id="x_255"><envar 7.2718 + role="rc-item-bugzilla">password</envar>: The MySQL 7.2719 + password for the user you configured above. This is 7.2720 + stored as plain text, so you should make sure that 7.2721 + unauthorised users cannot read the <filename 7.2722 + role="special">~/.hgrc</filename> file where you 7.2723 + store this information. 7.2724 + </para> 7.2725 + </listitem> 7.2726 + <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: 7.2727 + The name of the Bugzilla database on the MySQL server. 7.2728 + The default value of this item is 7.2729 + <literal>bugs</literal>, which is the standard name of 7.2730 + the MySQL database where Bugzilla stores its data. 7.2731 + </para> 7.2732 + </listitem> 7.2733 + <listitem><para id="x_257"><envar 7.2734 + role="rc-item-bugzilla">notify</envar>: If you want 7.2735 + Bugzilla to send out a notification email to subscribers 7.2736 + after this hook has added a comment to a bug, you will 7.2737 + need this hook to run a command whenever it updates the 7.2738 + database. The command to run depends on where you have 7.2739 + installed Bugzilla, but it will typically look something 7.2740 + like this, if you have Bugzilla installed in <filename 7.2741 + class="directory">/var/www/html/bugzilla</filename>: 7.2742 + </para> 7.2743 + <programlisting>cd /var/www/html/bugzilla && 7.2744 + ./processmail %s nobody@nowhere.com</programlisting> 7.2745 + </listitem> 7.2746 + <listitem><para id="x_258"> The Bugzilla 7.2747 + <literal>processmail</literal> program expects to be 7.2748 + given a bug ID (the hook replaces 7.2749 + <quote><literal>%s</literal></quote> with the bug ID) 7.2750 + and an email address. It also expects to be able to 7.2751 + write to some files in the directory that it runs in. 7.2752 + If Bugzilla and this hook are not installed on the same 7.2753 + machine, you will need to find a way to run 7.2754 + <literal>processmail</literal> on the server where 7.2755 + Bugzilla is installed. 7.2756 + </para> 7.2757 + </listitem></itemizedlist> 7.2758 + 7.2759 + </sect3> 7.2760 + <sect3> 7.2761 + <title>Mapping committer names to Bugzilla user names</title> 7.2762 + 7.2763 + <para id="x_259">By default, the <literal 7.2764 + role="hg-ext">bugzilla</literal> hook tries to use the 7.2765 + email address of a changeset's committer as the Bugzilla 7.2766 + user name with which to update a bug. If this does not suit 7.2767 + your needs, you can map committer email addresses to 7.2768 + Bugzilla user names using a <literal 7.2769 + role="rc-usermap">usermap</literal> section. 7.2770 + </para> 7.2771 + 7.2772 + <para id="x_25a">Each item in the <literal 7.2773 + role="rc-usermap">usermap</literal> section contains an 7.2774 + email address on the left, and a Bugzilla user name on the 7.2775 + right. 7.2776 + </para> 7.2777 + <programlisting>[usermap] 7.2778 +jane.user@example.com = jane</programlisting> 7.2779 + <para id="x_25b">You can either keep the <literal 7.2780 + role="rc-usermap">usermap</literal> data in a normal 7.2781 + <filename role="special">~/.hgrc</filename>, or tell the 7.2782 + <literal role="hg-ext">bugzilla</literal> hook to read the 7.2783 + information from an external <filename>usermap</filename> 7.2784 + file. In the latter case, you can store 7.2785 + <filename>usermap</filename> data by itself in (for example) 7.2786 + a user-modifiable repository. This makes it possible to let 7.2787 + your users maintain their own <envar 7.2788 + role="rc-item-bugzilla">usermap</envar> entries. The main 7.2789 + <filename role="special">~/.hgrc</filename> file might look 7.2790 + like this: 7.2791 + </para> 7.2792 + <programlisting># regular hgrc file refers to external usermap file 7.2793 +[bugzilla] 7.2794 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 7.2795 + <para id="x_25c">While the <filename>usermap</filename> file that it 7.2796 + refers to might look like this: 7.2797 + </para> 7.2798 + <programlisting># bugzilla-usermap.conf - inside a hg repository 7.2799 +[usermap] stephanie@example.com = steph</programlisting> 7.2800 + 7.2801 + </sect3> 7.2802 + <sect3> 7.2803 + <title>Configuring the text that gets added to a bug</title> 7.2804 + 7.2805 + <para id="x_25d">You can configure the text that this hook adds as a 7.2806 + comment; you specify it in the form of a Mercurial template. 7.2807 + Several <filename role="special">~/.hgrc</filename> entries 7.2808 + (still in the <literal role="rc-bugzilla">bugzilla</literal> 7.2809 + section) control this behavior. 7.2810 + </para> 7.2811 + <itemizedlist> 7.2812 + <listitem><para id="x_25e"><literal>strip</literal>: The number of 7.2813 + leading path elements to strip from a repository's path 7.2814 + name to construct a partial path for a URL. For example, 7.2815 + if the repositories on your server live under <filename 7.2816 + class="directory">/home/hg/repos</filename>, and you 7.2817 + have a repository whose path is <filename 7.2818 + class="directory">/home/hg/repos/app/tests</filename>, 7.2819 + then setting <literal>strip</literal> to 7.2820 + <literal>4</literal> will give a partial path of 7.2821 + <filename class="directory">app/tests</filename>. The 7.2822 + hook will make this partial path available when 7.2823 + expanding a template, as <literal>webroot</literal>. 7.2824 + </para> 7.2825 + </listitem> 7.2826 + <listitem><para id="x_25f"><literal>template</literal>: The text of the 7.2827 + template to use. In addition to the usual 7.2828 + changeset-related variables, this template can use 7.2829 + <literal>hgweb</literal> (the value of the 7.2830 + <literal>hgweb</literal> configuration item above) and 7.2831 + <literal>webroot</literal> (the path constructed using 7.2832 + <literal>strip</literal> above). 7.2833 + </para> 7.2834 + </listitem></itemizedlist> 7.2835 + 7.2836 + <para id="x_260">In addition, you can add a <envar 7.2837 + role="rc-item-web">baseurl</envar> item to the <literal 7.2838 + role="rc-web">web</literal> section of your <filename 7.2839 + role="special">~/.hgrc</filename>. The <literal 7.2840 + role="hg-ext">bugzilla</literal> hook will make this 7.2841 + available when expanding a template, as the base string to 7.2842 + use when constructing a URL that will let users browse from 7.2843 + a Bugzilla comment to view a changeset. Example: 7.2844 + </para> 7.2845 + <programlisting>[web] 7.2846 +baseurl = http://hg.domain.com/</programlisting> 7.2847 + 7.2848 + <para id="x_261">Here is an example set of <literal 7.2849 + role="hg-ext">bugzilla</literal> hook config information. 7.2850 + </para> 7.2851 + 7.2852 + &ch10-bugzilla-config.lst; 7.2853 + 7.2854 + </sect3> 7.2855 + <sect3> 7.2856 + <title>Testing and troubleshooting</title> 7.2857 + 7.2858 + <para id="x_262">The most common problems with configuring the <literal 7.2859 + role="hg-ext">bugzilla</literal> hook relate to running 7.2860 + Bugzilla's <filename>processmail</filename> script and 7.2861 + mapping committer names to user names. 7.2862 + </para> 7.2863 + 7.2864 + <para id="x_263">Recall from <xref 7.2865 + linkend="sec:hook:bugzilla:config"/> above that the user 7.2866 + that runs the Mercurial process on the server is also the 7.2867 + one that will run the <filename>processmail</filename> 7.2868 + script. The <filename>processmail</filename> script 7.2869 + sometimes causes Bugzilla to write to files in its 7.2870 + configuration directory, and Bugzilla's configuration files 7.2871 + are usually owned by the user that your web server runs 7.2872 + under. 7.2873 + </para> 7.2874 + 7.2875 + <para id="x_264">You can cause <filename>processmail</filename> to be run 7.2876 + with the suitable user's identity using the 7.2877 + <command>sudo</command> command. Here is an example entry 7.2878 + for a <filename>sudoers</filename> file. 7.2879 + </para> 7.2880 + <programlisting>hg_user = (httpd_user) 7.2881 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> 7.2882 + <para id="x_265">This allows the <literal>hg_user</literal> user to run a 7.2883 + <filename>processmail-wrapper</filename> program under the 7.2884 + identity of <literal>httpd_user</literal>. 7.2885 + </para> 7.2886 + 7.2887 + <para id="x_266">This indirection through a wrapper script is necessary, 7.2888 + because <filename>processmail</filename> expects to be run 7.2889 + with its current directory set to wherever you installed 7.2890 + Bugzilla; you can't specify that kind of constraint in a 7.2891 + <filename>sudoers</filename> file. The contents of the 7.2892 + wrapper script are simple: 7.2893 + </para> 7.2894 + <programlisting>#!/bin/sh 7.2895 +cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> 7.2896 + <para id="x_267">It doesn't seem to matter what email address you pass to 7.2897 + <filename>processmail</filename>. 7.2898 + </para> 7.2899 + 7.2900 + <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is 7.2901 + not set up correctly, users will see an error message from 7.2902 + the <literal role="hg-ext">bugzilla</literal> hook when they 7.2903 + push changes to the server. The error message will look 7.2904 + like this: 7.2905 + </para> 7.2906 + <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> 7.2907 + <para id="x_269">What this means is that the committer's address, 7.2908 + <literal>john.q.public@example.com</literal>, is not a valid 7.2909 + Bugzilla user name, nor does it have an entry in your 7.2910 + <literal role="rc-usermap">usermap</literal> that maps it to 7.2911 + a valid Bugzilla user name. 7.2912 + </para> 7.2913 + 7.2914 + </sect3> </sect2> 7.2915 + 7.2916 + <sect2> 7.2917 + <title><literal role="hg-ext">notify</literal>&emdash;send email 7.2918 + notifications</title> 7.2919 + 7.2920 + <para id="x_26a">Although Mercurial's built-in web server provides RSS 7.2921 + feeds of changes in every repository, many people prefer to 7.2922 + receive change notifications via email. The <literal 7.2923 + role="hg-ext">notify</literal> hook lets you send out 7.2924 + notifications to a set of email addresses whenever changesets 7.2925 + arrive that those subscribers are interested in. 7.2926 + </para> 7.2927 + 7.2928 + <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> 7.2929 + hook, the <literal role="hg-ext">notify</literal> hook is 7.2930 + template-driven, so you can customise the contents of the 7.2931 + notification messages that it sends. 7.2932 + </para> 7.2933 + 7.2934 + <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> 7.2935 + hook includes a diff of every changeset that it sends out; you 7.2936 + can limit the size of the diff, or turn this feature off 7.2937 + entirely. It is useful for letting subscribers review changes 7.2938 + immediately, rather than clicking to follow a URL. 7.2939 + </para> 7.2940 + 7.2941 + <sect3> 7.2942 + <title>Configuring the <literal role="hg-ext">notify</literal> 7.2943 + hook</title> 7.2944 + 7.2945 + <para id="x_26d">You can set up the <literal 7.2946 + role="hg-ext">notify</literal> hook to send one email 7.2947 + message per incoming changeset, or one per incoming group of 7.2948 + changesets (all those that arrived in a single pull or 7.2949 + push). 7.2950 + </para> 7.2951 + <programlisting>[hooks] 7.2952 +# send one email per group of changes 7.2953 +changegroup.notify = python:hgext.notify.hook 7.2954 +# send one email per change 7.2955 +incoming.notify = python:hgext.notify.hook</programlisting> 7.2956 + 7.2957 + <para id="x_26e">Configuration information for this hook lives in the 7.2958 + <literal role="rc-notify">notify</literal> section of a 7.2959 + <filename role="special">~/.hgrc</filename> file. 7.2960 + </para> 7.2961 + <itemizedlist> 7.2962 + <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: 7.2963 + By default, this hook does not send out email at all; 7.2964 + instead, it prints the message that it 7.2965 + <emphasis>would</emphasis> send. Set this item to 7.2966 + <literal>false</literal> to allow email to be sent. The 7.2967 + reason that sending of email is turned off by default is 7.2968 + that it takes several tries to configure this extension 7.2969 + exactly as you would like, and it would be bad form to 7.2970 + spam subscribers with a number of <quote>broken</quote> 7.2971 + notifications while you debug your configuration. 7.2972 + </para> 7.2973 + </listitem> 7.2974 + <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: 7.2975 + The path to a configuration file that contains 7.2976 + subscription information. This is kept separate from 7.2977 + the main <filename role="special">~/.hgrc</filename> so 7.2978 + that you can maintain it in a repository of its own. 7.2979 + People can then clone that repository, update their 7.2980 + subscriptions, and push the changes back to your server. 7.2981 + </para> 7.2982 + </listitem> 7.2983 + <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: 7.2984 + The number of leading path separator characters to strip 7.2985 + from a repository's path, when deciding whether a 7.2986 + repository has subscribers. For example, if the 7.2987 + repositories on your server live in <filename 7.2988 + class="directory">/home/hg/repos</filename>, and 7.2989 + <literal role="hg-ext">notify</literal> is considering a 7.2990 + repository named <filename 7.2991 + class="directory">/home/hg/repos/shared/test</filename>, 7.2992 + setting <envar role="rc-item-notify">strip</envar> to 7.2993 + <literal>4</literal> will cause <literal 7.2994 + role="hg-ext">notify</literal> to trim the path it 7.2995 + considers down to <filename 7.2996 + class="directory">shared/test</filename>, and it will 7.2997 + match subscribers against that. 7.2998 + </para> 7.2999 + </listitem> 7.3000 + <listitem><para id="x_272"><envar 7.3001 + role="rc-item-notify">template</envar>: The template 7.3002 + text to use when sending messages. This specifies both 7.3003 + the contents of the message header and its body. 7.3004 + </para> 7.3005 + </listitem> 7.3006 + <listitem><para id="x_273"><envar 7.3007 + role="rc-item-notify">maxdiff</envar>: The maximum 7.3008 + number of lines of diff data to append to the end of a 7.3009 + message. If a diff is longer than this, it is 7.3010 + truncated. By default, this is set to 300. Set this to 7.3011 + <literal>0</literal> to omit diffs from notification 7.3012 + emails. 7.3013 + </para> 7.3014 + </listitem> 7.3015 + <listitem><para id="x_274"><envar 7.3016 + role="rc-item-notify">sources</envar>: A list of 7.3017 + sources of changesets to consider. This lets you limit 7.3018 + <literal role="hg-ext">notify</literal> to only sending 7.3019 + out email about changes that remote users pushed into 7.3020 + this repository via a server, for example. See 7.3021 + <xref linkend="sec:hook:sources"/> for the sources you 7.3022 + can specify here. 7.3023 + </para> 7.3024 + </listitem></itemizedlist> 7.3025 + 7.3026 + <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> 7.3027 + item in the <literal role="rc-web">web</literal> section, 7.3028 + you can use it in a template; it will be available as 7.3029 + <literal>webroot</literal>. 7.3030 + </para> 7.3031 + 7.3032 + <para id="x_276">Here is an example set of <literal 7.3033 + role="hg-ext">notify</literal> configuration information. 7.3034 + </para> 7.3035 + 7.3036 + &ch10-notify-config.lst; 7.3037 + 7.3038 + <para id="x_277">This will produce a message that looks like the 7.3039 + following: 7.3040 + </para> 7.3041 + 7.3042 + &ch10-notify-config-mail.lst; 7.3043 + 7.3044 + </sect3> 7.3045 + <sect3> 7.3046 + <title>Testing and troubleshooting</title> 7.3047 + 7.3048 + <para id="x_278">Do not forget that by default, the <literal 7.3049 + role="hg-ext">notify</literal> extension <emphasis>will not 7.3050 + send any mail</emphasis> until you explicitly configure it to do so, 7.3051 + by setting <envar role="rc-item-notify">test</envar> to 7.3052 + <literal>false</literal>. Until you do that, it simply 7.3053 + prints the message it <emphasis>would</emphasis> send. 7.3054 + </para> 7.3055 + 7.3056 + </sect3> 7.3057 + </sect2> 7.3058 + </sect1> 7.3059 + <sect1 id="sec:hook:ref"> 7.3060 + <title>Information for writers of hooks</title> 7.3061 + 7.3062 + <sect2> 7.3063 + <title>In-process hook execution</title> 7.3064 + 7.3065 + <para id="x_279">An in-process hook is called with arguments of the 7.3066 + following form: 7.3067 + </para> 7.3068 + <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> 7.3069 + <para id="x_27a">The <literal>ui</literal> parameter is a <literal 7.3070 + role="py-mod-mercurial.ui">ui</literal> object. The 7.3071 + <literal>repo</literal> parameter is a <literal 7.3072 + role="py-mod-mercurial.localrepo">localrepository</literal> 7.3073 + object. The names and values of the 7.3074 + <literal>**kwargs</literal> parameters depend on the hook 7.3075 + being invoked, with the following common features: 7.3076 + </para> 7.3077 + <itemizedlist> 7.3078 + <listitem><para id="x_27b">If a parameter is named 7.3079 + <literal>node</literal> or <literal>parentN</literal>, it 7.3080 + will contain a hexadecimal changeset ID. The empty string 7.3081 + is used to represent <quote>null changeset ID</quote> 7.3082 + instead of a string of zeroes. 7.3083 + </para> 7.3084 + </listitem> 7.3085 + <listitem><para id="x_27c">If a parameter is named 7.3086 + <literal>url</literal>, it will contain the URL of a 7.3087 + remote repository, if that can be determined. 7.3088 + </para> 7.3089 + </listitem> 7.3090 + <listitem><para id="x_27d">Boolean-valued parameters are represented as 7.3091 + Python <literal>bool</literal> objects. 7.3092 + </para> 7.3093 + </listitem></itemizedlist> 7.3094 + 7.3095 + <para id="x_27e">An in-process hook is called without a change to the 7.3096 + process's working directory (unlike external hooks, which are 7.3097 + run in the root of the repository). It must not change the 7.3098 + process's working directory, or it will cause any calls it 7.3099 + makes into the Mercurial API to fail. 7.3100 + </para> 7.3101 + 7.3102 + <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it 7.3103 + is considered to have succeeded. If it returns a boolean 7.3104 + <quote>true</quote> value or raises an exception, it is 7.3105 + considered to have failed. A useful way to think of the 7.3106 + calling convention is <quote>tell me if you fail</quote>. 7.3107 + </para> 7.3108 + 7.3109 + <para id="x_280">Note that changeset IDs are passed into Python hooks as 7.3110 + hexadecimal strings, not the binary hashes that Mercurial's 7.3111 + APIs normally use. To convert a hash from hex to binary, use 7.3112 + the <literal>bin</literal> function. 7.3113 + </para> 7.3114 + </sect2> 7.3115 + 7.3116 + <sect2> 7.3117 + <title>External hook execution</title> 7.3118 + 7.3119 + <para id="x_281">An external hook is passed to the shell of the user 7.3120 + running Mercurial. Features of that shell, such as variable 7.3121 + substitution and command redirection, are available. The hook 7.3122 + is run in the root directory of the repository (unlike 7.3123 + in-process hooks, which are run in the same directory that 7.3124 + Mercurial was run in). 7.3125 + </para> 7.3126 + 7.3127 + <para id="x_282">Hook parameters are passed to the hook as environment 7.3128 + variables. Each environment variable's name is converted in 7.3129 + upper case and prefixed with the string 7.3130 + <quote><literal>HG_</literal></quote>. For example, if the 7.3131 + name of a parameter is <quote><literal>node</literal></quote>, 7.3132 + the name of the environment variable representing that 7.3133 + parameter will be <quote><literal>HG_NODE</literal></quote>. 7.3134 + </para> 7.3135 + 7.3136 + <para id="x_283">A boolean parameter is represented as the string 7.3137 + <quote><literal>1</literal></quote> for <quote>true</quote>, 7.3138 + <quote><literal>0</literal></quote> for <quote>false</quote>. 7.3139 + If an environment variable is named <envar>HG_NODE</envar>, 7.3140 + <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 7.3141 + contains a changeset ID represented as a hexadecimal string. 7.3142 + The empty string is used to represent <quote>null changeset 7.3143 + ID</quote> instead of a string of zeroes. If an environment 7.3144 + variable is named <envar>HG_URL</envar>, it will contain the 7.3145 + URL of a remote repository, if that can be determined. 7.3146 + </para> 7.3147 + 7.3148 + <para id="x_284">If a hook exits with a status of zero, it is considered to 7.3149 + have succeeded. If it exits with a non-zero status, it is 7.3150 + considered to have failed. 7.3151 + </para> 7.3152 + </sect2> 7.3153 + 7.3154 + <sect2> 7.3155 + <title>Finding out where changesets come from</title> 7.3156 + 7.3157 + <para id="x_285">A hook that involves the transfer of changesets between a 7.3158 + local repository and another may be able to find out 7.3159 + information about the <quote>far side</quote>. Mercurial 7.3160 + knows <emphasis>how</emphasis> changes are being transferred, 7.3161 + and in many cases <emphasis>where</emphasis> they are being 7.3162 + transferred to or from. 7.3163 + </para> 7.3164 + 7.3165 + <sect3 id="sec:hook:sources"> 7.3166 + <title>Sources of changesets</title> 7.3167 + 7.3168 + <para id="x_286">Mercurial will tell a hook what means are, or were, used 7.3169 + to transfer changesets between repositories. This is 7.3170 + provided by Mercurial in a Python parameter named 7.3171 + <literal>source</literal>, or an environment variable named 7.3172 + <envar>HG_SOURCE</envar>. 7.3173 + </para> 7.3174 + 7.3175 + <itemizedlist> 7.3176 + <listitem><para id="x_287"><literal>serve</literal>: Changesets are 7.3177 + transferred to or from a remote repository over http or 7.3178 + ssh. 7.3179 + </para> 7.3180 + </listitem> 7.3181 + <listitem><para id="x_288"><literal>pull</literal>: Changesets are 7.3182 + being transferred via a pull from one repository into 7.3183 + another. 7.3184 + </para> 7.3185 + </listitem> 7.3186 + <listitem><para id="x_289"><literal>push</literal>: Changesets are 7.3187 + being transferred via a push from one repository into 7.3188 + another. 7.3189 + </para> 7.3190 + </listitem> 7.3191 + <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are 7.3192 + being transferred to or from a bundle. 7.3193 + </para> 7.3194 + </listitem></itemizedlist> 7.3195 + </sect3> 7.3196 + 7.3197 + <sect3 id="sec:hook:url"> 7.3198 + <title>Where changes are going&emdash;remote repository 7.3199 + URLs</title> 7.3200 + 7.3201 + <para id="x_28b">When possible, Mercurial will tell a hook the location 7.3202 + of the <quote>far side</quote> of an activity that transfers 7.3203 + changeset data between repositories. This is provided by 7.3204 + Mercurial in a Python parameter named 7.3205 + <literal>url</literal>, or an environment variable named 7.3206 + <envar>HG_URL</envar>. 7.3207 + </para> 7.3208 + 7.3209 + <para id="x_28c">This information is not always known. If a hook is 7.3210 + invoked in a repository that is being served via http or 7.3211 + ssh, Mercurial cannot tell where the remote repository is, 7.3212 + but it may know where the client is connecting from. In 7.3213 + such cases, the URL will take one of the following forms: 7.3214 + </para> 7.3215 + <itemizedlist> 7.3216 + <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 7.3217 + ssh client, at the IP address 7.3218 + <literal>1.2.3.4</literal>. 7.3219 + </para> 7.3220 + </listitem> 7.3221 + <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 7.3222 + http client, at the IP address 7.3223 + <literal>1.2.3.4</literal>. If the client is using SSL, 7.3224 + this will be of the form 7.3225 + <literal>remote:https:1.2.3.4</literal>. 7.3226 + </para> 7.3227 + </listitem> 7.3228 + <listitem><para id="x_28f">Empty&emdash;no information could be 7.3229 + discovered about the remote client. 7.3230 + </para> 7.3231 + </listitem></itemizedlist> 7.3232 + </sect3> 7.3233 + </sect2> 7.3234 + </sect1> 7.3235 + <sect1> 7.3236 + <title>Hook reference</title> 7.3237 + 7.3238 + <sect2 id="sec:hook:changegroup"> 7.3239 + <title><literal role="hook">changegroup</literal>&emdash;after 7.3240 + remote changesets added</title> 7.3241 + 7.3242 + <para id="x_290">This hook is run after a group of pre-existing changesets 7.3243 + has been added to the repository, for example via a <command 7.3244 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 7.3245 + unbundle</command>. This hook is run once per operation 7.3246 + that added one or more changesets. This is in contrast to the 7.3247 + <literal role="hook">incoming</literal> hook, which is run 7.3248 + once per changeset, regardless of whether the changesets 7.3249 + arrive in a group. 7.3250 + </para> 7.3251 + 7.3252 + <para id="x_291">Some possible uses for this hook include kicking off an 7.3253 + automated build or test of the added changesets, updating a 7.3254 + bug database, or notifying subscribers that a repository 7.3255 + contains new changes. 7.3256 + </para> 7.3257 + 7.3258 + <para id="x_292">Parameters to this hook: 7.3259 + </para> 7.3260 + <itemizedlist> 7.3261 + <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The 7.3262 + changeset ID of the first changeset in the group that was 7.3263 + added. All changesets between this and 7.3264 + <literal role="tag">tip</literal>, inclusive, were added by a single 7.3265 + <command role="hg-cmd">hg pull</command>, <command 7.3266 + role="hg-cmd">hg push</command> or <command 7.3267 + role="hg-cmd">hg unbundle</command>. 7.3268 + </para> 7.3269 + </listitem> 7.3270 + <listitem><para id="x_294"><literal>source</literal>: A 7.3271 + string. The source of these changes. See <xref 7.3272 + linkend="sec:hook:sources"/> for details. 7.3273 + </para> 7.3274 + </listitem> 7.3275 + <listitem><para id="x_295"><literal>url</literal>: A URL. The 7.3276 + location of the remote repository, if known. See <xref 7.3277 + linkend="sec:hook:url"/> for more information. 7.3278 + </para> 7.3279 + </listitem></itemizedlist> 7.3280 + 7.3281 + <para id="x_296">See also: <literal 7.3282 + role="hook">incoming</literal> (<xref 7.3283 + linkend="sec:hook:incoming"/>), <literal 7.3284 + role="hook">prechangegroup</literal> (<xref 7.3285 + linkend="sec:hook:prechangegroup"/>), <literal 7.3286 + role="hook">pretxnchangegroup</literal> (<xref 7.3287 + linkend="sec:hook:pretxnchangegroup"/>) 7.3288 + </para> 7.3289 + </sect2> 7.3290 + 7.3291 + <sect2 id="sec:hook:commit"> 7.3292 + <title><literal role="hook">commit</literal>&emdash;after a new 7.3293 + changeset is created</title> 7.3294 + 7.3295 + <para id="x_297">This hook is run after a new changeset has been created. 7.3296 + </para> 7.3297 + 7.3298 + <para id="x_298">Parameters to this hook: 7.3299 + </para> 7.3300 + <itemizedlist> 7.3301 + <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The 7.3302 + changeset ID of the newly committed changeset. 7.3303 + </para> 7.3304 + </listitem> 7.3305 + <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. 7.3306 + The changeset ID of the first parent of the newly 7.3307 + committed changeset. 7.3308 + </para> 7.3309 + </listitem> 7.3310 + <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. 7.3311 + The changeset ID of the second parent of the newly 7.3312 + committed changeset. 7.3313 + </para> 7.3314 + </listitem></itemizedlist> 7.3315 + 7.3316 + <para id="x_29c">See also: <literal 7.3317 + role="hook">precommit</literal> (<xref 7.3318 + linkend="sec:hook:precommit"/>), <literal 7.3319 + role="hook">pretxncommit</literal> (<xref 7.3320 + linkend="sec:hook:pretxncommit"/>) 7.3321 + </para> 7.3322 + </sect2> 7.3323 + 7.3324 + <sect2 id="sec:hook:incoming"> 7.3325 + <title><literal role="hook">incoming</literal>&emdash;after one 7.3326 + remote changeset is added</title> 7.3327 + 7.3328 + <para id="x_29d">This hook is run after a pre-existing changeset has been 7.3329 + added to the repository, for example via a <command 7.3330 + role="hg-cmd">hg push</command>. If a group of changesets 7.3331 + was added in a single operation, this hook is called once for 7.3332 + each added changeset. 7.3333 + </para> 7.3334 + 7.3335 + <para id="x_29e">You can use this hook for the same purposes as 7.3336 + the <literal role="hook">changegroup</literal> hook (<xref 7.3337 + linkend="sec:hook:changegroup"/>); it's simply more 7.3338 + convenient sometimes to run a hook once per group of 7.3339 + changesets, while other times it's handier once per changeset. 7.3340 + </para> 7.3341 + 7.3342 + <para id="x_29f">Parameters to this hook: 7.3343 + </para> 7.3344 + <itemizedlist> 7.3345 + <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The 7.3346 + ID of the newly added changeset. 7.3347 + </para> 7.3348 + </listitem> 7.3349 + <listitem><para id="x_2a1"><literal>source</literal>: A 7.3350 + string. The source of these changes. See <xref 7.3351 + linkend="sec:hook:sources"/> for details. 7.3352 + </para> 7.3353 + </listitem> 7.3354 + <listitem><para id="x_2a2"><literal>url</literal>: A URL. The 7.3355 + location of the remote repository, if known. See <xref 7.3356 + linkend="sec:hook:url"/> for more information. 7.3357 + </para> 7.3358 + </listitem></itemizedlist> 7.3359 + 7.3360 + <para id="x_2a3">See also: <literal 7.3361 + role="hook">changegroup</literal> (<xref 7.3362 + linkend="sec:hook:changegroup"/>) <literal 7.3363 + role="hook">prechangegroup</literal> (<xref 7.3364 + linkend="sec:hook:prechangegroup"/>), <literal 7.3365 + role="hook">pretxnchangegroup</literal> (<xref 7.3366 + linkend="sec:hook:pretxnchangegroup"/>) 7.3367 + </para> 7.3368 + </sect2> 7.3369 + 7.3370 + <sect2 id="sec:hook:outgoing"> 7.3371 + <title><literal role="hook">outgoing</literal>&emdash;after 7.3372 + changesets are propagated</title> 7.3373 + 7.3374 + <para id="x_2a4">This hook is run after a group of changesets has been 7.3375 + propagated out of this repository, for example by a <command 7.3376 + role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 7.3377 + bundle</command> command. 7.3378 + </para> 7.3379 + 7.3380 + <para id="x_2a5">One possible use for this hook is to notify administrators 7.3381 + that changes have been pulled. 7.3382 + </para> 7.3383 + 7.3384 + <para id="x_2a6">Parameters to this hook: 7.3385 + </para> 7.3386 + <itemizedlist> 7.3387 + <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The 7.3388 + changeset ID of the first changeset of the group that was 7.3389 + sent. 7.3390 + </para> 7.3391 + </listitem> 7.3392 + <listitem><para id="x_2a8"><literal>source</literal>: A string. The 7.3393 + source of the of the operation (see <xref 7.3394 + linkend="sec:hook:sources"/>). If a remote 7.3395 + client pulled changes from this repository, 7.3396 + <literal>source</literal> will be 7.3397 + <literal>serve</literal>. If the client that obtained 7.3398 + changes from this repository was local, 7.3399 + <literal>source</literal> will be 7.3400 + <literal>bundle</literal>, <literal>pull</literal>, or 7.3401 + <literal>push</literal>, depending on the operation the 7.3402 + client performed. 7.3403 + </para> 7.3404 + </listitem> 7.3405 + <listitem><para id="x_2a9"><literal>url</literal>: A URL. The 7.3406 + location of the remote repository, if known. See <xref 7.3407 + linkend="sec:hook:url"/> for more information. 7.3408 + </para> 7.3409 + </listitem></itemizedlist> 7.3410 + 7.3411 + <para id="x_2aa">See also: <literal 7.3412 + role="hook">preoutgoing</literal> (<xref 7.3413 + linkend="sec:hook:preoutgoing"/>) 7.3414 + </para> 7.3415 + </sect2> 7.3416 + 7.3417 + <sect2 id="sec:hook:prechangegroup"> 7.3418 + <title><literal 7.3419 + role="hook">prechangegroup</literal>&emdash;before starting 7.3420 + to add remote changesets</title> 7.3421 + 7.3422 + <para id="x_2ab">This controlling hook is run before Mercurial begins to 7.3423 + add a group of changesets from another repository. 7.3424 + </para> 7.3425 + 7.3426 + <para id="x_2ac">This hook does not have any information about the 7.3427 + changesets to be added, because it is run before transmission 7.3428 + of those changesets is allowed to begin. If this hook fails, 7.3429 + the changesets will not be transmitted. 7.3430 + </para> 7.3431 + 7.3432 + <para id="x_2ad">One use for this hook is to prevent external changes from 7.3433 + being added to a repository. For example, you could use this 7.3434 + to <quote>freeze</quote> a server-hosted branch temporarily or 7.3435 + permanently so that users cannot push to it, while still 7.3436 + allowing a local administrator to modify the repository. 7.3437 + </para> 7.3438 + 7.3439 + <para id="x_2ae">Parameters to this hook: 7.3440 + </para> 7.3441 + <itemizedlist> 7.3442 + <listitem><para id="x_2af"><literal>source</literal>: A string. The 7.3443 + source of these changes. See <xref 7.3444 + linkend="sec:hook:sources"/> for details. 7.3445 + </para> 7.3446 + </listitem> 7.3447 + <listitem><para id="x_2b0"><literal>url</literal>: A URL. The 7.3448 + location of the remote repository, if known. See <xref 7.3449 + linkend="sec:hook:url"/> for more information. 7.3450 + </para> 7.3451 + </listitem></itemizedlist> 7.3452 + 7.3453 + <para id="x_2b1">See also: <literal 7.3454 + role="hook">changegroup</literal> (<xref 7.3455 + linkend="sec:hook:changegroup"/>), <literal 7.3456 + role="hook">incoming</literal> (<xref 7.3457 + linkend="sec:hook:incoming"/>), <literal 7.3458 + role="hook">pretxnchangegroup</literal> (<xref 7.3459 + linkend="sec:hook:pretxnchangegroup"/>) 7.3460 + </para> 7.3461 + </sect2> 7.3462 + 7.3463 + <sect2 id="sec:hook:precommit"> 7.3464 + <title><literal role="hook">precommit</literal>&emdash;before 7.3465 + starting to commit a changeset</title> 7.3466 + 7.3467 + <para id="x_2b2">This hook is run before Mercurial begins to commit a new 7.3468 + changeset. It is run before Mercurial has any of the metadata 7.3469 + for the commit, such as the files to be committed, the commit 7.3470 + message, or the commit date. 7.3471 + </para> 7.3472 + 7.3473 + <para id="x_2b3">One use for this hook is to disable the ability to commit 7.3474 + new changesets, while still allowing incoming changesets. 7.3475 + Another is to run a build or test, and only allow the commit 7.3476 + to begin if the build or test succeeds. 7.3477 + </para> 7.3478 + 7.3479 + <para id="x_2b4">Parameters to this hook: 7.3480 + </para> 7.3481 + <itemizedlist> 7.3482 + <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. 7.3483 + The changeset ID of the first parent of the working 7.3484 + directory. 7.3485 + </para> 7.3486 + </listitem> 7.3487 + <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. 7.3488 + The changeset ID of the second parent of the working 7.3489 + directory. 7.3490 + </para> 7.3491 + </listitem></itemizedlist> 7.3492 + <para id="x_2b7">If the commit proceeds, the parents of the working 7.3493 + directory will become the parents of the new changeset. 7.3494 + </para> 7.3495 + 7.3496 + <para id="x_2b8">See also: <literal role="hook">commit</literal> 7.3497 + (<xref linkend="sec:hook:commit"/>), <literal 7.3498 + role="hook">pretxncommit</literal> (<xref 7.3499 + linkend="sec:hook:pretxncommit"/>) 7.3500 + </para> 7.3501 + </sect2> 7.3502 + 7.3503 + <sect2 id="sec:hook:preoutgoing"> 7.3504 + <title><literal role="hook">preoutgoing</literal>&emdash;before 7.3505 + starting to propagate changesets</title> 7.3506 + 7.3507 + <para id="x_2b9">This hook is invoked before Mercurial knows the identities 7.3508 + of the changesets to be transmitted. 7.3509 + </para> 7.3510 + 7.3511 + <para id="x_2ba">One use for this hook is to prevent changes from being 7.3512 + transmitted to another repository. 7.3513 + </para> 7.3514 + 7.3515 + <para id="x_2bb">Parameters to this hook: 7.3516 + </para> 7.3517 + <itemizedlist> 7.3518 + <listitem><para id="x_2bc"><literal>source</literal>: A 7.3519 + string. The source of the operation that is attempting to 7.3520 + obtain changes from this repository (see <xref 7.3521 + linkend="sec:hook:sources"/>). See the documentation 7.3522 + for the <literal>source</literal> parameter to the 7.3523 + <literal role="hook">outgoing</literal> hook, in 7.3524 + <xref linkend="sec:hook:outgoing"/>, for possible values 7.3525 + of this parameter. 7.3526 + </para> 7.3527 + </listitem> 7.3528 + <listitem><para id="x_2bd"><literal>url</literal>: A URL. The 7.3529 + location of the remote repository, if known. See <xref 7.3530 + linkend="sec:hook:url"/> for more information. 7.3531 + </para> 7.3532 + </listitem></itemizedlist> 7.3533 + 7.3534 + <para id="x_2be">See also: <literal 7.3535 + role="hook">outgoing</literal> (<xref 7.3536 + linkend="sec:hook:outgoing"/>) 7.3537 + </para> 7.3538 + </sect2> 7.3539 + 7.3540 + <sect2 id="sec:hook:pretag"> 7.3541 + <title><literal role="hook">pretag</literal>&emdash;before 7.3542 + tagging a changeset</title> 7.3543 + 7.3544 + <para id="x_2bf">This controlling hook is run before a tag is created. If 7.3545 + the hook succeeds, creation of the tag proceeds. If the hook 7.3546 + fails, the tag is not created. 7.3547 + </para> 7.3548 + 7.3549 + <para id="x_2c0">Parameters to this hook: 7.3550 + </para> 7.3551 + <itemizedlist> 7.3552 + <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether 7.3553 + the tag is local to this repository instance (i.e. stored 7.3554 + in <filename role="special">.hg/localtags</filename>) or 7.3555 + managed by Mercurial (stored in <filename 7.3556 + role="special">.hgtags</filename>). 7.3557 + </para> 7.3558 + </listitem> 7.3559 + <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The 7.3560 + ID of the changeset to be tagged. 7.3561 + </para> 7.3562 + </listitem> 7.3563 + <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of 7.3564 + the tag to be created. 7.3565 + </para> 7.3566 + </listitem></itemizedlist> 7.3567 + 7.3568 + <para id="x_2c4">If the tag to be created is 7.3569 + revision-controlled, the <literal 7.3570 + role="hook">precommit</literal> and <literal 7.3571 + role="hook">pretxncommit</literal> hooks (<xref 7.3572 + linkend="sec:hook:commit"/> and <xref 7.3573 + linkend="sec:hook:pretxncommit"/>) will also be run. 7.3574 + </para> 7.3575 + 7.3576 + <para id="x_2c5">See also: <literal role="hook">tag</literal> 7.3577 + (<xref linkend="sec:hook:tag"/>) 7.3578 + </para> 7.3579 + </sect2> 7.3580 + 7.3581 + <sect2 id="sec:hook:pretxnchangegroup"> 7.3582 + <title><literal 7.3583 + role="hook">pretxnchangegroup</literal>&emdash;before 7.3584 + completing addition of remote changesets</title> 7.3585 + 7.3586 + <para id="x_2c6">This controlling hook is run before a 7.3587 + transaction&emdash;that manages the addition of a group of new 7.3588 + changesets from outside the repository&emdash;completes. If 7.3589 + the hook succeeds, the transaction completes, and all of the 7.3590 + changesets become permanent within this repository. If the 7.3591 + hook fails, the transaction is rolled back, and the data for 7.3592 + the changesets is erased. 7.3593 + </para> 7.3594 + 7.3595 + <para id="x_2c7">This hook can access the metadata associated with the 7.3596 + almost-added changesets, but it should not do anything 7.3597 + permanent with this data. It must also not modify the working 7.3598 + directory. 7.3599 + </para> 7.3600 + 7.3601 + <para id="x_2c8">While this hook is running, if other Mercurial processes 7.3602 + access this repository, they will be able to see the 7.3603 + almost-added changesets as if they are permanent. This may 7.3604 + lead to race conditions if you do not take steps to avoid 7.3605 + them. 7.3606 + </para> 7.3607 + 7.3608 + <para id="x_2c9">This hook can be used to automatically vet a group of 7.3609 + changesets. If the hook fails, all of the changesets are 7.3610 + <quote>rejected</quote> when the transaction rolls back. 7.3611 + </para> 7.3612 + 7.3613 + <para id="x_2ca">Parameters to this hook: 7.3614 + </para> 7.3615 + <itemizedlist> 7.3616 + <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The 7.3617 + changeset ID of the first changeset in the group that was 7.3618 + added. All changesets between this and 7.3619 + <literal role="tag">tip</literal>, 7.3620 + inclusive, were added by a single <command 7.3621 + role="hg-cmd">hg pull</command>, <command 7.3622 + role="hg-cmd">hg push</command> or <command 7.3623 + role="hg-cmd">hg unbundle</command>. 7.3624 + </para> 7.3625 + </listitem> 7.3626 + <listitem><para id="x_2cc"><literal>source</literal>: A 7.3627 + string. The source of these changes. See <xref 7.3628 + linkend="sec:hook:sources"/> for details. 7.3629 + </para> 7.3630 + </listitem> 7.3631 + <listitem><para id="x_2cd"><literal>url</literal>: A URL. The 7.3632 + location of the remote repository, if known. See <xref 7.3633 + linkend="sec:hook:url"/> for more information. 7.3634 + </para> 7.3635 + </listitem></itemizedlist> 7.3636 + 7.3637 + <para id="x_2ce">See also: <literal 7.3638 + role="hook">changegroup</literal> (<xref 7.3639 + linkend="sec:hook:changegroup"/>), <literal 7.3640 + role="hook">incoming</literal> (<xref 7.3641 + linkend="sec:hook:incoming"/>), <literal 7.3642 + role="hook">prechangegroup</literal> (<xref 7.3643 + linkend="sec:hook:prechangegroup"/>) 7.3644 + </para> 7.3645 + </sect2> 7.3646 + 7.3647 + <sect2 id="sec:hook:pretxncommit"> 7.3648 + <title><literal role="hook">pretxncommit</literal>&emdash;before 7.3649 + completing commit of new changeset</title> 7.3650 + 7.3651 + <para id="x_2cf">This controlling hook is run before a 7.3652 + transaction&emdash;that manages a new commit&emdash;completes. 7.3653 + If the hook succeeds, the transaction completes and the 7.3654 + changeset becomes permanent within this repository. If the 7.3655 + hook fails, the transaction is rolled back, and the commit 7.3656 + data is erased. 7.3657 + </para> 7.3658 + 7.3659 + <para id="x_2d0">This hook can access the metadata associated with the 7.3660 + almost-new changeset, but it should not do anything permanent 7.3661 + with this data. It must also not modify the working 7.3662 + directory. 7.3663 + </para> 7.3664 + 7.3665 + <para id="x_2d1">While this hook is running, if other Mercurial processes 7.3666 + access this repository, they will be able to see the 7.3667 + almost-new changeset as if it is permanent. This may lead to 7.3668 + race conditions if you do not take steps to avoid them. 7.3669 + </para> 7.3670 + 7.3671 + <para id="x_2d2">Parameters to this hook:</para> 7.3672 + 7.3673 + <itemizedlist> 7.3674 + <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 7.3675 + changeset ID of the newly committed changeset. 7.3676 + </para> 7.3677 + </listitem> 7.3678 + <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. 7.3679 + The changeset ID of the first parent of the newly 7.3680 + committed changeset. 7.3681 + </para> 7.3682 + </listitem> 7.3683 + <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. 7.3684 + The changeset ID of the second parent of the newly 7.3685 + committed changeset. 7.3686 + </para> 7.3687 + </listitem></itemizedlist> 7.3688 + 7.3689 + <para id="x_2d6">See also: <literal 7.3690 + role="hook">precommit</literal> (<xref 7.3691 + linkend="sec:hook:precommit"/>) 7.3692 + </para> 7.3693 + </sect2> 7.3694 + 7.3695 + <sect2 id="sec:hook:preupdate"> 7.3696 + <title><literal role="hook">preupdate</literal>&emdash;before 7.3697 + updating or merging working directory</title> 7.3698 + 7.3699 + <para id="x_2d7">This controlling hook is run before an update 7.3700 + or merge of the working directory begins. It is run only if 7.3701 + Mercurial's normal pre-update checks determine that the update 7.3702 + or merge can proceed. If the hook succeeds, the update or 7.3703 + merge may proceed; if it fails, the update or merge does not 7.3704 + start. 7.3705 + </para> 7.3706 + 7.3707 + <para id="x_2d8">Parameters to this hook: 7.3708 + </para> 7.3709 + <itemizedlist> 7.3710 + <listitem><para id="x_2d9"><literal>parent1</literal>: A 7.3711 + changeset ID. The ID of the parent that the working 7.3712 + directory is to be updated to. If the working directory 7.3713 + is being merged, it will not change this parent. 7.3714 + </para> 7.3715 + </listitem> 7.3716 + <listitem><para id="x_2da"><literal>parent2</literal>: A 7.3717 + changeset ID. Only set if the working directory is being 7.3718 + merged. The ID of the revision that the working directory 7.3719 + is being merged with. 7.3720 + </para> 7.3721 + </listitem></itemizedlist> 7.3722 + 7.3723 + <para id="x_2db">See also: <literal role="hook">update</literal> 7.3724 + (<xref linkend="sec:hook:update"/>)</para> 7.3725 + </sect2> 7.3726 + 7.3727 + <sect2 id="sec:hook:tag"> 7.3728 + <title><literal role="hook">tag</literal>&emdash;after tagging a 7.3729 + changeset</title> 7.3730 + 7.3731 + <para id="x_2dc">This hook is run after a tag has been created. 7.3732 + </para> 7.3733 + 7.3734 + <para id="x_2dd">Parameters to this hook: 7.3735 + </para> 7.3736 + <itemizedlist> 7.3737 + <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether 7.3738 + the new tag is local to this repository instance (i.e. 7.3739 + stored in <filename 7.3740 + role="special">.hg/localtags</filename>) or managed by 7.3741 + Mercurial (stored in <filename 7.3742 + role="special">.hgtags</filename>). 7.3743 + </para> 7.3744 + </listitem> 7.3745 + <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The 7.3746 + ID of the changeset that was tagged. 7.3747 + </para> 7.3748 + </listitem> 7.3749 + <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of 7.3750 + the tag that was created. 7.3751 + </para> 7.3752 + </listitem></itemizedlist> 7.3753 + 7.3754 + <para id="x_2e1">If the created tag is revision-controlled, the <literal 7.3755 + role="hook">commit</literal> hook (section <xref 7.3756 + linkend="sec:hook:commit"/>) is run before this hook. 7.3757 + </para> 7.3758 + 7.3759 + <para id="x_2e2">See also: <literal role="hook">pretag</literal> 7.3760 + (<xref linkend="sec:hook:pretag"/>) 7.3761 + </para> 7.3762 + </sect2> 7.3763 + 7.3764 + <sect2 id="sec:hook:update"> 7.3765 + <title><literal role="hook">update</literal>&emdash;after 7.3766 + updating or merging working directory</title> 7.3767 + 7.3768 + <para id="x_2e3">This hook is run after an update or merge of the working 7.3769 + directory completes. Since a merge can fail (if the external 7.3770 + <command>hgmerge</command> command fails to resolve conflicts 7.3771 + in a file), this hook communicates whether the update or merge 7.3772 + completed cleanly. 7.3773 + </para> 7.3774 + 7.3775 + <itemizedlist> 7.3776 + <listitem><para id="x_2e4"><literal>error</literal>: A boolean. 7.3777 + Indicates whether the update or merge completed 7.3778 + successfully. 7.3779 + </para> 7.3780 + </listitem> 7.3781 + <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. 7.3782 + The ID of the parent that the working directory was 7.3783 + updated to. If the working directory was merged, it will 7.3784 + not have changed this parent. 7.3785 + </para> 7.3786 + </listitem> 7.3787 + <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. 7.3788 + Only set if the working directory was merged. The ID of 7.3789 + the revision that the working directory was merged with. 7.3790 + </para> 7.3791 + </listitem></itemizedlist> 7.3792 + 7.3793 + <para id="x_2e7">See also: <literal role="hook">preupdate</literal> 7.3794 + (<xref linkend="sec:hook:preupdate"/>) 7.3795 + </para> 7.3796 + 7.3797 + </sect2> 7.3798 + </sect1> 7.3799 </chapter> 7.3800 7.3801 <!-- 7.3802 local variables: 7.3803 sgml-parent-document: ("00book.xml" "book" "chapter") 7.3804 end: 7.3805 ---> 7.3806 \ No newline at end of file 7.3807 +-->
8.1 --- a/fr/ch11-template.xml Wed Sep 09 15:25:09 2009 +0200 8.2 +++ b/fr/ch11-template.xml Wed Sep 09 16:07:36 2009 +0200 8.3 @@ -1,689 +1,685 @@ 8.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 8.5 8.6 -<chapter> 8.7 -<title>Customising the output of Mercurial</title> 8.8 -<para>\label{chap:template}</para> 8.9 - 8.10 -<para>Mercurial provides a powerful mechanism to let you control how it 8.11 -displays information. The mechanism is based on templates. You can 8.12 -use templates to generate specific output for a single command, or to 8.13 -customise the entire appearance of the built-in web interface.</para> 8.14 - 8.15 -<sect1> 8.16 -<title>Using precanned output styles</title> 8.17 -<para>\label{sec:style}</para> 8.18 - 8.19 -<para>Packaged with Mercurial are some output styles that you can use 8.20 -immediately. A style is simply a precanned template that someone 8.21 -wrote and installed somewhere that Mercurial can find.</para> 8.22 - 8.23 -<para>Before we take a look at Mercurial's bundled styles, let's review its 8.24 -normal output.</para> 8.25 - 8.26 -<para><!-- &interaction.template.simple.normal; --></para> 8.27 - 8.28 -<para>This is somewhat informative, but it takes up a lot of space&emdash;five 8.29 -lines of output per changeset. The <literal>compact</literal> style reduces 8.30 -this to three lines, presented in a sparse manner.</para> 8.31 - 8.32 -<para><!-- &interaction.template.simple.compact; --></para> 8.33 - 8.34 -<para>The <literal>changelog</literal> style hints at the expressive power of 8.35 -Mercurial's templating engine. This style attempts to follow the GNU 8.36 -Project's changelog guidelines<citation>web:changelog</citation>. 8.37 -</para> 8.38 - 8.39 -<para><!-- &interaction.template.simple.changelog; --> 8.40 -</para> 8.41 - 8.42 -<para>You will not be shocked to learn that Mercurial's default output style 8.43 -is named <literal>default</literal>. 8.44 -</para> 8.45 - 8.46 -<sect2> 8.47 -<title>Setting a default style</title> 8.48 - 8.49 -<para>You can modify the output style that Mercurial will use for every 8.50 -command by editing your <filename role="special"> /.hgrc</filename>\ file, naming the style you would 8.51 -prefer to use. 8.52 -</para> 8.53 - 8.54 -<programlisting> 8.55 -<para> [ui] 8.56 - style = compact 8.57 -</para> 8.58 -</programlisting> 8.59 - 8.60 -<para>If you write a style of your own, you can use it by either providing 8.61 -the path to your style file, or copying your style file into a 8.62 -location where Mercurial can find it (typically the <literal>templates</literal> 8.63 -subdirectory of your Mercurial install directory). 8.64 -</para> 8.65 - 8.66 -</sect2> 8.67 -</sect1> 8.68 -<sect1> 8.69 -<title>Commands that support styles and templates</title> 8.70 - 8.71 -<para>All of Mercurial's <quote><literal>log</literal>-like</quote> commands let you use styles 8.72 -and templates: <command role="hg-cmd">hg incoming</command>, <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg outgoing</command>, and 8.73 -<command role="hg-cmd">hg tip</command>. 8.74 -</para> 8.75 - 8.76 -<para>As I write this manual, these are so far the only commands that 8.77 -support styles and templates. Since these are the most important 8.78 -commands that need customisable output, there has been little pressure 8.79 -from the Mercurial user community to add style and template support to 8.80 -other commands. 8.81 -</para> 8.82 - 8.83 -</sect1> 8.84 -<sect1> 8.85 -<title>The basics of templating</title> 8.86 - 8.87 -<para>At its simplest, a Mercurial template is a piece of text. Some of the 8.88 -text never changes, while other parts are <emphasis>expanded</emphasis>, or replaced 8.89 -with new text, when necessary. 8.90 -</para> 8.91 - 8.92 -<para>Before we continue, let's look again at a simple example of 8.93 -Mercurial's normal output. 8.94 -</para> 8.95 - 8.96 -<para><!-- &interaction.template.simple.normal; --> 8.97 -</para> 8.98 - 8.99 -<para>Now, let's run the same command, but using a template to change its 8.100 -output. 8.101 -</para> 8.102 - 8.103 -<para><!-- &interaction.template.simple.simplest; --> 8.104 -</para> 8.105 - 8.106 -<para>The example above illustrates the simplest possible template; it's 8.107 -just a piece of static text, printed once for each changeset. The 8.108 -<option role="hg-opt-log">--template</option> option to the <command role="hg-cmd">hg log</command> command tells 8.109 -Mercurial to use the given text as the template when printing each 8.110 -changeset. 8.111 -</para> 8.112 - 8.113 -<para>Notice that the template string above ends with the text 8.114 -<quote><literal>\n</literal></quote>. This is an <emphasis>escape sequence</emphasis>, telling Mercurial 8.115 -to print a newline at the end of each template item. If you omit this 8.116 -newline, Mercurial will run each piece of output together. See 8.117 -section <xref linkend="sec:template:escape"/> for more details of escape sequences. 8.118 -</para> 8.119 - 8.120 -<para>A template that prints a fixed string of text all the time isn't very 8.121 -useful; let's try something a bit more complex. 8.122 -</para> 8.123 - 8.124 -<para><!-- &interaction.template.simple.simplesub; --> 8.125 -</para> 8.126 - 8.127 -<para>As you can see, the string <quote><literal>{desc}</literal></quote> in the template has been 8.128 -replaced in the output with the description of each changeset. Every 8.129 -time Mercurial finds text enclosed in curly braces (<quote><literal>{</literal></quote> 8.130 -and <quote>\texttt{}}</quote>), it will try to replace the braces and text with 8.131 -the expansion of whatever is inside. To print a literal curly brace, 8.132 -you must escape it, as described in section <xref linkend="sec:template:escape"/>. 8.133 -</para> 8.134 - 8.135 -</sect1> 8.136 -<sect1> 8.137 -<title>Common template keywords</title> 8.138 -<para>\label{sec:template:keyword} 8.139 -</para> 8.140 - 8.141 -<para>You can start writing simple templates immediately using the keywords 8.142 -below. 8.143 -</para> 8.144 - 8.145 -<itemizedlist> 8.146 -<listitem><para><literal role="template-keyword">author</literal>: String. The unmodified author of the changeset. 8.147 -</para> 8.148 -</listitem> 8.149 -<listitem><para><literal role="template-keyword">branches</literal>: String. The name of the branch on which 8.150 - the changeset was committed. Will be empty if the branch name was 8.151 - <literal>default</literal>. 8.152 -</para> 8.153 -</listitem> 8.154 -<listitem><para><literal role="template-keyword">date</literal>: Date information. The date when the changeset 8.155 - was committed. This is <emphasis>not</emphasis> human-readable; you must pass it 8.156 - through a filter that will render it appropriately. See 8.157 - section <xref linkend="sec:template:filter"/> for more information on filters. 8.158 - The date is expressed as a pair of numbers. The first number is a 8.159 - Unix UTC timestamp (seconds since January 1, 1970); the second is 8.160 - the offset of the committer's timezone from UTC, in seconds. 8.161 -</para> 8.162 -</listitem> 8.163 -<listitem><para><literal role="template-keyword">desc</literal>: String. The text of the changeset description. 8.164 -</para> 8.165 -</listitem> 8.166 -<listitem><para><literal role="template-keyword">files</literal>: List of strings. All files modified, added, or 8.167 - removed by this changeset. 8.168 -</para> 8.169 -</listitem> 8.170 -<listitem><para><literal role="template-keyword">file_adds</literal>: List of strings. Files added by this 8.171 - changeset. 8.172 -</para> 8.173 -</listitem> 8.174 -<listitem><para><literal role="template-keyword">file_dels</literal>: List of strings. Files removed by this 8.175 - changeset. 8.176 -</para> 8.177 -</listitem> 8.178 -<listitem><para><literal role="template-keyword">node</literal>: String. The changeset identification hash, as a 8.179 - 40-character hexadecimal string. 8.180 -</para> 8.181 -</listitem> 8.182 -<listitem><para><literal role="template-keyword">parents</literal>: List of strings. The parents of the 8.183 - changeset. 8.184 -</para> 8.185 -</listitem> 8.186 -<listitem><para><literal role="template-keyword">rev</literal>: Integer. The repository-local changeset revision 8.187 - number. 8.188 -</para> 8.189 -</listitem> 8.190 -<listitem><para><literal role="template-keyword">tags</literal>: List of strings. Any tags associated with the 8.191 - changeset. 8.192 -</para> 8.193 -</listitem></itemizedlist> 8.194 - 8.195 -<para>A few simple experiments will show us what to expect when we use these 8.196 -keywords; you can see the results in 8.197 -figure <xref linkend="fig:template:keywords"/>. 8.198 -</para> 8.199 - 8.200 -<informalfigure> 8.201 -<para> <!-- &interaction.template.simple.keywords; --> 8.202 - <caption><para>Template keywords in use</para></caption> 8.203 - \label{fig:template:keywords} 8.204 -</para> 8.205 -</informalfigure> 8.206 - 8.207 -<para>As we noted above, the date keyword does not produce human-readable 8.208 -output, so we must treat it specially. This involves using a 8.209 -<emphasis>filter</emphasis>, about which more in section <xref linkend="sec:template:filter"/>. 8.210 -</para> 8.211 - 8.212 -<para><!-- &interaction.template.simple.datekeyword; --> 8.213 -</para> 8.214 - 8.215 -</sect1> 8.216 -<sect1> 8.217 -<title>Escape sequences</title> 8.218 -<para>\label{sec:template:escape} 8.219 -</para> 8.220 - 8.221 -<para>Mercurial's templating engine recognises the most commonly used escape 8.222 -sequences in strings. When it sees a backslash (<quote><literal>\</literal></quote>) 8.223 -character, it looks at the following character and substitutes the two 8.224 -characters with a single replacement, as described below. 8.225 -</para> 8.226 - 8.227 -<itemizedlist> 8.228 -<listitem><para><literal>\textbackslash\textbackslash</literal>: Backslash, <quote><literal>\</literal></quote>, 8.229 - ASCII 134. 8.230 -</para> 8.231 -</listitem> 8.232 -<listitem><para><literal>\textbackslash n</literal>: Newline, ASCII 12. 8.233 -</para> 8.234 -</listitem> 8.235 -<listitem><para><literal>\textbackslash r</literal>: Carriage return, ASCII 15. 8.236 -</para> 8.237 -</listitem> 8.238 -<listitem><para><literal>\textbackslash t</literal>: Tab, ASCII 11. 8.239 -</para> 8.240 -</listitem> 8.241 -<listitem><para><literal>\textbackslash v</literal>: Vertical tab, ASCII 13. 8.242 -</para> 8.243 -</listitem> 8.244 -<listitem><para><literal>\textbackslash {</literal>: Open curly brace, <quote><literal>{</literal></quote>, ASCII 173. 8.245 -</para> 8.246 -</listitem> 8.247 -<listitem><para><literal>\textbackslash }</literal>: Close curly brace, <quote><literal>}</literal></quote>, ASCII 175. 8.248 -</para> 8.249 -</listitem></itemizedlist> 8.250 - 8.251 -<para>As indicated above, if you want the expansion of a template to contain 8.252 -a literal <quote><literal>\</literal></quote>, <quote><literal>{</literal></quote>, or <quote><literal>{</literal></quote> character, you 8.253 -must escape it. 8.254 -</para> 8.255 - 8.256 -</sect1> 8.257 -<sect1> 8.258 -<title>Filtering keywords to change their results</title> 8.259 -<para>\label{sec:template:filter} 8.260 -</para> 8.261 - 8.262 -<para>Some of the results of template expansion are not immediately easy to 8.263 -use. Mercurial lets you specify an optional chain of <emphasis>filters</emphasis> 8.264 -to modify the result of expanding a keyword. You have already seen a 8.265 -common filter, <literal role="template-kw-filt-date">isodate</literal>, in action above, to make a 8.266 -date readable. 8.267 -</para> 8.268 - 8.269 -<para>Below is a list of the most commonly used filters that Mercurial 8.270 -supports. While some filters can be applied to any text, others can 8.271 -only be used in specific circumstances. The name of each filter is 8.272 -followed first by an indication of where it can be used, then a 8.273 -description of its effect. 8.274 -</para> 8.275 - 8.276 -<itemizedlist> 8.277 -<listitem><para><literal role="template-filter">addbreaks</literal>: Any text. Add an XHTML <quote><literal><br/></literal></quote> 8.278 - tag before the end of every line except the last. For example, 8.279 - <quote><literal>foo\nbar</literal></quote> becomes <quote><literal>foo<br/>\nbar</literal></quote>. 8.280 -</para> 8.281 -</listitem> 8.282 -<listitem><para><literal role="template-kw-filt-date">age</literal>: <literal role="template-keyword">date</literal> keyword. Render the 8.283 - age of the date, relative to the current time. Yields a string like 8.284 - <quote><literal>10 minutes</literal></quote>. 8.285 -</para> 8.286 -</listitem> 8.287 -<listitem><para><literal role="template-filter">basename</literal>: Any text, but most useful for the 8.288 - <literal role="template-keyword">files</literal> keyword and its relatives. Treat the text as a 8.289 - path, and return the basename. For example, <quote><literal>foo/bar/baz</literal></quote> 8.290 - becomes <quote><literal>baz</literal></quote>. 8.291 -</para> 8.292 -</listitem> 8.293 -<listitem><para><literal role="template-kw-filt-date">date</literal>: <literal role="template-keyword">date</literal> keyword. Render a date 8.294 - in a similar format to the Unix <literal role="template-keyword">date</literal> command, but with 8.295 - timezone included. Yields a string like 8.296 - <quote><literal>Mon Sep 04 15:13:13 2006 -0700</literal></quote>. 8.297 -</para> 8.298 -</listitem> 8.299 -<listitem><para><literal role="template-kw-filt-author">domain</literal>: Any text, but most useful for the 8.300 - <literal role="template-keyword">author</literal> keyword. Finds the first string that looks like 8.301 - an email address, and extract just the domain component. For 8.302 - example, <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 8.303 - <quote><literal>serpentine.com</literal></quote>. 8.304 -</para> 8.305 -</listitem> 8.306 -<listitem><para><literal role="template-kw-filt-author">email</literal>: Any text, but most useful for the 8.307 - <literal role="template-keyword">author</literal> keyword. Extract the first string that looks like 8.308 - an email address. For example, 8.309 - <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 8.310 - <quote><literal>bos@serpentine.com</literal></quote>. 8.311 -</para> 8.312 -</listitem> 8.313 -<listitem><para><literal role="template-filter">escape</literal>: Any text. Replace the special XML/XHTML 8.314 - characters <quote><literal>&</literal></quote>, <quote><literal><</literal></quote> and <quote><literal>></literal></quote> with 8.315 - XML entities. 8.316 -</para> 8.317 -</listitem> 8.318 -<listitem><para><literal role="template-filter">fill68</literal>: Any text. Wrap the text to fit in 68 8.319 - columns. This is useful before you pass text through the 8.320 - <literal role="template-filter">tabindent</literal> filter, and still want it to fit in an 8.321 - 80-column fixed-font window. 8.322 -</para> 8.323 -</listitem> 8.324 -<listitem><para><literal role="template-filter">fill76</literal>: Any text. Wrap the text to fit in 76 8.325 - columns. 8.326 -</para> 8.327 -</listitem> 8.328 -<listitem><para><literal role="template-filter">firstline</literal>: Any text. Yield the first line of text, 8.329 - without any trailing newlines. 8.330 -</para> 8.331 -</listitem> 8.332 -<listitem><para><literal role="template-kw-filt-date">hgdate</literal>: <literal role="template-keyword">date</literal> keyword. Render the 8.333 - date as a pair of readable numbers. Yields a string like 8.334 - <quote><literal>1157407993 25200</literal></quote>. 8.335 -</para> 8.336 -</listitem> 8.337 -<listitem><para><literal role="template-kw-filt-date">isodate</literal>: <literal role="template-keyword">date</literal> keyword. Render the 8.338 - date as a text string in ISO 8601 format. Yields a string like 8.339 - <quote><literal>2006-09-04 15:13:13 -0700</literal></quote>. 8.340 -</para> 8.341 -</listitem> 8.342 -<listitem><para><literal role="template-filter">obfuscate</literal>: Any text, but most useful for the 8.343 - <literal role="template-keyword">author</literal> keyword. Yield the input text rendered as a 8.344 - sequence of XML entities. This helps to defeat some particularly 8.345 - stupid screen-scraping email harvesting spambots. 8.346 -</para> 8.347 -</listitem> 8.348 -<listitem><para><literal role="template-kw-filt-author">person</literal>: Any text, but most useful for the 8.349 - <literal role="template-keyword">author</literal> keyword. Yield the text before an email address. 8.350 - For example, <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> 8.351 - becomes <quote><literal>Bryan O'Sullivan</literal></quote>. 8.352 -</para> 8.353 -</listitem> 8.354 -<listitem><para><literal role="template-kw-filt-date">rfc822date</literal>: <literal role="template-keyword">date</literal> keyword. Render a 8.355 - date using the same format used in email headers. Yields a string 8.356 - like <quote><literal>Mon, 04 Sep 2006 15:13:13 -0700</literal></quote>. 8.357 -</para> 8.358 -</listitem> 8.359 -<listitem><para><literal role="template-kw-filt-node">short</literal>: Changeset hash. Yield the short form 8.360 - of a changeset hash, i.e. a 12-character hexadecimal string. 8.361 -</para> 8.362 -</listitem> 8.363 -<listitem><para><literal role="template-kw-filt-date">shortdate</literal>: <literal role="template-keyword">date</literal> keyword. Render 8.364 - the year, month, and day of the date. Yields a string like 8.365 - <quote><literal>2006-09-04</literal></quote>. 8.366 -</para> 8.367 -</listitem> 8.368 -<listitem><para><literal role="template-filter">strip</literal>: Any text. Strip all leading and trailing 8.369 - whitespace from the string. 8.370 -</para> 8.371 -</listitem> 8.372 -<listitem><para><literal role="template-filter">tabindent</literal>: Any text. Yield the text, with every line 8.373 - except the first starting with a tab character. 8.374 -</para> 8.375 -</listitem> 8.376 -<listitem><para><literal role="template-filter">urlescape</literal>: Any text. Escape all characters that are 8.377 - considered <quote>special</quote> by URL parsers. For example, <literal>foo bar</literal> 8.378 - becomes <literal>foo%20bar</literal>. 8.379 -</para> 8.380 -</listitem> 8.381 -<listitem><para><literal role="template-kw-filt-author">user</literal>: Any text, but most useful for the 8.382 - <literal role="template-keyword">author</literal> keyword. Return the <quote>user</quote> portion of an email 8.383 - address. For example, 8.384 - <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 8.385 - <quote><literal>bos</literal></quote>. 8.386 -</para> 8.387 -</listitem></itemizedlist> 8.388 - 8.389 -<informalfigure> 8.390 -<para> <!-- &interaction.template.simple.manyfilters; --> 8.391 - <caption><para>Template filters in action</para></caption> 8.392 - \label{fig:template:filters} 8.393 -</para> 8.394 -</informalfigure> 8.395 - 8.396 -<note> 8.397 -<para> If you try to apply a filter to a piece of data that it cannot 8.398 - process, Mercurial will fail and print a Python exception. For 8.399 - example, trying to run the output of the <literal role="template-keyword">desc</literal> keyword 8.400 - into the <literal role="template-kw-filt-date">isodate</literal> filter is not a good idea. 8.401 -</para> 8.402 -</note> 8.403 - 8.404 -<sect2> 8.405 -<title>Combining filters</title> 8.406 - 8.407 -<para>It is easy to combine filters to yield output in the form you would 8.408 -like. The following chain of filters tidies up a description, then 8.409 -makes sure that it fits cleanly into 68 columns, then indents it by a 8.410 -further 8 characters (at least on Unix-like systems, where a tab is 8.411 -conventionally 8 characters wide). 8.412 -</para> 8.413 - 8.414 -<para><!-- &interaction.template.simple.combine; --> 8.415 -</para> 8.416 - 8.417 -<para>Note the use of <quote><literal>\t</literal></quote> (a tab character) in the template to 8.418 -force the first line to be indented; this is necessary since 8.419 -<literal role="template-keyword">tabindent</literal> indents all lines <emphasis>except</emphasis> the first. 8.420 -</para> 8.421 - 8.422 -<para>Keep in mind that the order of filters in a chain is significant. The 8.423 -first filter is applied to the result of the keyword; the second to 8.424 -the result of the first filter; and so on. For example, using 8.425 -<literal>fill68|tabindent</literal> gives very different results from 8.426 -<literal>tabindent|fill68</literal>. 8.427 -</para> 8.428 - 8.429 - 8.430 -</sect2> 8.431 -</sect1> 8.432 -<sect1> 8.433 -<title>From templates to styles</title> 8.434 - 8.435 -<para>A command line template provides a quick and simple way to format some 8.436 -output. Templates can become verbose, though, and it's useful to be 8.437 -able to give a template a name. A style file is a template with a 8.438 -name, stored in a file. 8.439 -</para> 8.440 - 8.441 -<para>More than that, using a style file unlocks the power of Mercurial's 8.442 -templating engine in ways that are not possible using the command line 8.443 -<option role="hg-opt-log">--template</option> option. 8.444 -</para> 8.445 - 8.446 -<sect2> 8.447 -<title>The simplest of style files</title> 8.448 - 8.449 -<para>Our simple style file contains just one line: 8.450 -</para> 8.451 - 8.452 -<para><!-- &interaction.template.simple.rev; --> 8.453 -</para> 8.454 - 8.455 -<para>This tells Mercurial, <quote>if you're printing a changeset, use the text 8.456 -on the right as the template</quote>. 8.457 -</para> 8.458 - 8.459 -</sect2> 8.460 -<sect2> 8.461 -<title>Style file syntax</title> 8.462 - 8.463 -<para>The syntax rules for a style file are simple. 8.464 -</para> 8.465 - 8.466 -<itemizedlist> 8.467 -<listitem><para>The file is processed one line at a time. 8.468 -</para> 8.469 -</listitem> 8.470 -</para> 8.471 -</listitem> 8.472 -<listitem><para>Leading and trailing white space are ignored. 8.473 -</para> 8.474 -</listitem> 8.475 -</para> 8.476 -</listitem> 8.477 -<listitem><para>Empty lines are skipped. 8.478 -</para> 8.479 -</listitem> 8.480 -</para> 8.481 -</listitem> 8.482 -<listitem><para>If a line starts with either of the characters <quote><literal>#</literal></quote> or 8.483 - <quote><literal>;</literal></quote>, the entire line is treated as a comment, and skipped 8.484 - as if empty. 8.485 -</para> 8.486 -</listitem> 8.487 -</para> 8.488 -</listitem> 8.489 -<listitem><para>A line starts with a keyword. This must start with an 8.490 - alphabetic character or underscore, and can subsequently contain any 8.491 - alphanumeric character or underscore. (In regexp notation, a 8.492 - keyword must match <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.) 8.493 -</para> 8.494 -</listitem> 8.495 -</para> 8.496 -</listitem> 8.497 -<listitem><para>The next element must be an <quote><literal>=</literal></quote> character, which can 8.498 - be preceded or followed by an arbitrary amount of white space. 8.499 -</para> 8.500 -</listitem> 8.501 -</para> 8.502 -</listitem> 8.503 -<listitem><para>If the rest of the line starts and ends with matching quote 8.504 - characters (either single or double quote), it is treated as a 8.505 - template body. 8.506 -</para> 8.507 -</listitem> 8.508 -</para> 8.509 -</listitem> 8.510 -<listitem><para>If the rest of the line <emphasis>does not</emphasis> start with a quote 8.511 - character, it is treated as the name of a file; the contents of this 8.512 - file will be read and used as a template body. 8.513 -</para> 8.514 -</listitem></itemizedlist> 8.515 - 8.516 -</sect2> 8.517 -</sect1> 8.518 -<sect1> 8.519 -<title>Style files by example</title> 8.520 - 8.521 -<para>To illustrate how to write a style file, we will construct a few by 8.522 -example. Rather than provide a complete style file and walk through 8.523 -it, we'll mirror the usual process of developing a style file by 8.524 -starting with something very simple, and walking through a series of 8.525 -successively more complete examples. 8.526 -</para> 8.527 - 8.528 -<sect2> 8.529 -<title>Identifying mistakes in style files</title> 8.530 - 8.531 -<para>If Mercurial encounters a problem in a style file you are working on, 8.532 -it prints a terse error message that, once you figure out what it 8.533 -means, is actually quite useful. 8.534 -</para> 8.535 - 8.536 -<para><!-- &interaction.template.svnstyle.syntax.input; --> 8.537 -</para> 8.538 - 8.539 -<para>Notice that <filename>broken.style</filename> attempts to define a 8.540 -<literal>changeset</literal> keyword, but forgets to give any content for it. 8.541 -When instructed to use this style file, Mercurial promptly complains. 8.542 -</para> 8.543 - 8.544 -<para><!-- &interaction.template.svnstyle.syntax.error; --> 8.545 -</para> 8.546 - 8.547 -<para>This error message looks intimidating, but it is not too hard to 8.548 -follow. 8.549 -</para> 8.550 - 8.551 -<itemizedlist> 8.552 -<listitem><para>The first component is simply Mercurial's way of saying <quote>I am 8.553 - giving up</quote>. 8.554 -</para> 8.555 -</listitem><programlisting> 8.556 -<listitem><para> <emphasis role="bold">abort:</emphasis> broken.style:1: parse error 8.557 -</para> 8.558 -</listitem></programlisting> 8.559 - 8.560 -</para> 8.561 -</listitem> 8.562 -<listitem><para>Next comes the name of the style file that contains the error. 8.563 -</para> 8.564 -</listitem><programlisting> 8.565 -<listitem><para> abort: <emphasis role="bold">broken.style</emphasis>:1: parse error 8.566 -</para> 8.567 -</listitem></programlisting> 8.568 - 8.569 -</para> 8.570 -</listitem> 8.571 -<listitem><para>Following the file name is the line number where the error was 8.572 - encountered. 8.573 -</para> 8.574 -</listitem><programlisting> 8.575 -<listitem><para> abort: broken.style:<emphasis role="bold">1</emphasis>: parse error 8.576 -</para> 8.577 -</listitem></programlisting> 8.578 - 8.579 -</para> 8.580 -</listitem> 8.581 -<listitem><para>Finally, a description of what went wrong. 8.582 -</para> 8.583 -</listitem><programlisting> 8.584 -<listitem><para> abort: broken.style:1: <emphasis role="bold">parse error</emphasis> 8.585 -</para> 8.586 -</listitem></programlisting> 8.587 -<listitem><para> The description of the problem is not always clear (as in this 8.588 - case), but even when it is cryptic, it is almost always trivial to 8.589 - visually inspect the offending line in the style file and see what 8.590 - is wrong. 8.591 -</para> 8.592 -</listitem></itemizedlist> 8.593 - 8.594 -</sect2> 8.595 -<sect2> 8.596 -<title>Uniquely identifying a repository</title> 8.597 - 8.598 -<para>If you would like to be able to identify a Mercurial repository 8.599 -<quote>fairly uniquely</quote> using a short string as an identifier, you can 8.600 -use the first revision in the repository. 8.601 -<!-- &interaction.template.svnstyle.id; --> 8.602 -This is not guaranteed to be unique, but it is nevertheless useful in 8.603 -many cases. 8.604 -</para> 8.605 -<itemizedlist> 8.606 -<listitem><para>It will not work in a completely empty repository, because such 8.607 - a repository does not have a revision zero. 8.608 -</para> 8.609 -</listitem> 8.610 -<listitem><para>Neither will it work in the (extremely rare) case where a 8.611 - repository is a merge of two or more formerly independent 8.612 - repositories, and you still have those repositories around. 8.613 -</para> 8.614 -</listitem></itemizedlist> 8.615 -<para>Here are some uses to which you could put this identifier: 8.616 -</para> 8.617 -<itemizedlist> 8.618 -<listitem><para>As a key into a table for a database that manages repositories 8.619 - on a server. 8.620 -</para> 8.621 -</listitem> 8.622 -<listitem><para>As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 8.623 - Save this information away when you run an automated build or other 8.624 - activity, so that you can <quote>replay</quote> the build later if necessary. 8.625 -</para> 8.626 -</listitem></itemizedlist> 8.627 - 8.628 -</sect2> 8.629 -<sect2> 8.630 -<title>Mimicking Subversion's output</title> 8.631 - 8.632 -<para>Let's try to emulate the default output format used by another 8.633 -revision control tool, Subversion. 8.634 -<!-- &interaction.template.svnstyle.short; --> 8.635 -</para> 8.636 - 8.637 -<para>Since Subversion's output style is fairly simple, it is easy to 8.638 -copy-and-paste a hunk of its output into a file, and replace the text 8.639 -produced above by Subversion with the template values we'd like to see 8.640 -expanded. 8.641 -<!-- &interaction.template.svnstyle.template; --> 8.642 -</para> 8.643 - 8.644 -<para>There are a few small ways in which this template deviates from the 8.645 -output produced by Subversion. 8.646 -</para> 8.647 -<itemizedlist> 8.648 -<listitem><para>Subversion prints a <quote>readable</quote> date (the <quote>\texttt{Wed, 27 Sep 8.649 - 2006}</quote> in the example output above) in parentheses. Mercurial's 8.650 - templating engine does not provide a way to display a date in this 8.651 - format without also printing the time and time zone. 8.652 -</para> 8.653 -</listitem> 8.654 -<listitem><para>We emulate Subversion's printing of <quote>separator</quote> lines full of 8.655 - <quote><literal>-</literal></quote> characters by ending the template with such a line. 8.656 - We use the templating engine's <literal role="template-keyword">header</literal> keyword to print a 8.657 - separator line as the first line of output (see below), thus 8.658 - achieving similar output to Subversion. 8.659 -</para> 8.660 -</listitem> 8.661 -<listitem><para>Subversion's output includes a count in the header of the number 8.662 - of lines in the commit message. We cannot replicate this in 8.663 - Mercurial; the templating engine does not currently provide a filter 8.664 - that counts the number of lines the template generates. 8.665 -</para> 8.666 -</listitem></itemizedlist> 8.667 -<para>It took me no more than a minute or two of work to replace literal 8.668 -text from an example of Subversion's output with some keywords and 8.669 -filters to give the template above. The style file simply refers to 8.670 -the template. 8.671 -<!-- &interaction.template.svnstyle.style; --> 8.672 -</para> 8.673 - 8.674 -<para>We could have included the text of the template file directly in the 8.675 -style file by enclosing it in quotes and replacing the newlines with 8.676 -<quote><literal>\n</literal></quote> sequences, but it would have made the style file too 8.677 -difficult to read. Readability is a good guide when you're trying to 8.678 -decide whether some text belongs in a style file, or in a template 8.679 -file that the style file points to. If the style file will look too 8.680 -big or cluttered if you insert a literal piece of text, drop it into a 8.681 -template instead. 8.682 -</para> 8.683 - 8.684 -</sect2> 8.685 -</sect1> 8.686 +<chapter id="chap:template"> 8.687 + <?dbhtml filename="customizing-the-output-of-mercurial.html"?> 8.688 + <title>Customizing the output of Mercurial</title> 8.689 + 8.690 + <para id="x_578">Mercurial provides a powerful mechanism to let you control how 8.691 + it displays information. The mechanism is based on templates. 8.692 + You can use templates to generate specific output for a single 8.693 + command, or to customize the entire appearance of the built-in web 8.694 + interface.</para> 8.695 + 8.696 + <sect1 id="sec:style"> 8.697 + <title>Using precanned output styles</title> 8.698 + 8.699 + <para id="x_579">Packaged with Mercurial are some output styles that you can 8.700 + use immediately. A style is simply a precanned template that 8.701 + someone wrote and installed somewhere that Mercurial can 8.702 + find.</para> 8.703 + 8.704 + <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's 8.705 + review its normal output.</para> 8.706 + 8.707 + &interaction.template.simple.normal; 8.708 + 8.709 + <para id="x_57b">This is somewhat informative, but it takes up a lot of 8.710 + space&emdash;five lines of output per changeset. The 8.711 + <literal>compact</literal> style reduces this to three lines, 8.712 + presented in a sparse manner.</para> 8.713 + 8.714 + &interaction.template.simple.compact; 8.715 + 8.716 + <para id="x_57c">The <literal>changelog</literal> style hints at the 8.717 + expressive power of Mercurial's templating engine. This style 8.718 + attempts to follow the GNU Project's changelog 8.719 + guidelines<citation>web:changelog</citation>.</para> 8.720 + 8.721 + &interaction.template.simple.changelog; 8.722 + 8.723 + <para id="x_57d">You will not be shocked to learn that Mercurial's default 8.724 + output style is named <literal>default</literal>.</para> 8.725 + 8.726 + <sect2> 8.727 + <title>Setting a default style</title> 8.728 + 8.729 + <para id="x_57e">You can modify the output style that Mercurial will use 8.730 + for every command by editing your <filename 8.731 + role="special">~/.hgrc</filename> file, naming the style 8.732 + you would prefer to use.</para> 8.733 + 8.734 + <programlisting>[ui] 8.735 +style = compact</programlisting> 8.736 + 8.737 + <para id="x_57f">If you write a style of your own, you can use it by either 8.738 + providing the path to your style file, or copying your style 8.739 + file into a location where Mercurial can find it (typically 8.740 + the <literal>templates</literal> subdirectory of your 8.741 + Mercurial install directory).</para> 8.742 + </sect2> 8.743 + </sect1> 8.744 + 8.745 + <sect1> 8.746 + <title>Commands that support styles and templates</title> 8.747 + 8.748 + <para id="x_580">All of Mercurial's 8.749 + <quote><literal>log</literal>-like</quote> commands let you use 8.750 + styles and templates: <command role="hg-cmd">hg 8.751 + incoming</command>, <command role="hg-cmd">hg log</command>, 8.752 + <command role="hg-cmd">hg outgoing</command>, and <command 8.753 + role="hg-cmd">hg tip</command>.</para> 8.754 + 8.755 + <para id="x_581">As I write this manual, these are so far the only commands 8.756 + that support styles and templates. Since these are the most 8.757 + important commands that need customizable output, there has been 8.758 + little pressure from the Mercurial user community to add style 8.759 + and template support to other commands.</para> 8.760 + </sect1> 8.761 + 8.762 + <sect1> 8.763 + <title>The basics of templating</title> 8.764 + 8.765 + <para id="x_582">At its simplest, a Mercurial template is a piece of text. 8.766 + Some of the text never changes, while other parts are 8.767 + <emphasis>expanded</emphasis>, or replaced with new text, when 8.768 + necessary.</para> 8.769 + 8.770 + <para id="x_583">Before we continue, let's look again at a simple example of 8.771 + Mercurial's normal output.</para> 8.772 + 8.773 + &interaction.template.simple.normal; 8.774 + 8.775 + <para id="x_584">Now, let's run the same command, but using a template to 8.776 + change its output.</para> 8.777 + 8.778 + &interaction.template.simple.simplest; 8.779 + 8.780 + <para id="x_585">The example above illustrates the simplest possible 8.781 + template; it's just a piece of static text, printed once for 8.782 + each changeset. The <option 8.783 + role="hg-opt-log">--template</option> option to the <command 8.784 + role="hg-cmd">hg log</command> command tells Mercurial to use 8.785 + the given text as the template when printing each 8.786 + changeset.</para> 8.787 + 8.788 + <para id="x_586">Notice that the template string above ends with the text 8.789 + <quote><literal>\n</literal></quote>. This is an 8.790 + <emphasis>escape sequence</emphasis>, telling Mercurial to print 8.791 + a newline at the end of each template item. If you omit this 8.792 + newline, Mercurial will run each piece of output together. See 8.793 + <xref linkend="sec:template:escape"/> for more details 8.794 + of escape sequences.</para> 8.795 + 8.796 + <para id="x_587">A template that prints a fixed string of text all the time 8.797 + isn't very useful; let's try something a bit more 8.798 + complex.</para> 8.799 + 8.800 + &interaction.template.simple.simplesub; 8.801 + 8.802 + <para id="x_588">As you can see, the string 8.803 + <quote><literal>{desc}</literal></quote> in the template has 8.804 + been replaced in the output with the description of each 8.805 + changeset. Every time Mercurial finds text enclosed in curly 8.806 + braces (<quote><literal>{</literal></quote> and 8.807 + <quote><literal>}</literal></quote>), it will try to replace the 8.808 + braces and text with the expansion of whatever is inside. To 8.809 + print a literal curly brace, you must escape it, as described in 8.810 + <xref linkend="sec:template:escape"/>.</para> 8.811 + </sect1> 8.812 + 8.813 + <sect1 id="sec:template:keyword"> 8.814 + <title>Common template keywords</title> 8.815 + 8.816 + <para id="x_589">You can start writing simple templates immediately using the 8.817 + keywords below.</para> 8.818 + 8.819 + <itemizedlist> 8.820 + <listitem><para id="x_58a"><literal 8.821 + role="template-keyword">author</literal>: String. The 8.822 + unmodified author of the changeset.</para> 8.823 + </listitem> 8.824 + <listitem><para id="x_58b"><literal 8.825 + role="template-keyword">branches</literal>: String. The 8.826 + name of the branch on which the changeset was committed. 8.827 + Will be empty if the branch name was 8.828 + <literal>default</literal>.</para> 8.829 + </listitem> 8.830 + <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: 8.831 + Date information. The date when the changeset was 8.832 + committed. This is <emphasis>not</emphasis> human-readable; 8.833 + you must pass it through a filter that will render it 8.834 + appropriately. See <xref 8.835 + linkend="sec:template:filter"/> for more information 8.836 + on filters. The date is expressed as a pair of numbers. The 8.837 + first number is a Unix UTC timestamp (seconds since January 8.838 + 1, 1970); the second is the offset of the committer's 8.839 + timezone from UTC, in seconds.</para> 8.840 + </listitem> 8.841 + <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: 8.842 + String. The text of the changeset description.</para> 8.843 + </listitem> 8.844 + <listitem><para id="x_58e"><literal 8.845 + role="template-keyword">files</literal>: List of strings. 8.846 + All files modified, added, or removed by this 8.847 + changeset.</para> 8.848 + </listitem> 8.849 + <listitem><para id="x_58f"><literal 8.850 + role="template-keyword">file_adds</literal>: List of 8.851 + strings. Files added by this changeset.</para> 8.852 + </listitem> 8.853 + <listitem><para id="x_590"><literal 8.854 + role="template-keyword">file_dels</literal>: List of 8.855 + strings. Files removed by this changeset.</para> 8.856 + </listitem> 8.857 + <listitem><para id="x_591"><literal role="template-keyword">node</literal>: 8.858 + String. The changeset identification hash, as a 8.859 + 40-character hexadecimal string.</para> 8.860 + </listitem> 8.861 + <listitem><para id="x_592"><literal 8.862 + role="template-keyword">parents</literal>: List of 8.863 + strings. The parents of the changeset.</para> 8.864 + </listitem> 8.865 + <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: 8.866 + Integer. The repository-local changeset revision 8.867 + number.</para> 8.868 + </listitem> 8.869 + <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: 8.870 + List of strings. Any tags associated with the 8.871 + changeset.</para> 8.872 + </listitem> 8.873 + </itemizedlist> 8.874 + 8.875 + <para id="x_595">A few simple experiments will show us what to expect when we 8.876 + use these keywords; you can see the results below.</para> 8.877 + 8.878 + &interaction.template.simple.keywords; 8.879 + 8.880 + <para id="x_596">As we noted above, the date keyword does not produce 8.881 + human-readable output, so we must treat it specially. This 8.882 + involves using a <emphasis>filter</emphasis>, about which more 8.883 + in <xref linkend="sec:template:filter"/>.</para> 8.884 + 8.885 + &interaction.template.simple.datekeyword; 8.886 + </sect1> 8.887 + 8.888 + <sect1 id="sec:template:escape"> 8.889 + <title>Escape sequences</title> 8.890 + 8.891 + <para id="x_597">Mercurial's templating engine recognises the most commonly 8.892 + used escape sequences in strings. When it sees a backslash 8.893 + (<quote><literal>\</literal></quote>) character, it looks at the 8.894 + following character and substitutes the two characters with a 8.895 + single replacement, as described below.</para> 8.896 + 8.897 + <itemizedlist> 8.898 + <listitem><para id="x_598"><literal>\</literal>: 8.899 + Backslash, <quote><literal>\</literal></quote>, ASCII 8.900 + 134.</para> 8.901 + </listitem> 8.902 + <listitem><para id="x_599"><literal>\n</literal>: Newline, 8.903 + ASCII 12.</para> 8.904 + </listitem> 8.905 + <listitem><para id="x_59a"><literal>\r</literal>: Carriage 8.906 + return, ASCII 15.</para> 8.907 + </listitem> 8.908 + <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII 8.909 + 11.</para> 8.910 + </listitem> 8.911 + <listitem><para id="x_59c"><literal>\v</literal>: Vertical 8.912 + tab, ASCII 13.</para> 8.913 + </listitem> 8.914 + <listitem><para id="x_59d"><literal>\{</literal>: Open curly 8.915 + brace, <quote><literal>{</literal></quote>, ASCII 8.916 + 173.</para> 8.917 + </listitem> 8.918 + <listitem><para id="x_59e"><literal>\}</literal>: Close curly 8.919 + brace, <quote><literal>}</literal></quote>, ASCII 8.920 + 175.</para> 8.921 + </listitem></itemizedlist> 8.922 + 8.923 + <para id="x_59f">As indicated above, if you want the expansion of a template 8.924 + to contain a literal <quote><literal>\</literal></quote>, 8.925 + <quote><literal>{</literal></quote>, or 8.926 + <quote><literal>{</literal></quote> character, you must escape 8.927 + it.</para> 8.928 + </sect1> 8.929 + 8.930 + <sect1 id="sec:template:filter"> 8.931 + <title>Filtering keywords to change their results</title> 8.932 + 8.933 + <para id="x_5a0">Some of the results of template expansion are not 8.934 + immediately easy to use. Mercurial lets you specify an optional 8.935 + chain of <emphasis>filters</emphasis> to modify the result of 8.936 + expanding a keyword. You have already seen a common filter, 8.937 + <literal role="template-kw-filt-date">isodate</literal>, in 8.938 + action above, to make a date readable.</para> 8.939 + 8.940 + <para id="x_5a1">Below is a list of the most commonly used filters that 8.941 + Mercurial supports. While some filters can be applied to any 8.942 + text, others can only be used in specific circumstances. The 8.943 + name of each filter is followed first by an indication of where 8.944 + it can be used, then a description of its effect.</para> 8.945 + 8.946 + <itemizedlist> 8.947 + <listitem><para id="x_5a2"><literal 8.948 + role="template-filter">addbreaks</literal>: Any text. Add 8.949 + an XHTML <quote><literal><br/></literal></quote> tag 8.950 + before the end of every line except the last. For example, 8.951 + <quote><literal>foo\nbar</literal></quote> becomes 8.952 + <quote><literal>foo<br/>\nbar</literal></quote>.</para> 8.953 + </listitem> 8.954 + <listitem><para id="x_5a3"><literal 8.955 + role="template-kw-filt-date">age</literal>: <literal 8.956 + role="template-keyword">date</literal> keyword. Render 8.957 + the age of the date, relative to the current time. Yields a 8.958 + string like <quote><literal>10 8.959 + minutes</literal></quote>.</para> 8.960 + </listitem> 8.961 + <listitem><para id="x_5a4"><literal 8.962 + role="template-filter">basename</literal>: Any text, but 8.963 + most useful for the <literal 8.964 + role="template-keyword">files</literal> keyword and its 8.965 + relatives. Treat the text as a path, and return the 8.966 + basename. For example, 8.967 + <quote><literal>foo/bar/baz</literal></quote> becomes 8.968 + <quote><literal>baz</literal></quote>.</para> 8.969 + </listitem> 8.970 + <listitem><para id="x_5a5"><literal 8.971 + role="template-kw-filt-date">date</literal>: <literal 8.972 + role="template-keyword">date</literal> keyword. Render a 8.973 + date in a similar format to the Unix <literal 8.974 + role="template-keyword">date</literal> command, but with 8.975 + timezone included. Yields a string like <quote><literal>Mon 8.976 + Sep 04 15:13:13 2006 -0700</literal></quote>.</para> 8.977 + </listitem> 8.978 + <listitem><para id="x_5a6"><literal 8.979 + role="template-kw-filt-author">domain</literal>: Any text, 8.980 + but most useful for the <literal 8.981 + role="template-keyword">author</literal> keyword. Finds 8.982 + the first string that looks like an email address, and 8.983 + extract just the domain component. For example, 8.984 + <quote><literal>Bryan O'Sullivan 8.985 + <bos@serpentine.com></literal></quote> becomes 8.986 + <quote><literal>serpentine.com</literal></quote>.</para> 8.987 + </listitem> 8.988 + <listitem><para id="x_5a7"><literal 8.989 + role="template-kw-filt-author">email</literal>: Any text, 8.990 + but most useful for the <literal 8.991 + role="template-keyword">author</literal> keyword. Extract 8.992 + the first string that looks like an email address. For 8.993 + example, <quote><literal>Bryan O'Sullivan 8.994 + <bos@serpentine.com></literal></quote> becomes 8.995 + <quote><literal>bos@serpentine.com</literal></quote>.</para> 8.996 + </listitem> 8.997 + <listitem><para id="x_5a8"><literal 8.998 + role="template-filter">escape</literal>: Any text. 8.999 + Replace the special XML/XHTML characters 8.1000 + <quote><literal>&</literal></quote>, 8.1001 + <quote><literal><</literal></quote> and 8.1002 + <quote><literal>></literal></quote> with XML 8.1003 + entities.</para> 8.1004 + </listitem> 8.1005 + <listitem><para id="x_5a9"><literal 8.1006 + role="template-filter">fill68</literal>: Any text. Wrap 8.1007 + the text to fit in 68 columns. This is useful before you 8.1008 + pass text through the <literal 8.1009 + role="template-filter">tabindent</literal> filter, and 8.1010 + still want it to fit in an 80-column fixed-font 8.1011 + window.</para> 8.1012 + </listitem> 8.1013 + <listitem><para id="x_5aa"><literal 8.1014 + role="template-filter">fill76</literal>: Any text. Wrap 8.1015 + the text to fit in 76 columns.</para> 8.1016 + </listitem> 8.1017 + <listitem><para id="x_5ab"><literal 8.1018 + role="template-filter">firstline</literal>: Any text. 8.1019 + Yield the first line of text, without any trailing 8.1020 + newlines.</para> 8.1021 + </listitem> 8.1022 + <listitem><para id="x_5ac"><literal 8.1023 + role="template-kw-filt-date">hgdate</literal>: <literal 8.1024 + role="template-keyword">date</literal> keyword. Render 8.1025 + the date as a pair of readable numbers. Yields a string 8.1026 + like <quote><literal>1157407993 8.1027 + 25200</literal></quote>.</para> 8.1028 + </listitem> 8.1029 + <listitem><para id="x_5ad"><literal 8.1030 + role="template-kw-filt-date">isodate</literal>: <literal 8.1031 + role="template-keyword">date</literal> keyword. Render 8.1032 + the date as a text string in ISO 8601 format. Yields a 8.1033 + string like <quote><literal>2006-09-04 15:13:13 8.1034 + -0700</literal></quote>.</para> 8.1035 + </listitem> 8.1036 + <listitem><para id="x_5ae"><literal 8.1037 + role="template-filter">obfuscate</literal>: Any text, but 8.1038 + most useful for the <literal 8.1039 + role="template-keyword">author</literal> keyword. Yield 8.1040 + the input text rendered as a sequence of XML entities. This 8.1041 + helps to defeat some particularly stupid screen-scraping 8.1042 + email harvesting spambots.</para> 8.1043 + </listitem> 8.1044 + <listitem><para id="x_5af"><literal 8.1045 + role="template-kw-filt-author">person</literal>: Any text, 8.1046 + but most useful for the <literal 8.1047 + role="template-keyword">author</literal> keyword. Yield 8.1048 + the text before an email address. For example, 8.1049 + <quote><literal>Bryan O'Sullivan 8.1050 + <bos@serpentine.com></literal></quote> becomes 8.1051 + <quote><literal>Bryan O'Sullivan</literal></quote>.</para> 8.1052 + </listitem> 8.1053 + <listitem><para id="x_5b0"><literal 8.1054 + role="template-kw-filt-date">rfc822date</literal>: 8.1055 + <literal role="template-keyword">date</literal> keyword. 8.1056 + Render a date using the same format used in email headers. 8.1057 + Yields a string like <quote><literal>Mon, 04 Sep 2006 8.1058 + 15:13:13 -0700</literal></quote>.</para> 8.1059 + </listitem> 8.1060 + <listitem><para id="x_5b1"><literal 8.1061 + role="template-kw-filt-node">short</literal>: Changeset 8.1062 + hash. Yield the short form of a changeset hash, i.e. a 8.1063 + 12-character hexadecimal string.</para> 8.1064 + </listitem> 8.1065 + <listitem><para id="x_5b2"><literal 8.1066 + role="template-kw-filt-date">shortdate</literal>: <literal 8.1067 + role="template-keyword">date</literal> keyword. Render 8.1068 + the year, month, and day of the date. Yields a string like 8.1069 + <quote><literal>2006-09-04</literal></quote>.</para> 8.1070 + </listitem> 8.1071 + <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: 8.1072 + Any text. Strip all leading and trailing whitespace from 8.1073 + the string.</para> 8.1074 + </listitem> 8.1075 + <listitem><para id="x_5b4"><literal 8.1076 + role="template-filter">tabindent</literal>: Any text. 8.1077 + Yield the text, with every line except the first starting 8.1078 + with a tab character.</para> 8.1079 + </listitem> 8.1080 + <listitem><para id="x_5b5"><literal 8.1081 + role="template-filter">urlescape</literal>: Any text. 8.1082 + Escape all characters that are considered 8.1083 + <quote>special</quote> by URL parsers. For example, 8.1084 + <literal>foo bar</literal> becomes 8.1085 + <literal>foo%20bar</literal>.</para> 8.1086 + </listitem> 8.1087 + <listitem><para id="x_5b6"><literal 8.1088 + role="template-kw-filt-author">user</literal>: Any text, 8.1089 + but most useful for the <literal 8.1090 + role="template-keyword">author</literal> keyword. Return 8.1091 + the <quote>user</quote> portion of an email address. For 8.1092 + example, <quote><literal>Bryan O'Sullivan 8.1093 + <bos@serpentine.com></literal></quote> becomes 8.1094 + <quote><literal>bos</literal></quote>.</para> 8.1095 + </listitem> 8.1096 + </itemizedlist> 8.1097 + 8.1098 + &interaction.template.simple.manyfilters; 8.1099 + 8.1100 + <note> 8.1101 + <para id="x_5b7"> If you try to apply a filter to a piece of data that it 8.1102 + cannot process, Mercurial will fail and print a Python 8.1103 + exception. For example, trying to run the output of the 8.1104 + <literal role="template-keyword">desc</literal> keyword into 8.1105 + the <literal role="template-kw-filt-date">isodate</literal> 8.1106 + filter is not a good idea.</para> 8.1107 + </note> 8.1108 + 8.1109 + <sect2> 8.1110 + <title>Combining filters</title> 8.1111 + 8.1112 + <para id="x_5b8">It is easy to combine filters to yield output in the form 8.1113 + you would like. The following chain of filters tidies up a 8.1114 + description, then makes sure that it fits cleanly into 68 8.1115 + columns, then indents it by a further 8 characters (at least 8.1116 + on Unix-like systems, where a tab is conventionally 8 8.1117 + characters wide).</para> 8.1118 + 8.1119 + &interaction.template.simple.combine; 8.1120 + 8.1121 + <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a 8.1122 + tab character) in the template to force the first line to be 8.1123 + indented; this is necessary since <literal 8.1124 + role="template-keyword">tabindent</literal> indents all 8.1125 + lines <emphasis>except</emphasis> the first.</para> 8.1126 + 8.1127 + <para id="x_5ba">Keep in mind that the order of filters in a chain is 8.1128 + significant. The first filter is applied to the result of the 8.1129 + keyword; the second to the result of the first filter; and so 8.1130 + on. For example, using <literal>fill68|tabindent</literal> 8.1131 + gives very different results from 8.1132 + <literal>tabindent|fill68</literal>.</para> 8.1133 + </sect2> 8.1134 + </sect1> 8.1135 + 8.1136 + <sect1> 8.1137 + <title>From templates to styles</title> 8.1138 + 8.1139 + <para id="x_5bb">A command line template provides a quick and simple way to 8.1140 + format some output. Templates can become verbose, though, and 8.1141 + it's useful to be able to give a template a name. A style file 8.1142 + is a template with a name, stored in a file.</para> 8.1143 + 8.1144 + <para id="x_5bc">More than that, using a style file unlocks the power of 8.1145 + Mercurial's templating engine in ways that are not possible 8.1146 + using the command line <option 8.1147 + role="hg-opt-log">--template</option> option.</para> 8.1148 + 8.1149 + <sect2> 8.1150 + <title>The simplest of style files</title> 8.1151 + 8.1152 + <para id="x_5bd">Our simple style file contains just one line:</para> 8.1153 + 8.1154 + &interaction.template.simple.rev; 8.1155 + 8.1156 + <para id="x_5be">This tells Mercurial, <quote>if you're printing a 8.1157 + changeset, use the text on the right as the 8.1158 + template</quote>.</para> 8.1159 + </sect2> 8.1160 + 8.1161 + <sect2> 8.1162 + <title>Style file syntax</title> 8.1163 + 8.1164 + <para id="x_5bf">The syntax rules for a style file are simple.</para> 8.1165 + 8.1166 + <itemizedlist> 8.1167 + <listitem><para id="x_5c0">The file is processed one line at a 8.1168 + time.</para> 8.1169 + </listitem> 8.1170 + <listitem><para id="x_5c1">Leading and trailing white space are 8.1171 + ignored.</para> 8.1172 + </listitem> 8.1173 + <listitem><para id="x_5c2">Empty lines are skipped.</para> 8.1174 + </listitem> 8.1175 + <listitem><para id="x_5c3">If a line starts with either of the characters 8.1176 + <quote><literal>#</literal></quote> or 8.1177 + <quote><literal>;</literal></quote>, the entire line is 8.1178 + treated as a comment, and skipped as if empty.</para> 8.1179 + </listitem> 8.1180 + <listitem><para id="x_5c4">A line starts with a keyword. This must start 8.1181 + with an alphabetic character or underscore, and can 8.1182 + subsequently contain any alphanumeric character or 8.1183 + underscore. (In regexp notation, a keyword must match 8.1184 + <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para> 8.1185 + </listitem> 8.1186 + <listitem><para id="x_5c5">The next element must be an 8.1187 + <quote><literal>=</literal></quote> character, which can 8.1188 + be preceded or followed by an arbitrary amount of white 8.1189 + space.</para> 8.1190 + </listitem> 8.1191 + <listitem><para id="x_5c6">If the rest of the line starts and ends with 8.1192 + matching quote characters (either single or double quote), 8.1193 + it is treated as a template body.</para> 8.1194 + </listitem> 8.1195 + <listitem><para id="x_5c7">If the rest of the line <emphasis>does 8.1196 + not</emphasis> start with a quote character, it is 8.1197 + treated as the name of a file; the contents of this file 8.1198 + will be read and used as a template body.</para> 8.1199 + </listitem></itemizedlist> 8.1200 + </sect2> 8.1201 + </sect1> 8.1202 + 8.1203 + <sect1> 8.1204 + <title>Style files by example</title> 8.1205 + 8.1206 + <para id="x_5c8">To illustrate how to write a style file, we will construct a 8.1207 + few by example. Rather than provide a complete style file and 8.1208 + walk through it, we'll mirror the usual process of developing a 8.1209 + style file by starting with something very simple, and walking 8.1210 + through a series of successively more complete examples.</para> 8.1211 + 8.1212 + <sect2> 8.1213 + <title>Identifying mistakes in style files</title> 8.1214 + 8.1215 + <para id="x_5c9">If Mercurial encounters a problem in a style file you are 8.1216 + working on, it prints a terse error message that, once you 8.1217 + figure out what it means, is actually quite useful.</para> 8.1218 + 8.1219 +&interaction.template.svnstyle.syntax.input; 8.1220 + 8.1221 + <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to 8.1222 + define a <literal>changeset</literal> keyword, but forgets to 8.1223 + give any content for it. When instructed to use this style 8.1224 + file, Mercurial promptly complains.</para> 8.1225 + 8.1226 + &interaction.template.svnstyle.syntax.error; 8.1227 + 8.1228 + <para id="x_5cb">This error message looks intimidating, but it is not too 8.1229 + hard to follow.</para> 8.1230 + 8.1231 + <itemizedlist> 8.1232 + <listitem><para id="x_5cc">The first component is simply Mercurial's way 8.1233 + of saying <quote>I am giving up</quote>.</para> 8.1234 + <programlisting>___abort___: broken.style:1: parse error</programlisting> 8.1235 + </listitem> 8.1236 + <listitem><para id="x_5cd">Next comes the name of the style file that 8.1237 + contains the error.</para> 8.1238 + <programlisting>abort: ___broken.style___:1: parse error</programlisting> 8.1239 + </listitem> 8.1240 + <listitem><para id="x_5ce">Following the file name is the line number 8.1241 + where the error was encountered.</para> 8.1242 + <programlisting>abort: broken.style:___1___: parse error</programlisting> 8.1243 + </listitem> 8.1244 + <listitem><para id="x_5cf">Finally, a description of what went 8.1245 + wrong.</para> 8.1246 + <programlisting>abort: broken.style:1: ___parse error___</programlisting> 8.1247 + </listitem> 8.1248 + <listitem><para id="x_5d0">The description of the problem is not always 8.1249 + clear (as in this case), but even when it is cryptic, it 8.1250 + is almost always trivial to visually inspect the offending 8.1251 + line in the style file and see what is wrong.</para> 8.1252 + </listitem> 8.1253 + </itemizedlist> 8.1254 + </sect2> 8.1255 + 8.1256 + <sect2> 8.1257 + <title>Uniquely identifying a repository</title> 8.1258 + 8.1259 + <para id="x_5d1">If you would like to be able to identify a Mercurial 8.1260 + repository <quote>fairly uniquely</quote> using a short string 8.1261 + as an identifier, you can use the first revision in the 8.1262 + repository.</para> 8.1263 + 8.1264 + &interaction.template.svnstyle.id; 8.1265 + 8.1266 + <para id="x_5d2">This is likely to be unique, and so it is 8.1267 + useful in many cases. There are a few caveats.</para> 8.1268 + <itemizedlist> 8.1269 + <listitem><para id="x_5d3">It will not work in a completely empty 8.1270 + repository, because such a repository does not have a 8.1271 + revision zero.</para> 8.1272 + </listitem> 8.1273 + <listitem><para id="x_5d4">Neither will it work in the (extremely rare) 8.1274 + case where a repository is a merge of two or more formerly 8.1275 + independent repositories, and you still have those 8.1276 + repositories around.</para> 8.1277 + </listitem></itemizedlist> 8.1278 + <para id="x_5d5">Here are some uses to which you could put this 8.1279 + identifier:</para> 8.1280 + <itemizedlist> 8.1281 + <listitem><para id="x_5d6">As a key into a table for a database that 8.1282 + manages repositories on a server.</para> 8.1283 + </listitem> 8.1284 + <listitem><para id="x_5d7">As half of a {<emphasis>repository 8.1285 + ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 8.1286 + Save this information away when you run an automated build 8.1287 + or other activity, so that you can <quote>replay</quote> 8.1288 + the build later if necessary.</para> 8.1289 + </listitem> 8.1290 + </itemizedlist> 8.1291 + </sect2> 8.1292 + 8.1293 + <sect2> 8.1294 + <title>Listing files on multiple lines</title> 8.1295 + 8.1296 + <para id="x_714">Suppose we want to list the files changed by a changeset, 8.1297 + one per line, with a little indentation before each file 8.1298 + name.</para> 8.1299 + 8.1300 + &interaction.ch10-multiline.go; 8.1301 + </sect2> 8.1302 + 8.1303 + <sect2> 8.1304 + <title>Mimicking Subversion's output</title> 8.1305 + 8.1306 + <para id="x_5d8">Let's try to emulate the default output format used by 8.1307 + another revision control tool, Subversion.</para> 8.1308 + 8.1309 + &interaction.template.svnstyle.short; 8.1310 + 8.1311 + <para id="x_5d9">Since Subversion's output style is fairly simple, it is 8.1312 + easy to copy-and-paste a hunk of its output into a file, and 8.1313 + replace the text produced above by Subversion with the 8.1314 + template values we'd like to see expanded.</para> 8.1315 + 8.1316 + &interaction.template.svnstyle.template; 8.1317 + 8.1318 + <para id="x_5da">There are a few small ways in which this template deviates 8.1319 + from the output produced by Subversion.</para> 8.1320 + <itemizedlist> 8.1321 + <listitem><para id="x_5db">Subversion prints a <quote>readable</quote> 8.1322 + date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the 8.1323 + example output above) in parentheses. Mercurial's 8.1324 + templating engine does not provide a way to display a date 8.1325 + in this format without also printing the time and time 8.1326 + zone.</para> 8.1327 + </listitem> 8.1328 + <listitem><para id="x_5dc">We emulate Subversion's printing of 8.1329 + <quote>separator</quote> lines full of 8.1330 + <quote><literal>-</literal></quote> characters by ending 8.1331 + the template with such a line. We use the templating 8.1332 + engine's <literal role="template-keyword">header</literal> 8.1333 + keyword to print a separator line as the first line of 8.1334 + output (see below), thus achieving similar output to 8.1335 + Subversion.</para> 8.1336 + </listitem> 8.1337 + <listitem><para id="x_5dd">Subversion's output includes a count in the 8.1338 + header of the number of lines in the commit message. We 8.1339 + cannot replicate this in Mercurial; the templating engine 8.1340 + does not currently provide a filter that counts the number 8.1341 + of lines the template generates.</para> 8.1342 + </listitem></itemizedlist> 8.1343 + <para id="x_5de">It took me no more than a minute or two of work to replace 8.1344 + literal text from an example of Subversion's output with some 8.1345 + keywords and filters to give the template above. The style 8.1346 + file simply refers to the template.</para> 8.1347 + 8.1348 + &interaction.template.svnstyle.style; 8.1349 + 8.1350 + <para id="x_5df">We could have included the text of the template file 8.1351 + directly in the style file by enclosing it in quotes and 8.1352 + replacing the newlines with 8.1353 + <quote><literal>\n</literal></quote> sequences, but it would 8.1354 + have made the style file too difficult to read. Readability 8.1355 + is a good guide when you're trying to decide whether some text 8.1356 + belongs in a style file, or in a template file that the style 8.1357 + file points to. If the style file will look too big or 8.1358 + cluttered if you insert a literal piece of text, drop it into 8.1359 + a template instead.</para> 8.1360 + </sect2> 8.1361 + </sect1> 8.1362 </chapter> 8.1363 8.1364 <!-- 8.1365 local variables: 8.1366 sgml-parent-document: ("00book.xml" "book" "chapter") 8.1367 end: 8.1368 ---> 8.1369 \ No newline at end of file 8.1370 +-->
9.1 --- a/fr/ch12-mq.xml Wed Sep 09 15:25:09 2009 +0200 9.2 +++ b/fr/ch12-mq.xml Wed Sep 09 16:07:36 2009 +0200 9.3 @@ -1,1309 +1,1368 @@ 9.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 9.5 9.6 -<chapter> 9.7 -<title>Managing change with Mercurial Queues</title> 9.8 -<para>\label{chap:mq}</para> 9.9 - 9.10 -<sect1> 9.11 -<title>The patch management problem</title> 9.12 -<para>\label{sec:mq:patch-mgmt}</para> 9.13 - 9.14 -<para>Here is a common scenario: you need to install a software package from 9.15 -source, but you find a bug that you must fix in the source before you 9.16 -can start using the package. You make your changes, forget about the 9.17 -package for a while, and a few months later you need to upgrade to a 9.18 -newer version of the package. If the newer version of the package 9.19 -still has the bug, you must extract your fix from the older source 9.20 -tree and apply it against the newer version. This is a tedious task, 9.21 -and it's easy to make mistakes.</para> 9.22 - 9.23 -<para>This is a simple case of the <quote>patch management</quote> problem. You have 9.24 -an <quote>upstream</quote> source tree that you can't change; you need to make 9.25 -some local changes on top of the upstream tree; and you'd like to be 9.26 -able to keep those changes separate, so that you can apply them to 9.27 -newer versions of the upstream source.</para> 9.28 - 9.29 -<para>The patch management problem arises in many situations. Probably the 9.30 -most visible is that a user of an open source software project will 9.31 -contribute a bug fix or new feature to the project's maintainers in the 9.32 -form of a patch.</para> 9.33 - 9.34 -<para>Distributors of operating systems that include open source software 9.35 -often need to make changes to the packages they distribute so that 9.36 -they will build properly in their environments.</para> 9.37 - 9.38 -<para>When you have few changes to maintain, it is easy to manage a single 9.39 -patch using the standard <command>diff</command> and <command>patch</command> programs 9.40 -(see section <xref linkend="sec:mq:patch"/> for a discussion of these tools). 9.41 -Once the number of changes grows, it starts to make sense to maintain 9.42 -patches as discrete <quote>chunks of work,</quote> so that for example a single 9.43 -patch will contain only one bug fix (the patch might modify several 9.44 -files, but it's doing <quote>only one thing</quote>), and you may have a number 9.45 -of such patches for different bugs you need fixed and local changes 9.46 -you require. In this situation, if you submit a bug fix patch to the 9.47 -upstream maintainers of a package and they include your fix in a 9.48 -subsequent release, you can simply drop that single patch when you're 9.49 -updating to the newer release.</para> 9.50 - 9.51 -<para>Maintaining a single patch against an upstream tree is a little 9.52 -tedious and error-prone, but not difficult. However, the complexity 9.53 -of the problem grows rapidly as the number of patches you have to 9.54 -maintain increases. With more than a tiny number of patches in hand, 9.55 -understanding which ones you have applied and maintaining them moves 9.56 -from messy to overwhelming.</para> 9.57 - 9.58 -<para>Fortunately, Mercurial includes a powerful extension, Mercurial Queues 9.59 -(or simply <quote>MQ</quote>), that massively simplifies the patch management 9.60 -problem. 9.61 -</para> 9.62 - 9.63 -</sect1> 9.64 -<sect1> 9.65 -<title>The prehistory of Mercurial Queues</title> 9.66 -<para>\label{sec:mq:history} 9.67 -</para> 9.68 - 9.69 -<para>During the late 1990s, several Linux kernel developers started to 9.70 -maintain <quote>patch series</quote> that modified the behaviour of the Linux 9.71 -kernel. Some of these series were focused on stability, some on 9.72 -feature coverage, and others were more speculative. 9.73 -</para> 9.74 - 9.75 -<para>The sizes of these patch series grew rapidly. In 2002, Andrew Morton 9.76 -published some shell scripts he had been using to automate the task of 9.77 -managing his patch queues. Andrew was successfully using these 9.78 -scripts to manage hundreds (sometimes thousands) of patches on top of 9.79 -the Linux kernel. 9.80 -</para> 9.81 - 9.82 -<sect2> 9.83 -<title>A patchwork quilt</title> 9.84 -<para>\label{sec:mq:quilt} 9.85 -</para> 9.86 - 9.87 -<para>In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the 9.88 -approach of Andrew's scripts and published a tool called <quote>patchwork 9.89 -quilt</quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote> 9.90 -(see <citation>gruenbacher:2005</citation> for a paper describing it). Because 9.91 -quilt substantially automated patch management, it rapidly gained a 9.92 -large following among open source software developers. 9.93 -</para> 9.94 - 9.95 -<para>Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory tree. 9.96 -To begin, you tell quilt to manage a directory tree, and tell it which 9.97 -files you want to manage; it stores away the names and contents of 9.98 -those files. To fix a bug, you create a new patch (using a single 9.99 -command), edit the files you need to fix, then <quote>refresh</quote> the patch. 9.100 -</para> 9.101 - 9.102 -<para>The refresh step causes quilt to scan the directory tree; it updates 9.103 -the patch with all of the changes you have made. You can create 9.104 -another patch on top of the first, which will track the changes 9.105 -required to modify the tree from <quote>tree with one patch applied</quote> to 9.106 -<quote>tree with two patches applied</quote>. 9.107 -</para> 9.108 - 9.109 -<para>You can <emphasis>change</emphasis> which patches are applied to the tree. If you 9.110 -<quote>pop</quote> a patch, the changes made by that patch will vanish from the 9.111 -directory tree. Quilt remembers which patches you have popped, 9.112 -though, so you can <quote>push</quote> a popped patch again, and the directory 9.113 -tree will be restored to contain the modifications in the patch. Most 9.114 -importantly, you can run the <quote>refresh</quote> command at any time, and the 9.115 -topmost applied patch will be updated. This means that you can, at 9.116 -any time, change both which patches are applied and what 9.117 -modifications those patches make. 9.118 -</para> 9.119 - 9.120 -<para>Quilt knows nothing about revision control tools, so it works equally 9.121 -well on top of an unpacked tarball or a Subversion working copy. 9.122 -</para> 9.123 - 9.124 -</sect2> 9.125 -<sect2> 9.126 -<title>From patchwork quilt to Mercurial Queues</title> 9.127 -<para>\label{sec:mq:quilt-mq} 9.128 -</para> 9.129 - 9.130 -<para>In mid-2005, Chris Mason took the features of quilt and wrote an 9.131 -extension that he called Mercurial Queues, which added quilt-like 9.132 -behaviour to Mercurial. 9.133 -</para> 9.134 - 9.135 -<para>The key difference between quilt and MQ is that quilt knows nothing 9.136 -about revision control systems, while MQ is <emphasis>integrated</emphasis> into 9.137 -Mercurial. Each patch that you push is represented as a Mercurial 9.138 -changeset. Pop a patch, and the changeset goes away. 9.139 -</para> 9.140 - 9.141 -<para>Because quilt does not care about revision control tools, it is still 9.142 -a tremendously useful piece of software to know about for situations 9.143 -where you cannot use Mercurial and MQ. 9.144 -</para> 9.145 - 9.146 -</sect2> 9.147 -</sect1> 9.148 -<sect1> 9.149 -<title>The huge advantage of MQ</title> 9.150 - 9.151 -<para>I cannot overstate the value that MQ offers through the unification of 9.152 -patches and revision control. 9.153 -</para> 9.154 - 9.155 -<para>A major reason that patches have persisted in the free software and 9.156 -open source world&emdash;in spite of the availability of increasingly 9.157 -capable revision control tools over the years&emdash;is the <emphasis>agility</emphasis> 9.158 -they offer. 9.159 -</para> 9.160 - 9.161 -<para>Traditional revision control tools make a permanent, irreversible 9.162 -record of everything that you do. While this has great value, it's 9.163 -also somewhat stifling. If you want to perform a wild-eyed 9.164 -experiment, you have to be careful in how you go about it, or you risk 9.165 -leaving unneeded&emdash;or worse, misleading or destabilising&emdash;traces of 9.166 -your missteps and errors in the permanent revision record. 9.167 -</para> 9.168 - 9.169 -<para>By contrast, MQ's marriage of distributed revision control with 9.170 -patches makes it much easier to isolate your work. Your patches live 9.171 -on top of normal revision history, and you can make them disappear or 9.172 -reappear at will. If you don't like a patch, you can drop it. If a 9.173 -patch isn't quite as you want it to be, simply fix it&emdash;as many times 9.174 -as you need to, until you have refined it into the form you desire. 9.175 -</para> 9.176 - 9.177 -<para>As an example, the integration of patches with revision control makes 9.178 -understanding patches and debugging their effects&emdash;and their 9.179 -interplay with the code they're based on&emdash;<emphasis>enormously</emphasis> easier. 9.180 -Since every applied patch has an associated changeset, you can use 9.181 -<command role="hg-cmd">hg log <emphasis>filename</emphasis></command> to see which changesets and patches 9.182 -affected a file. You can use the <literal role="hg-ext">bisect</literal> command to 9.183 -binary-search through all changesets and applied patches to see where 9.184 -a bug got introduced or fixed. You can use the <command role="hg-cmd">hg annotate</command> 9.185 -command to see which changeset or patch modified a particular line of 9.186 -a source file. And so on. 9.187 -</para> 9.188 - 9.189 -</sect1> 9.190 -<sect1> 9.191 -<title>Understanding patches</title> 9.192 -<para>\label{sec:mq:patch} 9.193 -</para> 9.194 - 9.195 -<para>Because MQ doesn't hide its patch-oriented nature, it is helpful to 9.196 -understand what patches are, and a little about the tools that work 9.197 -with them. 9.198 -</para> 9.199 - 9.200 -<para>The traditional Unix <command>diff</command> command compares two files, and 9.201 -prints a list of differences between them. The <command>patch</command> command 9.202 -understands these differences as <emphasis>modifications</emphasis> to make to a 9.203 -file. Take a look at figure <xref linkend="ex:mq:diff"/> for a simple example of 9.204 -these commands in action. 9.205 -</para> 9.206 - 9.207 -<informalfigure> 9.208 -<para> <!-- &interaction.mq.dodiff.diff; --> 9.209 - <caption><para>Simple uses of the <command>diff</para></caption> and \command{patch</command> commands} 9.210 - \label{ex:mq:diff} 9.211 -</para> 9.212 -</informalfigure> 9.213 - 9.214 -<para>The type of file that <command>diff</command> generates (and <command>patch</command> 9.215 -takes as input) is called a <quote>patch</quote> or a <quote>diff</quote>; there is no 9.216 -difference between a patch and a diff. (We'll use the term <quote>patch</quote>, 9.217 -since it's more commonly used.) 9.218 -</para> 9.219 - 9.220 -<para>A patch file can start with arbitrary text; the <command>patch</command> 9.221 -command ignores this text, but MQ uses it as the commit message when 9.222 -creating changesets. To find the beginning of the patch content, 9.223 -<command>patch</command> searches for the first line that starts with the 9.224 -string <quote><literal>diff -</literal></quote>. 9.225 -</para> 9.226 - 9.227 -<para>MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> can accept several 9.228 -other diff formats, but MQ doesn't). A unified diff contains two 9.229 -kinds of header. The <emphasis>file header</emphasis> describes the file being 9.230 -modified; it contains the name of the file to modify. When 9.231 -<command>patch</command> sees a new file header, it looks for a file with that 9.232 -name to start modifying. 9.233 -</para> 9.234 - 9.235 -<para>After the file header comes a series of <emphasis>hunks</emphasis>. Each hunk 9.236 -starts with a header; this identifies the range of line numbers within 9.237 -the file that the hunk should modify. Following the header, a hunk 9.238 -starts and ends with a few (usually three) lines of text from the 9.239 -unmodified file; these are called the <emphasis>context</emphasis> for the hunk. If 9.240 -there's only a small amount of context between successive hunks, 9.241 -<command>diff</command> doesn't print a new hunk header; it just runs the hunks 9.242 -together, with a few lines of context between modifications. 9.243 -</para> 9.244 - 9.245 -<para>Each line of context begins with a space character. Within the hunk, 9.246 -a line that begins with <quote><literal>-</literal></quote> means <quote>remove this line,</quote> 9.247 -while a line that begins with <quote><literal>+</literal></quote> means <quote>insert this 9.248 -line.</quote> For example, a line that is modified is represented by one 9.249 -deletion and one insertion. 9.250 -</para> 9.251 - 9.252 -<para>We will return to some of the more subtle aspects of patches later (in 9.253 -section <xref linkend="sec:mq:adv-patch"/>), but you should have enough information 9.254 -now to use MQ. 9.255 -</para> 9.256 - 9.257 -</sect1> 9.258 -<sect1> 9.259 -<title>Getting started with Mercurial Queues</title> 9.260 -<para>\label{sec:mq:start} 9.261 -</para> 9.262 - 9.263 -<para>Because MQ is implemented as an extension, you must explicitly enable 9.264 -before you can use it. (You don't need to download anything; MQ ships 9.265 -with the standard Mercurial distribution.) To enable MQ, edit your 9.266 -<filename role="home">~/.hgrc</filename> file, and add the lines in figure <xref linkend="ex:mq:config"/>. 9.267 -</para> 9.268 - 9.269 -<informalfigure> 9.270 -<programlisting> 9.271 -<para> [extensions] 9.272 - hgext.mq = 9.273 -</para> 9.274 -</programlisting> 9.275 -<para> \label{ex:mq:config} 9.276 - <caption><para>Contents to add to <filename role="home">~/.hgrc</para></caption> to enable the MQ extension</filename> 9.277 -</para> 9.278 -</informalfigure> 9.279 - 9.280 -<para>Once the extension is enabled, it will make a number of new commands 9.281 -available. To verify that the extension is working, you can use 9.282 -<command role="hg-cmd">hg help</command> to see if the <command role="hg-ext-mq">qinit</command> command is now available; see 9.283 -the example in figure <xref linkend="ex:mq:enabled"/>. 9.284 -</para> 9.285 - 9.286 -<informalfigure> 9.287 -<para> <!-- &interaction.mq.qinit-help.help; --> 9.288 - <caption><para>How to verify that MQ is enabled</para></caption> 9.289 - \label{ex:mq:enabled} 9.290 -</para> 9.291 -</informalfigure> 9.292 - 9.293 -<para>You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its commands 9.294 -only operate within that repository. To get started, simply prepare 9.295 -the repository using the <command role="hg-ext-mq">qinit</command> command (see 9.296 -figure <xref linkend="ex:mq:qinit"/>). This command creates an empty directory 9.297 -called <filename role="special" class="directory">.hg/patches</filename>, where MQ will keep its metadata. As 9.298 -with many Mercurial commands, the <command role="hg-ext-mq">qinit</command> command prints nothing 9.299 -if it succeeds. 9.300 -</para> 9.301 - 9.302 -<informalfigure> 9.303 -<para> <!-- &interaction.mq.tutorial.qinit; --> 9.304 - <caption><para>Preparing a repository for use with MQ</para></caption> 9.305 - \label{ex:mq:qinit} 9.306 -</para> 9.307 -</informalfigure> 9.308 - 9.309 -<informalfigure> 9.310 -<para> <!-- &interaction.mq.tutorial.qnew; --> 9.311 - <caption><para>Creating a new patch</para></caption> 9.312 - \label{ex:mq:qnew} 9.313 -</para> 9.314 -</informalfigure> 9.315 - 9.316 -<sect2> 9.317 -<title>Creating a new patch</title> 9.318 - 9.319 -<para>To begin work on a new patch, use the <command role="hg-ext-mq">qnew</command> command. This 9.320 -command takes one argument, the name of the patch to create. MQ will 9.321 -use this as the name of an actual file in the <filename role="special" class="directory">.hg/patches</filename> 9.322 -directory, as you can see in figure <xref linkend="ex:mq:qnew"/>. 9.323 -</para> 9.324 - 9.325 -<para>Also newly present in the <filename role="special" class="directory">.hg/patches</filename> directory are two 9.326 -other files, <filename role="special">series</filename> and <filename role="special">status</filename>. The 9.327 -<filename role="special">series</filename> file lists all of the patches that MQ knows about 9.328 -for this repository, with one patch per line. Mercurial uses the 9.329 -<filename role="special">status</filename> file for internal book-keeping; it tracks all of the 9.330 -patches that MQ has <emphasis>applied</emphasis> in this repository. 9.331 -</para> 9.332 - 9.333 -<note> 9.334 -<para> You may sometimes want to edit the <filename role="special">series</filename> file by hand; 9.335 - for example, to change the sequence in which some patches are 9.336 - applied. However, manually editing the <filename role="special">status</filename> file is 9.337 - almost always a bad idea, as it's easy to corrupt MQ's idea of what 9.338 - is happening. 9.339 -</para> 9.340 -</note> 9.341 - 9.342 -<para>Once you have created your new patch, you can edit files in the 9.343 -working directory as you usually would. All of the normal Mercurial 9.344 -commands, such as <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg annotate</command>, work exactly as 9.345 -they did before. 9.346 -</para> 9.347 - 9.348 -</sect2> 9.349 -<sect2> 9.350 -<title>Refreshing a patch</title> 9.351 - 9.352 -<para>When you reach a point where you want to save your work, use the 9.353 -<command role="hg-ext-mq">qrefresh</command> command (figure <xref linkend="ex:mq:qnew"/>) to update the patch 9.354 -you are working on. This command folds the changes you have made in 9.355 -the working directory into your patch, and updates its corresponding 9.356 -changeset to contain those changes. 9.357 -</para> 9.358 - 9.359 -<informalfigure> 9.360 -<para> <!-- &interaction.mq.tutorial.qrefresh; --> 9.361 - <caption><para>Refreshing a patch</para></caption> 9.362 - \label{ex:mq:qrefresh} 9.363 -</para> 9.364 -</informalfigure> 9.365 - 9.366 -<para>You can run <command role="hg-ext-mq">qrefresh</command> as often as you like, so it's a good way 9.367 -to <quote>checkpoint</quote> your work. Refresh your patch at an opportune 9.368 -time; try an experiment; and if the experiment doesn't work out, 9.369 -<command role="hg-cmd">hg revert</command> your modifications back to the last time you refreshed. 9.370 -</para> 9.371 - 9.372 -<informalfigure> 9.373 -<para> <!-- &interaction.mq.tutorial.qrefresh2; --> 9.374 - <caption><para>Refresh a patch many times to accumulate changes</para></caption> 9.375 - \label{ex:mq:qrefresh2} 9.376 -</para> 9.377 -</informalfigure> 9.378 - 9.379 -</sect2> 9.380 -<sect2> 9.381 -<title>Stacking and tracking patches</title> 9.382 - 9.383 -<para>Once you have finished working on a patch, or need to work on another, 9.384 -you can use the <command role="hg-ext-mq">qnew</command> command again to create a new patch. 9.385 -Mercurial will apply this patch on top of your existing patch. See 9.386 -figure <xref linkend="ex:mq:qnew2"/> for an example. Notice that the patch 9.387 -contains the changes in our prior patch as part of its context (you 9.388 -can see this more clearly in the output of <command role="hg-cmd">hg annotate</command>). 9.389 -</para> 9.390 - 9.391 -<informalfigure> 9.392 -<para> <!-- &interaction.mq.tutorial.qnew2; --> 9.393 - <caption><para>Stacking a second patch on top of the first</para></caption> 9.394 - \label{ex:mq:qnew2} 9.395 -</para> 9.396 -</informalfigure> 9.397 - 9.398 -<para>So far, with the exception of <command role="hg-ext-mq">qnew</command> and <command role="hg-ext-mq">qrefresh</command>, we've 9.399 -been careful to only use regular Mercurial commands. However, MQ 9.400 -provides many commands that are easier to use when you are thinking 9.401 -about patches, as illustrated in figure <xref linkend="ex:mq:qseries"/>: 9.402 -</para> 9.403 - 9.404 -<itemizedlist> 9.405 -<listitem><para>The <command role="hg-ext-mq">qseries</command> command lists every patch that MQ knows 9.406 - about in this repository, from oldest to newest (most recently 9.407 - <emphasis>created</emphasis>). 9.408 -</para> 9.409 -</listitem> 9.410 -<listitem><para>The <command role="hg-ext-mq">qapplied</command> command lists every patch that MQ has 9.411 - <emphasis>applied</emphasis> in this repository, again from oldest to newest (most 9.412 - recently applied). 9.413 -</para> 9.414 -</listitem></itemizedlist> 9.415 - 9.416 -<informalfigure> 9.417 -<para> <!-- &interaction.mq.tutorial.qseries; --> 9.418 - \caption{Understanding the patch stack with <command role="hg-ext-mq">qseries</command> and 9.419 - <command role="hg-ext-mq">qapplied</command>} 9.420 - \label{ex:mq:qseries} 9.421 -</para> 9.422 -</informalfigure> 9.423 - 9.424 -</sect2> 9.425 -<sect2> 9.426 -<title>Manipulating the patch stack</title> 9.427 - 9.428 -<para>The previous discussion implied that there must be a difference 9.429 -between <quote>known</quote> and <quote>applied</quote> patches, and there is. MQ can 9.430 -manage a patch without it being applied in the repository. 9.431 -</para> 9.432 - 9.433 -<para>An <emphasis>applied</emphasis> patch has a corresponding changeset in the 9.434 -repository, and the effects of the patch and changeset are visible in 9.435 -the working directory. You can undo the application of a patch using 9.436 -the <command role="hg-ext-mq">qpop</command> command. MQ still <emphasis>knows about</emphasis>, or manages, a 9.437 -popped patch, but the patch no longer has a corresponding changeset in 9.438 -the repository, and the working directory does not contain the changes 9.439 -made by the patch. Figure <xref linkend="fig:mq:stack"/> illustrates the 9.440 -difference between applied and tracked patches. 9.441 -</para> 9.442 - 9.443 -<informalfigure> 9.444 - 9.445 -<para> <mediaobject><imageobject><imagedata fileref="mq-stack"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 9.446 - <caption><para>Applied and unapplied patches in the MQ patch stack</para></caption> 9.447 - \label{fig:mq:stack} 9.448 -</para> 9.449 -</informalfigure> 9.450 - 9.451 -<para>You can reapply an unapplied, or popped, patch using the <command role="hg-ext-mq">qpush</command> 9.452 -command. This creates a new changeset to correspond to the patch, and 9.453 -the patch's changes once again become present in the working 9.454 -directory. See figure <xref linkend="ex:mq:qpop"/> for examples of <command role="hg-ext-mq">qpop</command> 9.455 -and <command role="hg-ext-mq">qpush</command> in action. Notice that once we have popped a patch 9.456 -or two patches, the output of <command role="hg-ext-mq">qseries</command> remains the same, while 9.457 -that of <command role="hg-ext-mq">qapplied</command> has changed. 9.458 -</para> 9.459 - 9.460 -<informalfigure> 9.461 -<para> <!-- &interaction.mq.tutorial.qpop; --> 9.462 - <caption><para>Modifying the stack of applied patches</para></caption> 9.463 - \label{ex:mq:qpop} 9.464 -</para> 9.465 -</informalfigure> 9.466 - 9.467 -</sect2> 9.468 -<sect2> 9.469 -<title>Pushing and popping many patches</title> 9.470 - 9.471 -<para>While <command role="hg-ext-mq">qpush</command> and <command role="hg-ext-mq">qpop</command> each operate on a single patch at 9.472 -a time by default, you can push and pop many patches in one go. The 9.473 -<option role="hg-ext-mq-cmd-qpush-opt">-a</option> option to <command role="hg-ext-mq">qpush</command> causes it to push all 9.474 -unapplied patches, while the <option role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command role="hg-ext-mq">qpop</command> 9.475 -causes it to pop all applied patches. (For some more ways to push and 9.476 -pop many patches, see section <xref linkend="sec:mq:perf"/> below.) 9.477 -</para> 9.478 - 9.479 -<informalfigure> 9.480 -<para> <!-- &interaction.mq.tutorial.qpush-a; --> 9.481 - <caption><para>Pushing all unapplied patches</para></caption> 9.482 - \label{ex:mq:qpush-a} 9.483 -</para> 9.484 -</informalfigure> 9.485 - 9.486 -</sect2> 9.487 -<sect2> 9.488 -<title>Safety checks, and overriding them</title> 9.489 - 9.490 -<para>Several MQ commands check the working directory before they do 9.491 -anything, and fail if they find any modifications. They do this to 9.492 -ensure that you won't lose any changes that you have made, but not yet 9.493 -incorporated into a patch. Figure <xref linkend="ex:mq:add"/> illustrates this; 9.494 -the <command role="hg-ext-mq">qnew</command> command will not create a new patch if there are 9.495 -outstanding changes, caused in this case by the <command role="hg-cmd">hg add</command> of 9.496 -<filename>file3</filename>. 9.497 -</para> 9.498 - 9.499 -<informalfigure> 9.500 -<para> <!-- &interaction.mq.tutorial.add; --> 9.501 - <caption><para>Forcibly creating a patch</para></caption> 9.502 - \label{ex:mq:add} 9.503 -</para> 9.504 -</informalfigure> 9.505 - 9.506 -<para>Commands that check the working directory all take an <quote>I know what 9.507 -I'm doing</quote> option, which is always named <option>-f</option>. The exact 9.508 -meaning of <option>-f</option> depends on the command. For example, 9.509 -<command role="hg-cmd">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">-f</option></command> will incorporate any outstanding 9.510 -changes into the new patch it creates, but 9.511 -<command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-f</option></command> will revert modifications to any 9.512 -files affected by the patch that it is popping. Be sure to read the 9.513 -documentation for a command's <option>-f</option> option before you use it! 9.514 -</para> 9.515 - 9.516 -</sect2> 9.517 -<sect2> 9.518 -<title>Working on several patches at once</title> 9.519 - 9.520 -<para>The <command role="hg-ext-mq">qrefresh</command> command always refreshes the <emphasis>topmost</emphasis> 9.521 -applied patch. This means that you can suspend work on one patch (by 9.522 -refreshing it), pop or push to make a different patch the top, and 9.523 -work on <emphasis>that</emphasis> patch for a while. 9.524 -</para> 9.525 - 9.526 -<para>Here's an example that illustrates how you can use this ability. 9.527 -Let's say you're developing a new feature as two patches. The first 9.528 -is a change to the core of your software, and the second&emdash;layered on 9.529 -top of the first&emdash;changes the user interface to use the code you just 9.530 -added to the core. If you notice a bug in the core while you're 9.531 -working on the UI patch, it's easy to fix the core. Simply 9.532 -<command role="hg-ext-mq">qrefresh</command> the UI patch to save your in-progress changes, and 9.533 -<command role="hg-ext-mq">qpop</command> down to the core patch. Fix the core bug, 9.534 -<command role="hg-ext-mq">qrefresh</command> the core patch, and <command role="hg-ext-mq">qpush</command> back to the UI 9.535 -patch to continue where you left off. 9.536 -</para> 9.537 - 9.538 -</sect2> 9.539 -</sect1> 9.540 -<sect1> 9.541 -<title>More about patches</title> 9.542 -<para>\label{sec:mq:adv-patch} 9.543 -</para> 9.544 - 9.545 -<para>MQ uses the GNU <command>patch</command> command to apply patches, so it's 9.546 -helpful to know a few more detailed aspects of how <command>patch</command> 9.547 -works, and about patches themselves. 9.548 -</para> 9.549 - 9.550 -<sect2> 9.551 -<title>The strip count</title> 9.552 - 9.553 -<para>If you look at the file headers in a patch, you will notice that the 9.554 -pathnames usually have an extra component on the front that isn't 9.555 -present in the actual path name. This is a holdover from the way that 9.556 -people used to generate patches (people still do this, but it's 9.557 -somewhat rare with modern revision control tools). 9.558 -</para> 9.559 - 9.560 -<para>Alice would unpack a tarball, edit her files, then decide that she 9.561 -wanted to create a patch. So she'd rename her working directory, 9.562 -unpack the tarball again (hence the need for the rename), and use the 9.563 -<option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to <command>diff</command> to 9.564 -recursively generate a patch between the unmodified directory and the 9.565 -modified one. The result would be that the name of the unmodified 9.566 -directory would be at the front of the left-hand path in every file 9.567 -header, and the name of the modified directory would be at the front 9.568 -of the right-hand path. 9.569 -</para> 9.570 - 9.571 -<para>Since someone receiving a patch from the Alices of the net would be 9.572 -unlikely to have unmodified and modified directories with exactly the 9.573 -same names, the <command>patch</command> command has a <option role="cmd-opt-patch">-p</option> 9.574 -option that indicates the number of leading path name components to 9.575 -strip when trying to apply a patch. This number is called the 9.576 -<emphasis>strip count</emphasis>. 9.577 -</para> 9.578 - 9.579 -<para>An option of <quote><literal>-p1</literal></quote> means <quote>use a strip count of one</quote>. If 9.580 -<command>patch</command> sees a file name <filename>foo/bar/baz</filename> in a file 9.581 -header, it will strip <filename>foo</filename> and try to patch a file named 9.582 -<filename>bar/baz</filename>. (Strictly speaking, the strip count refers to the 9.583 -number of <emphasis>path separators</emphasis> (and the components that go with them 9.584 -) to strip. A strip count of one will turn <filename>foo/bar</filename> into 9.585 -<filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra leading 9.586 -slash) into <filename>foo/bar</filename>.) 9.587 -</para> 9.588 - 9.589 -<para>The <quote>standard</quote> strip count for patches is one; almost all patches 9.590 -contain one leading path name component that needs to be stripped. 9.591 -Mercurial's <command role="hg-cmd">hg diff</command> command generates path names in this form, 9.592 -and the <command role="hg-cmd">hg import</command> command and MQ expect patches to have a strip 9.593 -count of one. 9.594 -</para> 9.595 - 9.596 -<para>If you receive a patch from someone that you want to add to your patch 9.597 -queue, and the patch needs a strip count other than one, you cannot 9.598 -just <command role="hg-ext-mq">qimport</command> the patch, because <command role="hg-ext-mq">qimport</command> does not yet 9.599 -have a <literal>-p</literal> option (see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue 311</ulink>). Your best bet is to 9.600 -<command role="hg-ext-mq">qnew</command> a patch of your own, then use <command>patch -p<emphasis>N</emphasis></command> 9.601 -to apply their patch, followed by <command role="hg-cmd">hg addremove</command> to pick up any 9.602 -files added or removed by the patch, followed by <command role="hg-ext-mq">qrefresh</command>. 9.603 -This complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue 311</ulink> for details. 9.604 -</sect2> 9.605 -<sect2> 9.606 -<title>Strategies for applying a patch</title> 9.607 -</para> 9.608 - 9.609 -<para>When <command>patch</command> applies a hunk, it tries a handful of 9.610 -successively less accurate strategies to try to make the hunk apply. 9.611 -This falling-back technique often makes it possible to take a patch 9.612 -that was generated against an old version of a file, and apply it 9.613 -against a newer version of that file. 9.614 -</para> 9.615 - 9.616 -<para>First, <command>patch</command> tries an exact match, where the line numbers, 9.617 -the context, and the text to be modified must apply exactly. If it 9.618 -cannot make an exact match, it tries to find an exact match for the 9.619 -context, without honouring the line numbering information. If this 9.620 -succeeds, it prints a line of output saying that the hunk was applied, 9.621 -but at some <emphasis>offset</emphasis> from the original line number. 9.622 -</para> 9.623 - 9.624 -<para>If a context-only match fails, <command>patch</command> removes the first and 9.625 -last lines of the context, and tries a <emphasis>reduced</emphasis> context-only 9.626 -match. If the hunk with reduced context succeeds, it prints a message 9.627 -saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the number 9.628 -after the fuzz factor indicates how many lines of context 9.629 -<command>patch</command> had to trim before the patch applied). 9.630 -</para> 9.631 - 9.632 -<para>When neither of these techniques works, <command>patch</command> prints a 9.633 -message saying that the hunk in question was rejected. It saves 9.634 -rejected hunks (also simply called <quote>rejects</quote>) to a file with the 9.635 -same name, and an added <filename role="special">.rej</filename> extension. It also saves an 9.636 -unmodified copy of the file with a <filename role="special">.orig</filename> extension; the 9.637 -copy of the file without any extensions will contain any changes made 9.638 -by hunks that <emphasis>did</emphasis> apply cleanly. If you have a patch that 9.639 -modifies <filename>foo</filename> with six hunks, and one of them fails to 9.640 -apply, you will have: an unmodified <filename>foo.orig</filename>, a 9.641 -<filename>foo.rej</filename> containing one hunk, and <filename>foo</filename>, containing 9.642 -the changes made by the five successful hunks. 9.643 -</para> 9.644 - 9.645 -</sect2> 9.646 -<sect2> 9.647 -<title>Some quirks of patch representation</title> 9.648 - 9.649 -<para>There are a few useful things to know about how <command>patch</command> works 9.650 -with files. 9.651 -</para> 9.652 -<itemizedlist> 9.653 -<listitem><para>This should already be obvious, but <command>patch</command> cannot 9.654 - handle binary files. 9.655 -</para> 9.656 -</listitem> 9.657 -<listitem><para>Neither does it care about the executable bit; it creates new 9.658 - files as readable, but not executable. 9.659 -</para> 9.660 -</listitem> 9.661 -<listitem><para><command>patch</command> treats the removal of a file as a diff between 9.662 - the file to be removed and the empty file. So your idea of <quote>I 9.663 - deleted this file</quote> looks like <quote>every line of this file was 9.664 - deleted</quote> in a patch. 9.665 -</para> 9.666 -</listitem> 9.667 -<listitem><para>It treats the addition of a file as a diff between the empty 9.668 - file and the file to be added. So in a patch, your idea of <quote>I 9.669 - added this file</quote> looks like <quote>every line of this file was added</quote>. 9.670 -</para> 9.671 -</listitem> 9.672 -<listitem><para>It treats a renamed file as the removal of the old name, and the 9.673 - addition of the new name. This means that renamed files have a big 9.674 - footprint in patches. (Note also that Mercurial does not currently 9.675 - try to infer when files have been renamed or copied in a patch.) 9.676 -</para> 9.677 -</listitem> 9.678 -<listitem><para><command>patch</command> cannot represent empty files, so you cannot use 9.679 - a patch to represent the notion <quote>I added this empty file to the 9.680 - tree</quote>. 9.681 -</para> 9.682 -</listitem></itemizedlist> 9.683 -</sect2> 9.684 -<sect2> 9.685 -<title>Beware the fuzz</title> 9.686 - 9.687 -<para>While applying a hunk at an offset, or with a fuzz factor, will often 9.688 -be completely successful, these inexact techniques naturally leave 9.689 -open the possibility of corrupting the patched file. The most common 9.690 -cases typically involve applying a patch twice, or at an incorrect 9.691 -location in the file. If <command>patch</command> or <command role="hg-ext-mq">qpush</command> ever 9.692 -mentions an offset or fuzz factor, you should make sure that the 9.693 -modified files are correct afterwards. 9.694 -</para> 9.695 - 9.696 -<para>It's often a good idea to refresh a patch that has applied with an 9.697 -offset or fuzz factor; refreshing the patch generates new context 9.698 -information that will make it apply cleanly. I say <quote>often,</quote> not 9.699 -<quote>always,</quote> because sometimes refreshing a patch will make it fail to 9.700 -apply against a different revision of the underlying files. In some 9.701 -cases, such as when you're maintaining a patch that must sit on top of 9.702 -multiple versions of a source tree, it's acceptable to have a patch 9.703 -apply with some fuzz, provided you've verified the results of the 9.704 -patching process in such cases. 9.705 -</para> 9.706 - 9.707 -</sect2> 9.708 -<sect2> 9.709 -<title>Handling rejection</title> 9.710 - 9.711 -<para>If <command role="hg-ext-mq">qpush</command> fails to apply a patch, it will print an error 9.712 -message and exit. If it has left <filename role="special">.rej</filename> files behind, it is 9.713 -usually best to fix up the rejected hunks before you push more patches 9.714 -or do any further work. 9.715 -</para> 9.716 - 9.717 -<para>If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does because 9.718 -you've changed the underlying code that your patches are based on, 9.719 -Mercurial Queues can help; see section <xref linkend="sec:mq:merge"/> for details. 9.720 -</para> 9.721 - 9.722 -<para>Unfortunately, there aren't any great techniques for dealing with 9.723 -rejected hunks. Most often, you'll need to view the <filename role="special">.rej</filename> 9.724 -file and edit the target file, applying the rejected hunks by hand. 9.725 -</para> 9.726 - 9.727 -<para>If you're feeling adventurous, Neil Brown, a Linux kernel hacker, 9.728 -wrote a tool called <command>wiggle</command> <citation>web:wiggle</citation>, which is more 9.729 -vigorous than <command>patch</command> in its attempts to make a patch apply. 9.730 -</para> 9.731 - 9.732 -<para>Another Linux kernel hacker, Chris Mason (the author of Mercurial 9.733 -Queues), wrote a similar tool called 9.734 -<command>mpatch</command> <citation>web:mpatch</citation>, which takes a simple approach to 9.735 -automating the application of hunks rejected by <command>patch</command>. The 9.736 -<command>mpatch</command> command can help with four common reasons that a hunk 9.737 -may be rejected: 9.738 -</para> 9.739 - 9.740 -<itemizedlist> 9.741 -<listitem><para>The context in the middle of a hunk has changed. 9.742 -</para> 9.743 -</listitem> 9.744 -<listitem><para>A hunk is missing some context at the beginning or end. 9.745 -</para> 9.746 -</listitem> 9.747 -<listitem><para>A large hunk might apply better&emdash;either entirely or in 9.748 - part&emdash;if it was broken up into smaller hunks. 9.749 -</para> 9.750 -</listitem> 9.751 -<listitem><para>A hunk removes lines with slightly different content than those 9.752 - currently present in the file. 9.753 -</para> 9.754 -</listitem></itemizedlist> 9.755 - 9.756 -<para>If you use <command>wiggle</command> or <command>mpatch</command>, you should be doubly 9.757 -careful to check your results when you're done. In fact, 9.758 -<command>mpatch</command> enforces this method of double-checking the tool's 9.759 -output, by automatically dropping you into a merge program when it has 9.760 -done its job, so that you can verify its work and finish off any 9.761 -remaining merges. 9.762 -</para> 9.763 - 9.764 -</sect2> 9.765 -</sect1> 9.766 -<sect1> 9.767 -<title>Getting the best performance out of MQ</title> 9.768 -<para>\label{sec:mq:perf} 9.769 -</para> 9.770 - 9.771 -<para>MQ is very efficient at handling a large number of patches. I ran 9.772 -some performance experiments in mid-2006 for a talk that I gave at the 9.773 -2006 EuroPython conference <citation>web:europython</citation>. I used as my data 9.774 -set the Linux 2.6.17-mm1 patch series, which consists of 1,738 9.775 -patches. I applied these on top of a Linux kernel repository 9.776 -containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux 9.777 -2.6.17. 9.778 -</para> 9.779 - 9.780 -<para>On my old, slow laptop, I was able to 9.781 -<command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-a</option></command> all 1,738 patches in 3.5 minutes, 9.782 -and <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> them all in 30 seconds. (On a 9.783 -newer laptop, the time to push all patches dropped to two minutes.) I 9.784 -could <command role="hg-ext-mq">qrefresh</command> one of the biggest patches (which made 22,779 9.785 -lines of changes to 287 files) in 6.6 seconds. 9.786 -</para> 9.787 - 9.788 -<para>Clearly, MQ is well suited to working in large trees, but there are a 9.789 -few tricks you can use to get the best performance of it. 9.790 -</para> 9.791 - 9.792 -<para>First of all, try to <quote>batch</quote> operations together. Every time you 9.793 -run <command role="hg-ext-mq">qpush</command> or <command role="hg-ext-mq">qpop</command>, these commands scan the working 9.794 -directory once to make sure you haven't made some changes and then 9.795 -forgotten to run <command role="hg-ext-mq">qrefresh</command>. On a small tree, the time that 9.796 -this scan takes is unnoticeable. However, on a medium-sized tree 9.797 -(containing tens of thousands of files), it can take a second or more. 9.798 -</para> 9.799 - 9.800 -<para>The <command role="hg-ext-mq">qpush</command> and <command role="hg-ext-mq">qpop</command> commands allow you to push and pop 9.801 -multiple patches at a time. You can identify the <quote>destination 9.802 -patch</quote> that you want to end up at. When you <command role="hg-ext-mq">qpush</command> with a 9.803 -destination specified, it will push patches until that patch is at the 9.804 -top of the applied stack. When you <command role="hg-ext-mq">qpop</command> to a destination, MQ 9.805 -will pop patches until the destination patch is at the top. 9.806 -</para> 9.807 - 9.808 -<para>You can identify a destination patch using either the name of the 9.809 -patch, or by number. If you use numeric addressing, patches are 9.810 -counted from zero; this means that the first patch is zero, the second 9.811 -is one, and so on. 9.812 -</para> 9.813 - 9.814 -</sect1> 9.815 -<sect1> 9.816 -<title>Updating your patches when the underlying code changes</title> 9.817 -<para>\label{sec:mq:merge} 9.818 -</para> 9.819 - 9.820 -<para>It's common to have a stack of patches on top of an underlying 9.821 -repository that you don't modify directly. If you're working on 9.822 -changes to third-party code, or on a feature that is taking longer to 9.823 -develop than the rate of change of the code beneath, you will often 9.824 -need to sync up with the underlying code, and fix up any hunks in your 9.825 -patches that no longer apply. This is called <emphasis>rebasing</emphasis> your 9.826 -patch series. 9.827 -</para> 9.828 - 9.829 -<para>The simplest way to do this is to <command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> 9.830 -your patches, then <command role="hg-cmd">hg pull</command> changes into the underlying 9.831 -repository, and finally <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your 9.832 -patches again. MQ will stop pushing any time it runs across a patch 9.833 -that fails to apply during conflicts, allowing you to fix your 9.834 -conflicts, <command role="hg-ext-mq">qrefresh</command> the affected patch, and continue pushing 9.835 -until you have fixed your entire stack. 9.836 -</para> 9.837 - 9.838 -<para>This approach is easy to use and works well if you don't expect 9.839 -changes to the underlying code to affect how well your patches apply. 9.840 -If your patch stack touches code that is modified frequently or 9.841 -invasively in the underlying repository, however, fixing up rejected 9.842 -hunks by hand quickly becomes tiresome. 9.843 -</para> 9.844 - 9.845 -<para>It's possible to partially automate the rebasing process. If your 9.846 -patches apply cleanly against some revision of the underlying repo, MQ 9.847 -can use this information to help you to resolve conflicts between your 9.848 -patches and a different revision. 9.849 -</para> 9.850 - 9.851 -<para>The process is a little involved. 9.852 -</para> 9.853 -<orderedlist> 9.854 -<listitem><para>To begin, <command role="hg-cmd">hg qpush -a</command> all of your patches on top of 9.855 - the revision where you know that they apply cleanly. 9.856 -</para> 9.857 -</listitem> 9.858 -<listitem><para>Save a backup copy of your patch directory using 9.859 - <command role="hg-cmd">hg qsave <option role="hg-ext-mq-cmd-qsave-opt">-e</option> <option role="hg-ext-mq-cmd-qsave-opt">-c</option></command>. This prints 9.860 - the name of the directory that it has saved the patches in. It will 9.861 - save the patches to a directory called 9.862 - <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>, where <literal><emphasis>N</emphasis></literal> is a small 9.863 - integer. It also commits a <quote>save changeset</quote> on top of your 9.864 - applied patches; this is for internal book-keeping, and records the 9.865 - states of the <filename role="special">series</filename> and <filename role="special">status</filename> files. 9.866 -</para> 9.867 -</listitem> 9.868 -<listitem><para>Use <command role="hg-cmd">hg pull</command> to bring new changes into the underlying 9.869 - repository. (Don't run <command role="hg-cmd">hg pull -u</command>; see below for why.) 9.870 -</para> 9.871 -</listitem> 9.872 -<listitem><para>Update to the new tip revision, using 9.873 - <command role="hg-cmd">hg update <option role="hg-opt-update">-C</option></command> to override the patches you 9.874 - have pushed. 9.875 -</para> 9.876 -</listitem> 9.877 -<listitem><para>Merge all patches using \hgcmdargs{qpush}{<option role="hg-ext-mq-cmd-qpush-opt">-m</option> 9.878 - <option role="hg-ext-mq-cmd-qpush-opt">-a</option>}. The <option role="hg-ext-mq-cmd-qpush-opt">-m</option> option to <command role="hg-ext-mq">qpush</command> 9.879 - tells MQ to perform a three-way merge if the patch fails to apply. 9.880 -</para> 9.881 -</listitem></orderedlist> 9.882 - 9.883 -<para>During the <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-m</option></command>, each patch in the 9.884 -<filename role="special">series</filename> file is applied normally. If a patch applies with 9.885 -fuzz or rejects, MQ looks at the queue you <command role="hg-ext-mq">qsave</command>d, and 9.886 -performs a three-way merge with the corresponding changeset. This 9.887 -merge uses Mercurial's normal merge machinery, so it may pop up a GUI 9.888 -merge tool to help you to resolve problems. 9.889 -</para> 9.890 - 9.891 -<para>When you finish resolving the effects of a patch, MQ refreshes your 9.892 -patch based on the result of the merge. 9.893 -</para> 9.894 - 9.895 -<para>At the end of this process, your repository will have one extra head 9.896 -from the old patch queue, and a copy of the old patch queue will be in 9.897 -<filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>. You can remove the extra head using 9.898 -<command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option> <option role="hg-ext-mq-cmd-qpop-opt">-n</option> patches.<emphasis>N</emphasis></command> 9.899 -or <command role="hg-cmd">hg strip</command>. You can delete <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis> once 9.900 -you are sure that you no longer need it as a backup. 9.901 -</para> 9.902 - 9.903 -</sect1> 9.904 -<sect1> 9.905 -<title>Identifying patches</title> 9.906 - 9.907 -<para>MQ commands that work with patches let you refer to a patch either by 9.908 -using its name or by a number. By name is obvious enough; pass the 9.909 -name <filename>foo.patch</filename> to <command role="hg-ext-mq">qpush</command>, for example, and it will 9.910 -push patches until <filename>foo.patch</filename> is applied. 9.911 -</para> 9.912 - 9.913 -<para>As a shortcut, you can refer to a patch using both a name and a 9.914 -numeric offset; <literal>foo.patch-2</literal> means <quote>two patches before 9.915 -<literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> means <quote>four patches 9.916 -after <literal>bar.patch</literal></quote>. 9.917 -</para> 9.918 - 9.919 -<para>Referring to a patch by index isn't much different. The first patch 9.920 -printed in the output of <command role="hg-ext-mq">qseries</command> is patch zero (yes, it's one 9.921 -of those start-at-zero counting systems); the second is patch one; and 9.922 -so on. 9.923 -</para> 9.924 - 9.925 -<para>MQ also makes it easy to work with patches when you are using normal 9.926 -Mercurial commands. Every command that accepts a changeset ID will 9.927 -also accept the name of an applied patch. MQ augments the tags 9.928 -normally in the repository with an eponymous one for each applied 9.929 -patch. In addition, the special tags \index{tags!special tag 9.930 - names!<literal>qbase</literal>}<literal>qbase</literal> and \index{tags!special tag 9.931 - names!<literal>qtip</literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and 9.932 -topmost applied patches, respectively. 9.933 -</para> 9.934 - 9.935 -<para>These additions to Mercurial's normal tagging capabilities make 9.936 -dealing with patches even more of a breeze. 9.937 -</para> 9.938 -<itemizedlist> 9.939 -<listitem><para>Want to patchbomb a mailing list with your latest series of 9.940 - changes? 9.941 -</para> 9.942 -</listitem><programlisting> 9.943 -<listitem><para> hg email qbase:qtip 9.944 -</para> 9.945 -</listitem></programlisting> 9.946 -<listitem><para> (Don't know what <quote>patchbombing</quote> is? See 9.947 - section <xref linkend="sec:hgext:patchbomb"/>.) 9.948 -</para> 9.949 -</listitem> 9.950 -<listitem><para>Need to see all of the patches since <literal>foo.patch</literal> that 9.951 - have touched files in a subdirectory of your tree? 9.952 -</para> 9.953 -</listitem><programlisting> 9.954 -<listitem><para> hg log -r foo.patch:qtip <emphasis>subdir</emphasis> 9.955 -</para> 9.956 -</listitem></programlisting> 9.957 -</itemizedlist> 9.958 - 9.959 -<para>Because MQ makes the names of patches available to the rest of 9.960 -Mercurial through its normal internal tag machinery, you don't need to 9.961 -type in the entire name of a patch when you want to identify it by 9.962 -name. 9.963 -</para> 9.964 - 9.965 -<informalfigure> 9.966 -<para> <!-- &interaction.mq.id.output; --> 9.967 - <caption><para>Using MQ's tag features to work with patches</para></caption> 9.968 - \label{ex:mq:id} 9.969 -</para> 9.970 -</informalfigure> 9.971 - 9.972 -<para>Another nice consequence of representing patch names as tags is that 9.973 -when you run the <command role="hg-cmd">hg log</command> command, it will display a patch's name 9.974 -as a tag, simply as part of its normal output. This makes it easy to 9.975 -visually distinguish applied patches from underlying <quote>normal</quote> 9.976 -revisions. Figure <xref linkend="ex:mq:id"/> shows a few normal Mercurial 9.977 -commands in use with applied patches. 9.978 -</para> 9.979 - 9.980 -</sect1> 9.981 -<sect1> 9.982 -<title>Useful things to know about</title> 9.983 - 9.984 -<para>There are a number of aspects of MQ usage that don't fit tidily into 9.985 -sections of their own, but that are good to know. Here they are, in 9.986 -one place. 9.987 -</para> 9.988 - 9.989 -<itemizedlist> 9.990 -<listitem><para>Normally, when you <command role="hg-ext-mq">qpop</command> a patch and <command role="hg-ext-mq">qpush</command> it 9.991 - again, the changeset that represents the patch after the pop/push 9.992 - will have a <emphasis>different identity</emphasis> than the changeset that 9.993 - represented the hash beforehand. See 9.994 - section <xref linkend="sec:mqref:cmd:qpush"/> for information as to why this is. 9.995 -</para> 9.996 -</listitem> 9.997 -<listitem><para>It's not a good idea to <command role="hg-cmd">hg merge</command> changes from another 9.998 - branch with a patch changeset, at least if you want to maintain the 9.999 - <quote>patchiness</quote> of that changeset and changesets below it on the 9.1000 - patch stack. If you try to do this, it will appear to succeed, but 9.1001 - MQ will become confused. 9.1002 -</para> 9.1003 -</listitem></itemizedlist> 9.1004 - 9.1005 -</sect1> 9.1006 -<sect1> 9.1007 -<title>Managing patches in a repository</title> 9.1008 -<para>\label{sec:mq:repo} 9.1009 -</para> 9.1010 - 9.1011 -<para>Because MQ's <filename role="special" class="directory">.hg/patches</filename> directory resides outside a 9.1012 -Mercurial repository's working directory, the <quote>underlying</quote> Mercurial 9.1013 -repository knows nothing about the management or presence of patches. 9.1014 -</para> 9.1015 - 9.1016 -<para>This presents the interesting possibility of managing the contents of 9.1017 -the patch directory as a Mercurial repository in its own right. This 9.1018 -can be a useful way to work. For example, you can work on a patch for 9.1019 -a while, <command role="hg-ext-mq">qrefresh</command> it, then <command role="hg-cmd">hg commit</command> the current state of 9.1020 -the patch. This lets you <quote>roll back</quote> to that version of the patch 9.1021 -later on. 9.1022 -</para> 9.1023 - 9.1024 -<para>You can then share different versions of the same patch stack among 9.1025 -multiple underlying repositories. I use this when I am developing a 9.1026 -Linux kernel feature. I have a pristine copy of my kernel sources for 9.1027 -each of several CPU architectures, and a cloned repository under each 9.1028 -that contains the patches I am working on. When I want to test a 9.1029 -change on a different architecture, I push my current patches to the 9.1030 -patch repository associated with that kernel tree, pop and push all of 9.1031 -my patches, and build and test that kernel. 9.1032 -</para> 9.1033 - 9.1034 -<para>Managing patches in a repository makes it possible for multiple 9.1035 -developers to work on the same patch series without colliding with 9.1036 -each other, all on top of an underlying source base that they may or 9.1037 -may not control. 9.1038 -</para> 9.1039 - 9.1040 -<sect2> 9.1041 -<title>MQ support for patch repositories</title> 9.1042 - 9.1043 -<para>MQ helps you to work with the <filename role="special" class="directory">.hg/patches</filename> directory as a 9.1044 -repository; when you prepare a repository for working with patches 9.1045 -using <command role="hg-ext-mq">qinit</command>, you can pass the <option role="hg-ext-mq-cmd-qinit-opt">-c</option> option to 9.1046 -create the <filename role="special" class="directory">.hg/patches</filename> directory as a Mercurial repository. 9.1047 -</para> 9.1048 - 9.1049 -<note> 9.1050 -<para> If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">-c</option> option, you can simply go 9.1051 - into the <filename role="special" class="directory">.hg/patches</filename> directory at any time and run 9.1052 - <command role="hg-cmd">hg init</command>. Don't forget to add an entry for the 9.1053 - <filename role="special">status</filename> file to the <filename role="special">.hgignore</filename> file, though 9.1054 -</para> 9.1055 - 9.1056 -<para> (<command role="hg-cmd">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> does this for you 9.1057 - automatically); you <emphasis>really</emphasis> don't want to manage the 9.1058 - <filename role="special">status</filename> file. 9.1059 -</para> 9.1060 -</note> 9.1061 - 9.1062 -<para>As a convenience, if MQ notices that the <filename class="directory">.hg/patches</filename> 9.1063 -directory is a repository, it will automatically <command role="hg-cmd">hg add</command> every 9.1064 -patch that you create and import. 9.1065 -</para> 9.1066 - 9.1067 -<para>MQ provides a shortcut command, <command role="hg-ext-mq">qcommit</command>, that runs 9.1068 -<command role="hg-cmd">hg commit</command> in the <filename role="special" class="directory">.hg/patches</filename> directory. This saves 9.1069 -some bothersome typing. 9.1070 -</para> 9.1071 - 9.1072 -<para>Finally, as a convenience to manage the patch directory, you can 9.1073 -define the alias <command>mq</command> on Unix systems. For example, on Linux 9.1074 -systems using the <command>bash</command> shell, you can include the following 9.1075 -snippet in your <filename role="home">~/.bashrc</filename>. 9.1076 -</para> 9.1077 - 9.1078 -<programlisting> 9.1079 -<para> alias mq=`hg -R $(hg root)/.hg/patches' 9.1080 -</para> 9.1081 -</programlisting> 9.1082 - 9.1083 -<para>You can then issue commands of the form <command>mq pull</command> from 9.1084 -the main repository. 9.1085 -</para> 9.1086 - 9.1087 -</sect2> 9.1088 -<sect2> 9.1089 -<title>A few things to watch out for</title> 9.1090 - 9.1091 -<para>MQ's support for working with a repository full of patches is limited 9.1092 -in a few small respects. 9.1093 -</para> 9.1094 - 9.1095 -<para>MQ cannot automatically detect changes that you make to the patch 9.1096 -directory. If you <command role="hg-cmd">hg pull</command>, manually edit, or <command role="hg-cmd">hg update</command> 9.1097 -changes to patches or the <filename role="special">series</filename> file, you will have to 9.1098 -<command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> and then 9.1099 -<command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-a</option></command> in the underlying repository to 9.1100 -see those changes show up there. If you forget to do this, you can 9.1101 -confuse MQ's idea of which patches are applied. 9.1102 -</para> 9.1103 - 9.1104 -</sect2> 9.1105 -</sect1> 9.1106 -<sect1> 9.1107 -<title>Third party tools for working with patches</title> 9.1108 -<para>\label{sec:mq:tools} 9.1109 -</para> 9.1110 - 9.1111 -<para>Once you've been working with patches for a while, you'll find 9.1112 -yourself hungry for tools that will help you to understand and 9.1113 -manipulate the patches you're dealing with. 9.1114 -</para> 9.1115 - 9.1116 -<para>The <command>diffstat</command> command <citation>web:diffstat</citation> generates a 9.1117 -histogram of the modifications made to each file in a patch. It 9.1118 -provides a good way to <quote>get a sense of</quote> a patch&emdash;which files it 9.1119 -affects, and how much change it introduces to each file and as a 9.1120 -whole. (I find that it's a good idea to use <command>diffstat</command>'s 9.1121 -<option role="cmd-opt-diffstat">-p</option> option as a matter of course, as otherwise it 9.1122 -will try to do clever things with prefixes of file names that 9.1123 -inevitably confuse at least me.) 9.1124 -</para> 9.1125 - 9.1126 -<informalfigure> 9.1127 -<para> <!-- &interaction.mq.tools.tools; --> 9.1128 - <caption><para>The <command>diffstat</para></caption>, \command{filterdiff</command>, and <command>lsdiff</command> commands} 9.1129 - \label{ex:mq:tools} 9.1130 -</para> 9.1131 -</informalfigure> 9.1132 - 9.1133 -<para>The <literal role="package">patchutils</literal> package <citation>web:patchutils</citation> is invaluable. 9.1134 -It provides a set of small utilities that follow the <quote>Unix 9.1135 -philosophy;</quote> each does one useful thing with a patch. The 9.1136 -<literal role="package">patchutils</literal> command I use most is <command>filterdiff</command>, which 9.1137 -extracts subsets from a patch file. For example, given a patch that 9.1138 -modifies hundreds of files across dozens of directories, a single 9.1139 -invocation of <command>filterdiff</command> can generate a smaller patch that 9.1140 -only touches files whose names match a particular glob pattern. See 9.1141 -section <xref linkend="mq-collab:tips:interdiff"/> for another example. 9.1142 -</para> 9.1143 - 9.1144 -</sect1> 9.1145 -<sect1> 9.1146 -<title>Good ways to work with patches</title> 9.1147 - 9.1148 -<para>Whether you are working on a patch series to submit to a free software 9.1149 -or open source project, or a series that you intend to treat as a 9.1150 -sequence of regular changesets when you're done, you can use some 9.1151 -simple techniques to keep your work well organised. 9.1152 -</para> 9.1153 - 9.1154 -<para>Give your patches descriptive names. A good name for a patch might be 9.1155 -<filename>rework-device-alloc.patch</filename>, because it will immediately give 9.1156 -you a hint what the purpose of the patch is. Long names shouldn't be 9.1157 -a problem; you won't be typing the names often, but you <emphasis>will</emphasis> be 9.1158 -running commands like <command role="hg-ext-mq">qapplied</command> and <command role="hg-ext-mq">qtop</command> over and over. 9.1159 -Good naming becomes especially important when you have a number of 9.1160 -patches to work with, or if you are juggling a number of different 9.1161 -tasks and your patches only get a fraction of your attention. 9.1162 -</para> 9.1163 - 9.1164 -<para>Be aware of what patch you're working on. Use the <command role="hg-ext-mq">qtop</command> 9.1165 -command and skim over the text of your patches frequently&emdash;for 9.1166 -example, using <command role="hg-cmd">hg tip <option role="hg-opt-tip">-p</option></command>)&emdash;to be sure of where 9.1167 -you stand. I have several times worked on and <command role="hg-ext-mq">qrefresh</command>ed a 9.1168 -patch other than the one I intended, and it's often tricky to migrate 9.1169 -changes into the right patch after making them in the wrong one. 9.1170 -</para> 9.1171 - 9.1172 -<para>For this reason, it is very much worth investing a little time to 9.1173 -learn how to use some of the third-party tools I described in 9.1174 -section <xref linkend="sec:mq:tools"/>, particularly <command>diffstat</command> and 9.1175 -<command>filterdiff</command>. The former will give you a quick idea of what 9.1176 -changes your patch is making, while the latter makes it easy to splice 9.1177 -hunks selectively out of one patch and into another. 9.1178 -</para> 9.1179 - 9.1180 -</sect1> 9.1181 -<sect1> 9.1182 -<title>MQ cookbook</title> 9.1183 - 9.1184 -<sect2> 9.1185 -<title>Manage <quote>trivial</quote> patches</title> 9.1186 - 9.1187 -<para>Because the overhead of dropping files into a new Mercurial repository 9.1188 -is so low, it makes a lot of sense to manage patches this way even if 9.1189 -you simply want to make a few changes to a source tarball that you 9.1190 -downloaded. 9.1191 -</para> 9.1192 - 9.1193 -<para>Begin by downloading and unpacking the source tarball, 9.1194 -and turning it into a Mercurial repository. 9.1195 -<!-- &interaction.mq.tarball.download; --> 9.1196 -</para> 9.1197 - 9.1198 -<para>Continue by creating a patch stack and making your changes. 9.1199 -<!-- &interaction.mq.tarball.qinit; --> 9.1200 -</para> 9.1201 - 9.1202 -<para>Let's say a few weeks or months pass, and your package author releases 9.1203 -a new version. First, bring their changes into the repository. 9.1204 -<!-- &interaction.mq.tarball.newsource; --> 9.1205 -The pipeline starting with <command role="hg-cmd">hg locate</command> above deletes all files in 9.1206 -the working directory, so that <command role="hg-cmd">hg commit</command>'s 9.1207 -<option role="hg-opt-commit">--addremove</option> option can actually tell which files have 9.1208 -really been removed in the newer version of the source. 9.1209 -</para> 9.1210 - 9.1211 -<para>Finally, you can apply your patches on top of the new tree. 9.1212 -<!-- &interaction.mq.tarball.repush; --> 9.1213 -</para> 9.1214 - 9.1215 -</sect2> 9.1216 -<sect2> 9.1217 -<title>Combining entire patches</title> 9.1218 -<para>\label{sec:mq:combine} 9.1219 -</para> 9.1220 - 9.1221 -<para>MQ provides a command, <command role="hg-ext-mq">qfold</command> that lets you combine entire 9.1222 -patches. This <quote>folds</quote> the patches you name, in the order you name 9.1223 -them, into the topmost applied patch, and concatenates their 9.1224 -descriptions onto the end of its description. The patches that you 9.1225 -fold must be unapplied before you fold them. 9.1226 -</para> 9.1227 - 9.1228 -<para>The order in which you fold patches matters. If your topmost applied 9.1229 -patch is <literal>foo</literal>, and you <command role="hg-ext-mq">qfold</command> <literal>bar</literal> and 9.1230 -<literal>quux</literal> into it, you will end up with a patch that has the same 9.1231 -effect as if you applied first <literal>foo</literal>, then <literal>bar</literal>, 9.1232 -followed by <literal>quux</literal>. 9.1233 -</para> 9.1234 - 9.1235 -</sect2> 9.1236 -<sect2> 9.1237 -<title>Merging part of one patch into another</title> 9.1238 - 9.1239 -<para>Merging <emphasis>part</emphasis> of one patch into another is more difficult than 9.1240 -combining entire patches. 9.1241 -</para> 9.1242 - 9.1243 -<para>If you want to move changes to entire files, you can use 9.1244 -<command>filterdiff</command>'s <option role="cmd-opt-filterdiff">-i</option> and 9.1245 -<option role="cmd-opt-filterdiff">-x</option> options to choose the modifications to snip 9.1246 -out of one patch, concatenating its output onto the end of the patch 9.1247 -you want to merge into. You usually won't need to modify the patch 9.1248 -you've merged the changes from. Instead, MQ will report some rejected 9.1249 -hunks when you <command role="hg-ext-mq">qpush</command> it (from the hunks you moved into the 9.1250 -other patch), and you can simply <command role="hg-ext-mq">qrefresh</command> the patch to drop 9.1251 -the duplicate hunks. 9.1252 -</para> 9.1253 - 9.1254 -<para>If you have a patch that has multiple hunks modifying a file, and you 9.1255 -only want to move a few of those hunks, the job becomes more messy, 9.1256 -but you can still partly automate it. Use <command>lsdiff -nvv</command> to 9.1257 -print some metadata about the patch. 9.1258 -<!-- &interaction.mq.tools.lsdiff; --> 9.1259 -</para> 9.1260 - 9.1261 -<para>This command prints three different kinds of number: 9.1262 -</para> 9.1263 -<itemizedlist> 9.1264 -<listitem><para>(in the first column) a <emphasis>file number</emphasis> to identify each file 9.1265 - modified in the patch; 9.1266 -</para> 9.1267 -</listitem> 9.1268 -<listitem><para>(on the next line, indented) the line number within a modified 9.1269 - file where a hunk starts; and 9.1270 -</para> 9.1271 -</listitem> 9.1272 -<listitem><para>(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk. 9.1273 -</para> 9.1274 -</listitem></itemizedlist> 9.1275 - 9.1276 -<para>You'll have to use some visual inspection, and reading of the patch, 9.1277 -to identify the file and hunk numbers you'll want, but you can then 9.1278 -pass them to to <command>filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option> 9.1279 -and <option role="cmd-opt-filterdiff">--hunks</option> options, to select exactly the file 9.1280 -and hunk you want to extract. 9.1281 -</para> 9.1282 - 9.1283 -<para>Once you have this hunk, you can concatenate it onto the end of your 9.1284 -destination patch and continue with the remainder of 9.1285 -section <xref linkend="sec:mq:combine"/>. 9.1286 -</para> 9.1287 - 9.1288 -</sect2> 9.1289 -</sect1> 9.1290 -<sect1> 9.1291 -<title>Differences between quilt and MQ</title> 9.1292 - 9.1293 -<para>If you are already familiar with quilt, MQ provides a similar command 9.1294 -set. There are a few differences in the way that it works. 9.1295 -</para> 9.1296 - 9.1297 -<para>You will already have noticed that most quilt commands have MQ 9.1298 -counterparts that simply begin with a <quote><literal>q</literal></quote>. The exceptions 9.1299 -are quilt's <literal>add</literal> and <literal>remove</literal> commands, the 9.1300 -counterparts for which are the normal Mercurial <command role="hg-cmd">hg add</command> and 9.1301 -<command role="hg-cmd">hg remove</command> commands. There is no MQ equivalent of the quilt 9.1302 -<literal>edit</literal> command. 9.1303 -</para> 9.1304 - 9.1305 -</sect1> 9.1306 +<chapter id="chap:mq"> 9.1307 + <?dbhtml filename="managing-change-with-mercurial-queues.html"?> 9.1308 + <title>Managing change with Mercurial Queues</title> 9.1309 + 9.1310 + <sect1 id="sec:mq:patch-mgmt"> 9.1311 + <title>The patch management problem</title> 9.1312 + 9.1313 + <para id="x_3ac">Here is a common scenario: you need to install a software 9.1314 + package from source, but you find a bug that you must fix in the 9.1315 + source before you can start using the package. You make your 9.1316 + changes, forget about the package for a while, and a few months 9.1317 + later you need to upgrade to a newer version of the package. If 9.1318 + the newer version of the package still has the bug, you must 9.1319 + extract your fix from the older source tree and apply it against 9.1320 + the newer version. This is a tedious task, and it's easy to 9.1321 + make mistakes.</para> 9.1322 + 9.1323 + <para id="x_3ad">This is a simple case of the <quote>patch management</quote> 9.1324 + problem. You have an <quote>upstream</quote> source tree that 9.1325 + you can't change; you need to make some local changes on top of 9.1326 + the upstream tree; and you'd like to be able to keep those 9.1327 + changes separate, so that you can apply them to newer versions 9.1328 + of the upstream source.</para> 9.1329 + 9.1330 + <para id="x_3ae">The patch management problem arises in many situations. 9.1331 + Probably the most visible is that a user of an open source 9.1332 + software project will contribute a bug fix or new feature to the 9.1333 + project's maintainers in the form of a patch.</para> 9.1334 + 9.1335 + <para id="x_3af">Distributors of operating systems that include open source 9.1336 + software often need to make changes to the packages they 9.1337 + distribute so that they will build properly in their 9.1338 + environments.</para> 9.1339 + 9.1340 + <para id="x_3b0">When you have few changes to maintain, it is easy to manage 9.1341 + a single patch using the standard <command>diff</command> and 9.1342 + <command>patch</command> programs (see <xref 9.1343 + linkend="sec:mq:patch"/> for a discussion of these 9.1344 + tools). Once the number of changes grows, it starts to make 9.1345 + sense to maintain patches as discrete <quote>chunks of 9.1346 + work,</quote> so that for example a single patch will contain 9.1347 + only one bug fix (the patch might modify several files, but it's 9.1348 + doing <quote>only one thing</quote>), and you may have a number 9.1349 + of such patches for different bugs you need fixed and local 9.1350 + changes you require. In this situation, if you submit a bug fix 9.1351 + patch to the upstream maintainers of a package and they include 9.1352 + your fix in a subsequent release, you can simply drop that 9.1353 + single patch when you're updating to the newer release.</para> 9.1354 + 9.1355 + <para id="x_3b1">Maintaining a single patch against an upstream tree is a 9.1356 + little tedious and error-prone, but not difficult. However, the 9.1357 + complexity of the problem grows rapidly as the number of patches 9.1358 + you have to maintain increases. With more than a tiny number of 9.1359 + patches in hand, understanding which ones you have applied and 9.1360 + maintaining them moves from messy to overwhelming.</para> 9.1361 + 9.1362 + <para id="x_3b2">Fortunately, Mercurial includes a powerful extension, 9.1363 + Mercurial Queues (or simply <quote>MQ</quote>), that massively 9.1364 + simplifies the patch management problem.</para> 9.1365 + 9.1366 + </sect1> 9.1367 + <sect1 id="sec:mq:history"> 9.1368 + <title>The prehistory of Mercurial Queues</title> 9.1369 + 9.1370 + <para id="x_3b3">During the late 1990s, several Linux kernel developers 9.1371 + started to maintain <quote>patch series</quote> that modified 9.1372 + the behavior of the Linux kernel. Some of these series were 9.1373 + focused on stability, some on feature coverage, and others were 9.1374 + more speculative.</para> 9.1375 + 9.1376 + <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002, 9.1377 + Andrew Morton published some shell scripts he had been using to 9.1378 + automate the task of managing his patch queues. Andrew was 9.1379 + successfully using these scripts to manage hundreds (sometimes 9.1380 + thousands) of patches on top of the Linux kernel.</para> 9.1381 + 9.1382 + <sect2 id="sec:mq:quilt"> 9.1383 + <title>A patchwork quilt</title> 9.1384 + 9.1385 + <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson 9.1386 + borrowed the approach of Andrew's scripts and published a tool 9.1387 + called <quote>patchwork quilt</quote> 9.1388 + <citation>web:quilt</citation>, or simply <quote>quilt</quote> 9.1389 + (see <citation>gruenbacher:2005</citation> for a paper 9.1390 + describing it). Because quilt substantially automated patch 9.1391 + management, it rapidly gained a large following among open 9.1392 + source software developers.</para> 9.1393 + 9.1394 + <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on 9.1395 + top of a directory tree. To begin, you tell quilt to manage a 9.1396 + directory tree, and tell it which files you want to manage; it 9.1397 + stores away the names and contents of those files. To fix a 9.1398 + bug, you create a new patch (using a single command), edit the 9.1399 + files you need to fix, then <quote>refresh</quote> the 9.1400 + patch.</para> 9.1401 + 9.1402 + <para id="x_3b7">The refresh step causes quilt to scan the directory tree; 9.1403 + it updates the patch with all of the changes you have made. 9.1404 + You can create another patch on top of the first, which will 9.1405 + track the changes required to modify the tree from <quote>tree 9.1406 + with one patch applied</quote> to <quote>tree with two 9.1407 + patches applied</quote>.</para> 9.1408 + 9.1409 + <para id="x_3b8">You can <emphasis>change</emphasis> which patches are 9.1410 + applied to the tree. If you <quote>pop</quote> a patch, the 9.1411 + changes made by that patch will vanish from the directory 9.1412 + tree. Quilt remembers which patches you have popped, though, 9.1413 + so you can <quote>push</quote> a popped patch again, and the 9.1414 + directory tree will be restored to contain the modifications 9.1415 + in the patch. Most importantly, you can run the 9.1416 + <quote>refresh</quote> command at any time, and the topmost 9.1417 + applied patch will be updated. This means that you can, at 9.1418 + any time, change both which patches are applied and what 9.1419 + modifications those patches make.</para> 9.1420 + 9.1421 + <para id="x_3b9">Quilt knows nothing about revision control tools, so it 9.1422 + works equally well on top of an unpacked tarball or a 9.1423 + Subversion working copy.</para> 9.1424 + </sect2> 9.1425 + 9.1426 + <sect2 id="sec:mq:quilt-mq"> 9.1427 + <title>From patchwork quilt to Mercurial Queues</title> 9.1428 + 9.1429 + <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and 9.1430 + wrote an extension that he called Mercurial Queues, which 9.1431 + added quilt-like behavior to Mercurial.</para> 9.1432 + 9.1433 + <para id="x_3bb">The key difference between quilt and MQ is that quilt 9.1434 + knows nothing about revision control systems, while MQ is 9.1435 + <emphasis>integrated</emphasis> into Mercurial. Each patch 9.1436 + that you push is represented as a Mercurial changeset. Pop a 9.1437 + patch, and the changeset goes away.</para> 9.1438 + 9.1439 + <para id="x_3bc">Because quilt does not care about revision control tools, 9.1440 + it is still a tremendously useful piece of software to know 9.1441 + about for situations where you cannot use Mercurial and 9.1442 + MQ.</para> 9.1443 + 9.1444 + </sect2> 9.1445 + </sect1> 9.1446 + <sect1> 9.1447 + <title>The huge advantage of MQ</title> 9.1448 + 9.1449 + <para id="x_3bd">I cannot overstate the value that MQ offers through the 9.1450 + unification of patches and revision control.</para> 9.1451 + 9.1452 + <para id="x_3be">A major reason that patches have persisted in the free 9.1453 + software and open source world&emdash;in spite of the 9.1454 + availability of increasingly capable revision control tools over 9.1455 + the years&emdash;is the <emphasis>agility</emphasis> they 9.1456 + offer.</para> 9.1457 + 9.1458 + <para id="x_3bf">Traditional revision control tools make a permanent, 9.1459 + irreversible record of everything that you do. While this has 9.1460 + great value, it's also somewhat stifling. If you want to 9.1461 + perform a wild-eyed experiment, you have to be careful in how 9.1462 + you go about it, or you risk leaving unneeded&emdash;or worse, 9.1463 + misleading or destabilising&emdash;traces of your missteps and 9.1464 + errors in the permanent revision record.</para> 9.1465 + 9.1466 + <para id="x_3c0">By contrast, MQ's marriage of distributed revision control 9.1467 + with patches makes it much easier to isolate your work. Your 9.1468 + patches live on top of normal revision history, and you can make 9.1469 + them disappear or reappear at will. If you don't like a patch, 9.1470 + you can drop it. If a patch isn't quite as you want it to be, 9.1471 + simply fix it&emdash;as many times as you need to, until you 9.1472 + have refined it into the form you desire.</para> 9.1473 + 9.1474 + <para id="x_3c1">As an example, the integration of patches with revision 9.1475 + control makes understanding patches and debugging their 9.1476 + effects&emdash;and their interplay with the code they're based 9.1477 + on&emdash;<emphasis>enormously</emphasis> easier. Since every 9.1478 + applied patch has an associated changeset, you can give <command 9.1479 + role="hg-cmd">hg log</command> a file name to see which 9.1480 + changesets and patches affected the file. You can use the 9.1481 + <command role="hg-cmd">hg bisect</command> command to 9.1482 + binary-search through all changesets and applied patches to see 9.1483 + where a bug got introduced or fixed. You can use the <command 9.1484 + role="hg-cmd">hg annotate</command> command to see which 9.1485 + changeset or patch modified a particular line of a source file. 9.1486 + And so on.</para> 9.1487 + </sect1> 9.1488 + 9.1489 + <sect1 id="sec:mq:patch"> 9.1490 + <title>Understanding patches</title> 9.1491 + 9.1492 + <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is 9.1493 + helpful to understand what patches are, and a little about the 9.1494 + tools that work with them.</para> 9.1495 + 9.1496 + <para id="x_3c3">The traditional Unix <command>diff</command> command 9.1497 + compares two files, and prints a list of differences between 9.1498 + them. The <command>patch</command> command understands these 9.1499 + differences as <emphasis>modifications</emphasis> to make to a 9.1500 + file. Take a look below for a simple example of these commands 9.1501 + in action.</para> 9.1502 + 9.1503 + &interaction.mq.dodiff.diff; 9.1504 + 9.1505 + <para id="x_3c4">The type of file that <command>diff</command> generates (and 9.1506 + <command>patch</command> takes as input) is called a 9.1507 + <quote>patch</quote> or a <quote>diff</quote>; there is no 9.1508 + difference between a patch and a diff. (We'll use the term 9.1509 + <quote>patch</quote>, since it's more commonly used.)</para> 9.1510 + 9.1511 + <para id="x_3c5">A patch file can start with arbitrary text; the 9.1512 + <command>patch</command> command ignores this text, but MQ uses 9.1513 + it as the commit message when creating changesets. To find the 9.1514 + beginning of the patch content, <command>patch</command> 9.1515 + searches for the first line that starts with the string 9.1516 + <quote><literal>diff -</literal></quote>.</para> 9.1517 + 9.1518 + <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs 9.1519 + (<command>patch</command> can accept several other diff formats, 9.1520 + but MQ doesn't). A unified diff contains two kinds of header. 9.1521 + The <emphasis>file header</emphasis> describes the file being 9.1522 + modified; it contains the name of the file to modify. When 9.1523 + <command>patch</command> sees a new file header, it looks for a 9.1524 + file with that name to start modifying.</para> 9.1525 + 9.1526 + <para id="x_3c7">After the file header comes a series of 9.1527 + <emphasis>hunks</emphasis>. Each hunk starts with a header; 9.1528 + this identifies the range of line numbers within the file that 9.1529 + the hunk should modify. Following the header, a hunk starts and 9.1530 + ends with a few (usually three) lines of text from the 9.1531 + unmodified file; these are called the 9.1532 + <emphasis>context</emphasis> for the hunk. If there's only a 9.1533 + small amount of context between successive hunks, 9.1534 + <command>diff</command> doesn't print a new hunk header; it just 9.1535 + runs the hunks together, with a few lines of context between 9.1536 + modifications.</para> 9.1537 + 9.1538 + <para id="x_3c8">Each line of context begins with a space character. Within 9.1539 + the hunk, a line that begins with 9.1540 + <quote><literal>-</literal></quote> means <quote>remove this 9.1541 + line,</quote> while a line that begins with 9.1542 + <quote><literal>+</literal></quote> means <quote>insert this 9.1543 + line.</quote> For example, a line that is modified is 9.1544 + represented by one deletion and one insertion.</para> 9.1545 + 9.1546 + <para id="x_3c9">We will return to some of the more subtle aspects of patches 9.1547 + later (in <xref linkend="sec:mq:adv-patch"/>), but you 9.1548 + should have 9.1549 + enough information now to use MQ.</para> 9.1550 + </sect1> 9.1551 + 9.1552 + <sect1 id="sec:mq:start"> 9.1553 + <title>Getting started with Mercurial Queues</title> 9.1554 + 9.1555 + <para id="x_3ca">Because MQ is implemented as an extension, you must 9.1556 + explicitly enable before you can use it. (You don't need to 9.1557 + download anything; MQ ships with the standard Mercurial 9.1558 + distribution.) To enable MQ, edit your <filename 9.1559 + role="home">~/.hgrc</filename> file, and add the lines 9.1560 + below.</para> 9.1561 + 9.1562 + <programlisting>[extensions] 9.1563 +hgext.mq =</programlisting> 9.1564 + 9.1565 + <para id="x_3cb">Once the extension is enabled, it will make a number of new 9.1566 + commands available. To verify that the extension is working, 9.1567 + you can use <command role="hg-cmd">hg help</command> to see if 9.1568 + the <command role="hg-ext-mq">qinit</command> command is now 9.1569 + available.</para> 9.1570 + 9.1571 + &interaction.mq.qinit-help.help; 9.1572 + 9.1573 + <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 9.1574 + repository, and its commands only operate within that 9.1575 + repository. To get started, simply prepare the repository using 9.1576 + the <command role="hg-ext-mq">qinit</command> command.</para> 9.1577 + 9.1578 + &interaction.mq.tutorial.qinit; 9.1579 + 9.1580 + <para id="x_3cd">This command creates an empty directory called <filename 9.1581 + role="special" class="directory">.hg/patches</filename>, where 9.1582 + MQ will keep its metadata. As with many Mercurial commands, the 9.1583 + <command role="hg-ext-mq">qinit</command> command prints nothing 9.1584 + if it succeeds.</para> 9.1585 + 9.1586 + <sect2> 9.1587 + <title>Creating a new patch</title> 9.1588 + 9.1589 + <para id="x_3ce">To begin work on a new patch, use the <command 9.1590 + role="hg-ext-mq">qnew</command> command. This command takes 9.1591 + one argument, the name of the patch to create.</para> 9.1592 + 9.1593 + <para id="x_3cf">MQ will use this as the name of an actual file in the 9.1594 + <filename role="special" 9.1595 + class="directory">.hg/patches</filename> directory, as you 9.1596 + can see below.</para> 9.1597 + 9.1598 + &interaction.mq.tutorial.qnew; 9.1599 + 9.1600 + <para id="x_3d0">Also newly present in the <filename role="special" 9.1601 + class="directory">.hg/patches</filename> directory are two 9.1602 + other files, <filename role="special">series</filename> and 9.1603 + <filename role="special">status</filename>. The <filename 9.1604 + role="special">series</filename> file lists all of the 9.1605 + patches that MQ knows about for this repository, with one 9.1606 + patch per line. Mercurial uses the <filename 9.1607 + role="special">status</filename> file for internal 9.1608 + book-keeping; it tracks all of the patches that MQ has 9.1609 + <emphasis>applied</emphasis> in this repository.</para> 9.1610 + 9.1611 + <note> 9.1612 + <para id="x_3d1"> You may sometimes want to edit the <filename 9.1613 + role="special">series</filename> file by hand; for 9.1614 + example, to change the sequence in which some patches are 9.1615 + applied. However, manually editing the <filename 9.1616 + role="special">status</filename> file is almost always a 9.1617 + bad idea, as it's easy to corrupt MQ's idea of what is 9.1618 + happening.</para> 9.1619 + </note> 9.1620 + 9.1621 + <para id="x_3d2">Once you have created your new patch, you can edit files 9.1622 + in the working directory as you usually would. All of the 9.1623 + normal Mercurial commands, such as <command role="hg-cmd">hg 9.1624 + diff</command> and <command role="hg-cmd">hg 9.1625 + annotate</command>, work exactly as they did before.</para> 9.1626 + </sect2> 9.1627 + 9.1628 + <sect2> 9.1629 + <title>Refreshing a patch</title> 9.1630 + 9.1631 + <para id="x_3d3">When you reach a point where you want to save your work, 9.1632 + use the <command role="hg-ext-mq">qrefresh</command> command 9.1633 + to update the patch you are working on.</para> 9.1634 + 9.1635 + &interaction.mq.tutorial.qrefresh; 9.1636 + 9.1637 + <para id="x_3d4">This command folds the changes you have made in the 9.1638 + working directory into your patch, and updates its 9.1639 + corresponding changeset to contain those changes.</para> 9.1640 + 9.1641 + <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command> 9.1642 + as often as you like, so it's a good way to 9.1643 + <quote>checkpoint</quote> your work. Refresh your patch at an 9.1644 + opportune time; try an experiment; and if the experiment 9.1645 + doesn't work out, <command role="hg-cmd">hg revert</command> 9.1646 + your modifications back to the last time you refreshed.</para> 9.1647 + 9.1648 + &interaction.mq.tutorial.qrefresh2; 9.1649 + </sect2> 9.1650 + 9.1651 + <sect2> 9.1652 + <title>Stacking and tracking patches</title> 9.1653 + 9.1654 + <para id="x_3d6">Once you have finished working on a patch, or need to work 9.1655 + on another, you can use the <command 9.1656 + role="hg-ext-mq">qnew</command> command again to create a 9.1657 + new patch. Mercurial will apply this patch on top of your 9.1658 + existing patch.</para> 9.1659 + 9.1660 + &interaction.mq.tutorial.qnew2; 9.1661 + 9.1662 + <para id="x_3d7">Notice that the patch contains the changes in our prior 9.1663 + patch as part of its context (you can see this more clearly in 9.1664 + the output of <command role="hg-cmd">hg 9.1665 + annotate</command>).</para> 9.1666 + 9.1667 + <para id="x_3d8">So far, with the exception of <command 9.1668 + role="hg-ext-mq">qnew</command> and <command 9.1669 + role="hg-ext-mq">qrefresh</command>, we've been careful to 9.1670 + only use regular Mercurial commands. However, MQ provides 9.1671 + many commands that are easier to use when you are thinking 9.1672 + about patches, as illustrated below.</para> 9.1673 + 9.1674 + &interaction.mq.tutorial.qseries; 9.1675 + 9.1676 + <itemizedlist> 9.1677 + <listitem><para id="x_3d9">The <command 9.1678 + role="hg-ext-mq">qseries</command> command lists every 9.1679 + patch that MQ knows about in this repository, from oldest 9.1680 + to newest (most recently 9.1681 + <emphasis>created</emphasis>).</para> 9.1682 + </listitem> 9.1683 + <listitem><para id="x_3da">The <command 9.1684 + role="hg-ext-mq">qapplied</command> command lists every 9.1685 + patch that MQ has <emphasis>applied</emphasis> in this 9.1686 + repository, again from oldest to newest (most recently 9.1687 + applied).</para> 9.1688 + </listitem></itemizedlist> 9.1689 + </sect2> 9.1690 + 9.1691 + <sect2> 9.1692 + <title>Manipulating the patch stack</title> 9.1693 + 9.1694 + <para id="x_3db">The previous discussion implied that there must be a 9.1695 + difference between <quote>known</quote> and 9.1696 + <quote>applied</quote> patches, and there is. MQ can manage a 9.1697 + patch without it being applied in the repository.</para> 9.1698 + 9.1699 + <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding 9.1700 + changeset in the repository, and the effects of the patch and 9.1701 + changeset are visible in the working directory. You can undo 9.1702 + the application of a patch using the <command 9.1703 + role="hg-ext-mq">qpop</command> command. MQ still 9.1704 + <emphasis>knows about</emphasis>, or manages, a popped patch, 9.1705 + but the patch no longer has a corresponding changeset in the 9.1706 + repository, and the working directory does not contain the 9.1707 + changes made by the patch. <xref 9.1708 + linkend="fig:mq:stack"/> illustrates 9.1709 + the difference between applied and tracked patches.</para> 9.1710 + 9.1711 + <figure id="fig:mq:stack"> 9.1712 + <title>Applied and unapplied patches in the MQ patch 9.1713 + stack</title> 9.1714 + <mediaobject> 9.1715 + <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject> 9.1716 + <textobject><phrase>XXX add text</phrase></textobject> 9.1717 + </mediaobject> 9.1718 + </figure> 9.1719 + 9.1720 + <para id="x_3de">You can reapply an unapplied, or popped, patch using the 9.1721 + <command role="hg-ext-mq">qpush</command> command. This 9.1722 + creates a new changeset to correspond to the patch, and the 9.1723 + patch's changes once again become present in the working 9.1724 + directory. See below for examples of <command 9.1725 + role="hg-ext-mq">qpop</command> and <command 9.1726 + role="hg-ext-mq">qpush</command> in action.</para> 9.1727 + 9.1728 + &interaction.mq.tutorial.qpop; 9.1729 + 9.1730 + <para id="x_3df">Notice that once we have popped a patch or two patches, 9.1731 + the output of <command role="hg-ext-mq">qseries</command> 9.1732 + remains the same, while that of <command 9.1733 + role="hg-ext-mq">qapplied</command> has changed.</para> 9.1734 + 9.1735 + </sect2> 9.1736 + 9.1737 + <sect2> 9.1738 + <title>Pushing and popping many patches</title> 9.1739 + 9.1740 + <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and 9.1741 + <command role="hg-ext-mq">qpop</command> each operate on a 9.1742 + single patch at a time by default, you can push and pop many 9.1743 + patches in one go. The <option 9.1744 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to 9.1745 + <command role="hg-ext-mq">qpush</command> causes it to push 9.1746 + all unapplied patches, while the <option 9.1747 + role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command 9.1748 + role="hg-ext-mq">qpop</command> causes it to pop all applied 9.1749 + patches. (For some more ways to push and pop many patches, 9.1750 + see <xref linkend="sec:mq:perf"/> below.)</para> 9.1751 + 9.1752 + &interaction.mq.tutorial.qpush-a; 9.1753 + </sect2> 9.1754 + 9.1755 + <sect2> 9.1756 + <title>Safety checks, and overriding them</title> 9.1757 + 9.1758 + <para id="x_3e1">Several MQ commands check the working directory before 9.1759 + they do anything, and fail if they find any modifications. 9.1760 + They do this to ensure that you won't lose any changes that 9.1761 + you have made, but not yet incorporated into a patch. The 9.1762 + example below illustrates this; the <command 9.1763 + role="hg-ext-mq">qnew</command> command will not create a 9.1764 + new patch if there are outstanding changes, caused in this 9.1765 + case by the <command role="hg-cmd">hg add</command> of 9.1766 + <filename>file3</filename>.</para> 9.1767 + 9.1768 + &interaction.mq.tutorial.add; 9.1769 + 9.1770 + <para id="x_3e2">Commands that check the working directory all take an 9.1771 + <quote>I know what I'm doing</quote> option, which is always 9.1772 + named <option>-f</option>. The exact meaning of 9.1773 + <option>-f</option> depends on the command. For example, 9.1774 + <command role="hg-cmd">hg qnew <option 9.1775 + role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command> 9.1776 + will incorporate any outstanding changes into the new patch it 9.1777 + creates, but <command role="hg-cmd">hg qpop <option 9.1778 + role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command> 9.1779 + will revert modifications to any files affected by the patch 9.1780 + that it is popping. Be sure to read the documentation for a 9.1781 + command's <option>-f</option> option before you use it!</para> 9.1782 + </sect2> 9.1783 + 9.1784 + <sect2> 9.1785 + <title>Working on several patches at once</title> 9.1786 + 9.1787 + <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command 9.1788 + always refreshes the <emphasis>topmost</emphasis> applied 9.1789 + patch. This means that you can suspend work on one patch (by 9.1790 + refreshing it), pop or push to make a different patch the top, 9.1791 + and work on <emphasis>that</emphasis> patch for a 9.1792 + while.</para> 9.1793 + 9.1794 + <para id="x_3e4">Here's an example that illustrates how you can use this 9.1795 + ability. Let's say you're developing a new feature as two 9.1796 + patches. The first is a change to the core of your software, 9.1797 + and the second&emdash;layered on top of the 9.1798 + first&emdash;changes the user interface to use the code you 9.1799 + just added to the core. If you notice a bug in the core while 9.1800 + you're working on the UI patch, it's easy to fix the core. 9.1801 + Simply <command role="hg-ext-mq">qrefresh</command> the UI 9.1802 + patch to save your in-progress changes, and <command 9.1803 + role="hg-ext-mq">qpop</command> down to the core patch. Fix 9.1804 + the core bug, <command role="hg-ext-mq">qrefresh</command> the 9.1805 + core patch, and <command role="hg-ext-mq">qpush</command> back 9.1806 + to the UI patch to continue where you left off.</para> 9.1807 + </sect2> 9.1808 + </sect1> 9.1809 + 9.1810 + <sect1 id="sec:mq:adv-patch"> 9.1811 + <title>More about patches</title> 9.1812 + 9.1813 + <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply 9.1814 + patches, so it's helpful to know a few more detailed aspects of 9.1815 + how <command>patch</command> works, and about patches 9.1816 + themselves.</para> 9.1817 + 9.1818 + <sect2> 9.1819 + <title>The strip count</title> 9.1820 + 9.1821 + <para id="x_3e6">If you look at the file headers in a patch, you will 9.1822 + notice that the pathnames usually have an extra component on 9.1823 + the front that isn't present in the actual path name. This is 9.1824 + a holdover from the way that people used to generate patches 9.1825 + (people still do this, but it's somewhat rare with modern 9.1826 + revision control tools).</para> 9.1827 + 9.1828 + <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide 9.1829 + that she wanted to create a patch. So she'd rename her 9.1830 + working directory, unpack the tarball again (hence the need 9.1831 + for the rename), and use the <option 9.1832 + role="cmd-opt-diff">-r</option> and <option 9.1833 + role="cmd-opt-diff">-N</option> options to 9.1834 + <command>diff</command> to recursively generate a patch 9.1835 + between the unmodified directory and the modified one. The 9.1836 + result would be that the name of the unmodified directory 9.1837 + would be at the front of the left-hand path in every file 9.1838 + header, and the name of the modified directory would be at the 9.1839 + front of the right-hand path.</para> 9.1840 + 9.1841 + <para id="x_3e8">Since someone receiving a patch from the Alices of the net 9.1842 + would be unlikely to have unmodified and modified directories 9.1843 + with exactly the same names, the <command>patch</command> 9.1844 + command has a <option role="cmd-opt-patch">-p</option> option 9.1845 + that indicates the number of leading path name components to 9.1846 + strip when trying to apply a patch. This number is called the 9.1847 + <emphasis>strip count</emphasis>.</para> 9.1848 + 9.1849 + <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means 9.1850 + <quote>use a strip count of one</quote>. If 9.1851 + <command>patch</command> sees a file name 9.1852 + <filename>foo/bar/baz</filename> in a file header, it will 9.1853 + strip <filename>foo</filename> and try to patch a file named 9.1854 + <filename>bar/baz</filename>. (Strictly speaking, the strip 9.1855 + count refers to the number of <emphasis>path 9.1856 + separators</emphasis> (and the components that go with them 9.1857 + ) to strip. A strip count of one will turn 9.1858 + <filename>foo/bar</filename> into <filename>bar</filename>, 9.1859 + but <filename>/foo/bar</filename> (notice the extra leading 9.1860 + slash) into <filename>foo/bar</filename>.)</para> 9.1861 + 9.1862 + <para id="x_3ea">The <quote>standard</quote> strip count for patches is 9.1863 + one; almost all patches contain one leading path name 9.1864 + component that needs to be stripped. Mercurial's <command 9.1865 + role="hg-cmd">hg diff</command> command generates path names 9.1866 + in this form, and the <command role="hg-cmd">hg 9.1867 + import</command> command and MQ expect patches to have a 9.1868 + strip count of one.</para> 9.1869 + 9.1870 + <para id="x_3eb">If you receive a patch from someone that you want to add 9.1871 + to your patch queue, and the patch needs a strip count other 9.1872 + than one, you cannot just <command 9.1873 + role="hg-ext-mq">qimport</command> the patch, because 9.1874 + <command role="hg-ext-mq">qimport</command> does not yet have 9.1875 + a <literal>-p</literal> option (see <ulink role="hg-bug" 9.1876 + url="http://www.selenic.com/mercurial/bts/issue311">issue 9.1877 + 311</ulink>). Your best bet is to <command 9.1878 + role="hg-ext-mq">qnew</command> a patch of your own, then 9.1879 + use <command>patch -pN</command> to apply their patch, 9.1880 + followed by <command role="hg-cmd">hg addremove</command> to 9.1881 + pick up any files added or removed by the patch, followed by 9.1882 + <command role="hg-ext-mq">hg qrefresh</command>. This 9.1883 + complexity may become unnecessary; see <ulink role="hg-bug" 9.1884 + url="http://www.selenic.com/mercurial/bts/issue311">issue 9.1885 + 311</ulink> for details. 9.1886 + </para> 9.1887 + </sect2> 9.1888 + 9.1889 + <sect2> 9.1890 + <title>Strategies for applying a patch</title> 9.1891 + 9.1892 + <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a 9.1893 + handful of successively less accurate strategies to try to 9.1894 + make the hunk apply. This falling-back technique often makes 9.1895 + it possible to take a patch that was generated against an old 9.1896 + version of a file, and apply it against a newer version of 9.1897 + that file.</para> 9.1898 + 9.1899 + <para id="x_3ed">First, <command>patch</command> tries an exact match, 9.1900 + where the line numbers, the context, and the text to be 9.1901 + modified must apply exactly. If it cannot make an exact 9.1902 + match, it tries to find an exact match for the context, 9.1903 + without honouring the line numbering information. If this 9.1904 + succeeds, it prints a line of output saying that the hunk was 9.1905 + applied, but at some <emphasis>offset</emphasis> from the 9.1906 + original line number.</para> 9.1907 + 9.1908 + <para id="x_3ee">If a context-only match fails, <command>patch</command> 9.1909 + removes the first and last lines of the context, and tries a 9.1910 + <emphasis>reduced</emphasis> context-only match. If the hunk 9.1911 + with reduced context succeeds, it prints a message saying that 9.1912 + it applied the hunk with a <emphasis>fuzz factor</emphasis> 9.1913 + (the number after the fuzz factor indicates how many lines of 9.1914 + context <command>patch</command> had to trim before the patch 9.1915 + applied).</para> 9.1916 + 9.1917 + <para id="x_3ef">When neither of these techniques works, 9.1918 + <command>patch</command> prints a message saying that the hunk 9.1919 + in question was rejected. It saves rejected hunks (also 9.1920 + simply called <quote>rejects</quote>) to a file with the same 9.1921 + name, and an added <filename role="special">.rej</filename> 9.1922 + extension. It also saves an unmodified copy of the file with 9.1923 + a <filename role="special">.orig</filename> extension; the 9.1924 + copy of the file without any extensions will contain any 9.1925 + changes made by hunks that <emphasis>did</emphasis> apply 9.1926 + cleanly. If you have a patch that modifies 9.1927 + <filename>foo</filename> with six hunks, and one of them fails 9.1928 + to apply, you will have: an unmodified 9.1929 + <filename>foo.orig</filename>, a <filename>foo.rej</filename> 9.1930 + containing one hunk, and <filename>foo</filename>, containing 9.1931 + the changes made by the five successful hunks.</para> 9.1932 + </sect2> 9.1933 + 9.1934 + <sect2> 9.1935 + <title>Some quirks of patch representation</title> 9.1936 + 9.1937 + <para id="x_3f0">There are a few useful things to know about how 9.1938 + <command>patch</command> works with files.</para> 9.1939 + <itemizedlist> 9.1940 + <listitem><para id="x_3f1">This should already be obvious, but 9.1941 + <command>patch</command> cannot handle binary 9.1942 + files.</para> 9.1943 + </listitem> 9.1944 + <listitem><para id="x_3f2">Neither does it care about the executable bit; 9.1945 + it creates new files as readable, but not 9.1946 + executable.</para> 9.1947 + </listitem> 9.1948 + <listitem><para id="x_3f3"><command>patch</command> treats the removal of 9.1949 + a file as a diff between the file to be removed and the 9.1950 + empty file. So your idea of <quote>I deleted this 9.1951 + file</quote> looks like <quote>every line of this file 9.1952 + was deleted</quote> in a patch.</para> 9.1953 + </listitem> 9.1954 + <listitem><para id="x_3f4">It treats the addition of a file as a diff 9.1955 + between the empty file and the file to be added. So in a 9.1956 + patch, your idea of <quote>I added this file</quote> looks 9.1957 + like <quote>every line of this file was 9.1958 + added</quote>.</para> 9.1959 + </listitem> 9.1960 + <listitem><para id="x_3f5">It treats a renamed file as the removal of the 9.1961 + old name, and the addition of the new name. This means 9.1962 + that renamed files have a big footprint in patches. (Note 9.1963 + also that Mercurial does not currently try to infer when 9.1964 + files have been renamed or copied in a patch.)</para> 9.1965 + </listitem> 9.1966 + <listitem><para id="x_3f6"><command>patch</command> cannot represent 9.1967 + empty files, so you cannot use a patch to represent the 9.1968 + notion <quote>I added this empty file to the 9.1969 + tree</quote>.</para> 9.1970 + </listitem></itemizedlist> 9.1971 + </sect2> 9.1972 + 9.1973 + <sect2> 9.1974 + <title>Beware the fuzz</title> 9.1975 + 9.1976 + <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor, 9.1977 + will often be completely successful, these inexact techniques 9.1978 + naturally leave open the possibility of corrupting the patched 9.1979 + file. The most common cases typically involve applying a 9.1980 + patch twice, or at an incorrect location in the file. If 9.1981 + <command>patch</command> or <command 9.1982 + role="hg-ext-mq">qpush</command> ever mentions an offset or 9.1983 + fuzz factor, you should make sure that the modified files are 9.1984 + correct afterwards.</para> 9.1985 + 9.1986 + <para id="x_3f8">It's often a good idea to refresh a patch that has applied 9.1987 + with an offset or fuzz factor; refreshing the patch generates 9.1988 + new context information that will make it apply cleanly. I 9.1989 + say <quote>often,</quote> not <quote>always,</quote> because 9.1990 + sometimes refreshing a patch will make it fail to apply 9.1991 + against a different revision of the underlying files. In some 9.1992 + cases, such as when you're maintaining a patch that must sit 9.1993 + on top of multiple versions of a source tree, it's acceptable 9.1994 + to have a patch apply with some fuzz, provided you've verified 9.1995 + the results of the patching process in such cases.</para> 9.1996 + </sect2> 9.1997 + 9.1998 + <sect2> 9.1999 + <title>Handling rejection</title> 9.2000 + 9.2001 + <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to 9.2002 + apply a patch, it will print an error message and exit. If it 9.2003 + has left <filename role="special">.rej</filename> files 9.2004 + behind, it is usually best to fix up the rejected hunks before 9.2005 + you push more patches or do any further work.</para> 9.2006 + 9.2007 + <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly, 9.2008 + and no longer does because you've changed the underlying code 9.2009 + that your patches are based on, Mercurial Queues can help; see 9.2010 + <xref linkend="sec:mq:merge"/> for details.</para> 9.2011 + 9.2012 + <para id="x_3fb">Unfortunately, there aren't any great techniques for 9.2013 + dealing with rejected hunks. Most often, you'll need to view 9.2014 + the <filename role="special">.rej</filename> file and edit the 9.2015 + target file, applying the rejected hunks by hand.</para> 9.2016 + 9.2017 + <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author 9.2018 + of Mercurial Queues), wrote a tool called 9.2019 + <command>mpatch</command> (<ulink 9.2020 + url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 9.2021 + which takes a simple approach to automating the application of 9.2022 + hunks rejected by <command>patch</command>. The 9.2023 + <command>mpatch</command> command can help with four common 9.2024 + reasons that a hunk may be rejected:</para> 9.2025 + 9.2026 + <itemizedlist> 9.2027 + <listitem><para id="x_3fe">The context in the middle of a hunk has 9.2028 + changed.</para> 9.2029 + </listitem> 9.2030 + <listitem><para id="x_3ff">A hunk is missing some context at the 9.2031 + beginning or end.</para> 9.2032 + </listitem> 9.2033 + <listitem><para id="x_400">A large hunk might apply better&emdash;either 9.2034 + entirely or in part&emdash;if it was broken up into 9.2035 + smaller hunks.</para> 9.2036 + </listitem> 9.2037 + <listitem><para id="x_401">A hunk removes lines with slightly different 9.2038 + content than those currently present in the file.</para> 9.2039 + </listitem></itemizedlist> 9.2040 + 9.2041 + <para id="x_402">If you use <command>mpatch</command>, you 9.2042 + should be doubly careful to check your results when you're 9.2043 + done. In fact, <command>mpatch</command> enforces this method 9.2044 + of double-checking the tool's output, by automatically 9.2045 + dropping you into a merge program when it has done its job, so 9.2046 + that you can verify its work and finish off any remaining 9.2047 + merges.</para> 9.2048 + </sect2> 9.2049 + </sect1> 9.2050 + 9.2051 + <sect1> 9.2052 + <title>More on patch management</title> 9.2053 + 9.2054 + <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting 9.2055 + to perform other kinds of patch management operations.</para> 9.2056 + 9.2057 + <sect2> 9.2058 + <title>Deleting unwanted patches</title> 9.2059 + 9.2060 + <para id="x_6dc">If you want to get rid of a patch, use the <command 9.2061 + role="hg-ext-mq">hg qdelete</command> command to delete the 9.2062 + patch file and remove its entry from the patch series. If you 9.2063 + try to delete a patch that is still applied, <command 9.2064 + role="hg-ext-mq">hg qdelete</command> will refuse.</para> 9.2065 + 9.2066 + &interaction.ch11-qdelete.go; 9.2067 + </sect2> 9.2068 + 9.2069 + <sect2> 9.2070 + <title>Converting to and from permanent revisions</title> 9.2071 + 9.2072 + <para id="x_6dd">Once you're done working on a patch and want to 9.2073 + turn it into a permanent changeset, use the <command 9.2074 + role="hg-ext-mq">hg qfinish</command> command. Pass a revision 9.2075 + to the command to identify the patch that you want to turn into 9.2076 + a regular changeset; this patch must already be applied.</para> 9.2077 + 9.2078 + &interaction.ch11-qdelete.convert; 9.2079 + 9.2080 + <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command 9.2081 + accepts an <option>--all</option> or <option>-a</option> 9.2082 + option, which turns all applied patches into regular 9.2083 + changesets.</para> 9.2084 + 9.2085 + <para id="x_6de">It is also possible to turn an existing changeset into a 9.2086 + patch, by passing the <option>-r</option> option to <command 9.2087 + role="hg-ext-mq">hg qimport</command>.</para> 9.2088 + 9.2089 + &interaction.ch11-qdelete.import; 9.2090 + 9.2091 + <para id="x_6df">Note that it only makes sense to convert a changeset into 9.2092 + a patch if you have not propagated that changeset into any 9.2093 + other repositories. The imported changeset's ID will change 9.2094 + every time you refresh the patch, which will make Mercurial 9.2095 + treat it as unrelated to the original changeset if you have 9.2096 + pushed it somewhere else.</para> 9.2097 + </sect2> 9.2098 + </sect1> 9.2099 + 9.2100 + <sect1 id="sec:mq:perf"> 9.2101 + <title>Getting the best performance out of MQ</title> 9.2102 + 9.2103 + <para id="x_403">MQ is very efficient at handling a large number 9.2104 + of patches. I ran some performance experiments in mid-2006 for a 9.2105 + talk that I gave at the 2006 EuroPython conference (on modern 9.2106 + hardware, you should expect better performance than you'll see 9.2107 + below). I used as my data set the Linux 2.6.17-mm1 patch 9.2108 + series, which consists of 1,738 patches. I applied these on top 9.2109 + of a Linux kernel repository containing all 27,472 revisions 9.2110 + between Linux 2.6.12-rc2 and Linux 2.6.17.</para> 9.2111 + 9.2112 + <para id="x_404">On my old, slow laptop, I was able to <command 9.2113 + role="hg-cmd">hg qpush <option 9.2114 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all 9.2115 + 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 9.2116 + <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> 9.2117 + them all in 30 seconds. (On a newer laptop, the time to push 9.2118 + all patches dropped to two minutes.) I could <command 9.2119 + role="hg-ext-mq">qrefresh</command> one of the biggest patches 9.2120 + (which made 22,779 lines of changes to 287 files) in 6.6 9.2121 + seconds.</para> 9.2122 + 9.2123 + <para id="x_405">Clearly, MQ is well suited to working in large trees, but 9.2124 + there are a few tricks you can use to get the best performance 9.2125 + of it.</para> 9.2126 + 9.2127 + <para id="x_406">First of all, try to <quote>batch</quote> operations 9.2128 + together. Every time you run <command 9.2129 + role="hg-ext-mq">qpush</command> or <command 9.2130 + role="hg-ext-mq">qpop</command>, these commands scan the 9.2131 + working directory once to make sure you haven't made some 9.2132 + changes and then forgotten to run <command 9.2133 + role="hg-ext-mq">qrefresh</command>. On a small tree, the 9.2134 + time that this scan takes is unnoticeable. However, on a 9.2135 + medium-sized tree (containing tens of thousands of files), it 9.2136 + can take a second or more.</para> 9.2137 + 9.2138 + <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command 9.2139 + role="hg-ext-mq">qpop</command> commands allow you to push and 9.2140 + pop multiple patches at a time. You can identify the 9.2141 + <quote>destination patch</quote> that you want to end up at. 9.2142 + When you <command role="hg-ext-mq">qpush</command> with a 9.2143 + destination specified, it will push patches until that patch is 9.2144 + at the top of the applied stack. When you <command 9.2145 + role="hg-ext-mq">qpop</command> to a destination, MQ will pop 9.2146 + patches until the destination patch is at the top.</para> 9.2147 + 9.2148 + <para id="x_408">You can identify a destination patch using either the name 9.2149 + of the patch, or by number. If you use numeric addressing, 9.2150 + patches are counted from zero; this means that the first patch 9.2151 + is zero, the second is one, and so on.</para> 9.2152 + </sect1> 9.2153 + 9.2154 + <sect1 id="sec:mq:merge"> 9.2155 + <title>Updating your patches when the underlying code 9.2156 + changes</title> 9.2157 + 9.2158 + <para id="x_409">It's common to have a stack of patches on top of an 9.2159 + underlying repository that you don't modify directly. If you're 9.2160 + working on changes to third-party code, or on a feature that is 9.2161 + taking longer to develop than the rate of change of the code 9.2162 + beneath, you will often need to sync up with the underlying 9.2163 + code, and fix up any hunks in your patches that no longer apply. 9.2164 + This is called <emphasis>rebasing</emphasis> your patch 9.2165 + series.</para> 9.2166 + 9.2167 + <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg 9.2168 + qpop <option role="hg-ext-mq-cmd-qpop-opt">hg 9.2169 + -a</option></command> your patches, then <command 9.2170 + role="hg-cmd">hg pull</command> changes into the underlying 9.2171 + repository, and finally <command role="hg-cmd">hg qpush <option 9.2172 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your 9.2173 + patches again. MQ will stop pushing any time it runs across a 9.2174 + patch that fails to apply during conflicts, allowing you to fix 9.2175 + your conflicts, <command role="hg-ext-mq">qrefresh</command> the 9.2176 + affected patch, and continue pushing until you have fixed your 9.2177 + entire stack.</para> 9.2178 + 9.2179 + <para id="x_40b">This approach is easy to use and works well if you don't 9.2180 + expect changes to the underlying code to affect how well your 9.2181 + patches apply. If your patch stack touches code that is modified 9.2182 + frequently or invasively in the underlying repository, however, 9.2183 + fixing up rejected hunks by hand quickly becomes 9.2184 + tiresome.</para> 9.2185 + 9.2186 + <para id="x_40c">It's possible to partially automate the rebasing process. 9.2187 + If your patches apply cleanly against some revision of the 9.2188 + underlying repo, MQ can use this information to help you to 9.2189 + resolve conflicts between your patches and a different 9.2190 + revision.</para> 9.2191 + 9.2192 + <para id="x_40d">The process is a little involved.</para> 9.2193 + <orderedlist> 9.2194 + <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush 9.2195 + -a</command> all of your patches on top of the revision 9.2196 + where you know that they apply cleanly.</para> 9.2197 + </listitem> 9.2198 + <listitem><para id="x_40f">Save a backup copy of your patch directory using 9.2199 + <command role="hg-cmd">hg qsave <option 9.2200 + role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option 9.2201 + role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>. 9.2202 + This prints the name of the directory that it has saved the 9.2203 + patches in. It will save the patches to a directory called 9.2204 + <filename role="special" 9.2205 + class="directory">.hg/patches.N</filename>, where 9.2206 + <literal>N</literal> is a small integer. It also commits a 9.2207 + <quote>save changeset</quote> on top of your applied 9.2208 + patches; this is for internal book-keeping, and records the 9.2209 + states of the <filename role="special">series</filename> and 9.2210 + <filename role="special">status</filename> files.</para> 9.2211 + </listitem> 9.2212 + <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to 9.2213 + bring new changes into the underlying repository. (Don't 9.2214 + run <command role="hg-cmd">hg pull -u</command>; see below 9.2215 + for why.)</para> 9.2216 + </listitem> 9.2217 + <listitem><para id="x_411">Update to the new tip revision, using <command 9.2218 + role="hg-cmd">hg update <option 9.2219 + role="hg-opt-update">-C</option></command> to override 9.2220 + the patches you have pushed.</para> 9.2221 + </listitem> 9.2222 + <listitem><para id="x_412">Merge all patches using <command>hg qpush -m 9.2223 + -a</command>. The <option 9.2224 + role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 9.2225 + <command role="hg-ext-mq">qpush</command> tells MQ to 9.2226 + perform a three-way merge if the patch fails to 9.2227 + apply.</para> 9.2228 + </listitem></orderedlist> 9.2229 + 9.2230 + <para id="x_413">During the <command role="hg-cmd">hg qpush <option 9.2231 + role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>, 9.2232 + each patch in the <filename role="special">series</filename> 9.2233 + file is applied normally. If a patch applies with fuzz or 9.2234 + rejects, MQ looks at the queue you <command 9.2235 + role="hg-ext-mq">qsave</command>d, and performs a three-way 9.2236 + merge with the corresponding changeset. This merge uses 9.2237 + Mercurial's normal merge machinery, so it may pop up a GUI merge 9.2238 + tool to help you to resolve problems.</para> 9.2239 + 9.2240 + <para id="x_414">When you finish resolving the effects of a patch, MQ 9.2241 + refreshes your patch based on the result of the merge.</para> 9.2242 + 9.2243 + <para id="x_415">At the end of this process, your repository will have one 9.2244 + extra head from the old patch queue, and a copy of the old patch 9.2245 + queue will be in <filename role="special" 9.2246 + class="directory">.hg/patches.N</filename>. You can remove the 9.2247 + extra head using <command role="hg-cmd">hg qpop -a -n 9.2248 + patches.N</command> or <command role="hg-cmd">hg 9.2249 + strip</command>. You can delete <filename role="special" 9.2250 + class="directory">.hg/patches.N</filename> once you are sure 9.2251 + that you no longer need it as a backup.</para> 9.2252 + </sect1> 9.2253 + 9.2254 + <sect1> 9.2255 + <title>Identifying patches</title> 9.2256 + 9.2257 + <para id="x_416">MQ commands that work with patches let you refer to a patch 9.2258 + either by using its name or by a number. By name is obvious 9.2259 + enough; pass the name <filename>foo.patch</filename> to <command 9.2260 + role="hg-ext-mq">qpush</command>, for example, and it will 9.2261 + push patches until <filename>foo.patch</filename> is 9.2262 + applied.</para> 9.2263 + 9.2264 + <para id="x_417">As a shortcut, you can refer to a patch using both a name 9.2265 + and a numeric offset; <literal>foo.patch-2</literal> means 9.2266 + <quote>two patches before <literal>foo.patch</literal></quote>, 9.2267 + while <literal>bar.patch+4</literal> means <quote>four patches 9.2268 + after <literal>bar.patch</literal></quote>.</para> 9.2269 + 9.2270 + <para id="x_418">Referring to a patch by index isn't much different. The 9.2271 + first patch printed in the output of <command 9.2272 + role="hg-ext-mq">qseries</command> is patch zero (yes, it's 9.2273 + one of those start-at-zero counting systems); the second is 9.2274 + patch one; and so on.</para> 9.2275 + 9.2276 + <para id="x_419">MQ also makes it easy to work with patches when you are 9.2277 + using normal Mercurial commands. Every command that accepts a 9.2278 + changeset ID will also accept the name of an applied patch. MQ 9.2279 + augments the tags normally in the repository with an eponymous 9.2280 + one for each applied patch. In addition, the special tags 9.2281 + <literal role="tag">qbase</literal> and 9.2282 + <literal role="tag">qtip</literal> identify 9.2283 + the <quote>bottom-most</quote> and topmost applied patches, 9.2284 + respectively.</para> 9.2285 + 9.2286 + <para id="x_41a">These additions to Mercurial's normal tagging capabilities 9.2287 + make dealing with patches even more of a breeze.</para> 9.2288 + <itemizedlist> 9.2289 + <listitem><para id="x_41b">Want to patchbomb a mailing list with your 9.2290 + latest series of changes?</para> 9.2291 + <programlisting>hg email qbase:qtip</programlisting> 9.2292 + <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See 9.2293 + <xref linkend="sec:hgext:patchbomb"/>.)</para> 9.2294 + </listitem> 9.2295 + <listitem><para id="x_41d">Need to see all of the patches since 9.2296 + <literal>foo.patch</literal> that have touched files in a 9.2297 + subdirectory of your tree?</para> 9.2298 + <programlisting>hg log -r foo.patch:qtip subdir</programlisting> 9.2299 + </listitem> 9.2300 + </itemizedlist> 9.2301 + 9.2302 + <para id="x_41e">Because MQ makes the names of patches available to the rest 9.2303 + of Mercurial through its normal internal tag machinery, you 9.2304 + don't need to type in the entire name of a patch when you want 9.2305 + to identify it by name.</para> 9.2306 + 9.2307 + <para id="x_41f">Another nice consequence of representing patch names as tags 9.2308 + is that when you run the <command role="hg-cmd">hg log</command> 9.2309 + command, it will display a patch's name as a tag, simply as part 9.2310 + of its normal output. This makes it easy to visually 9.2311 + distinguish applied patches from underlying 9.2312 + <quote>normal</quote> revisions. The following example shows a 9.2313 + few normal Mercurial commands in use with applied 9.2314 + patches.</para> 9.2315 + 9.2316 + &interaction.mq.id.output; 9.2317 + </sect1> 9.2318 + 9.2319 + <sect1> 9.2320 + <title>Useful things to know about</title> 9.2321 + 9.2322 + <para id="x_420">There are a number of aspects of MQ usage that don't fit 9.2323 + tidily into sections of their own, but that are good to know. 9.2324 + Here they are, in one place.</para> 9.2325 + 9.2326 + <itemizedlist> 9.2327 + <listitem><para id="x_421">Normally, when you <command 9.2328 + role="hg-ext-mq">qpop</command> a patch and <command 9.2329 + role="hg-ext-mq">qpush</command> it again, the changeset 9.2330 + that represents the patch after the pop/push will have a 9.2331 + <emphasis>different identity</emphasis> than the changeset 9.2332 + that represented the hash beforehand. See <xref 9.2333 + linkend="sec:mqref:cmd:qpush"/> for 9.2334 + information as to why this is.</para> 9.2335 + </listitem> 9.2336 + <listitem><para id="x_422">It's not a good idea to <command 9.2337 + role="hg-cmd">hg merge</command> changes from another 9.2338 + branch with a patch changeset, at least if you want to 9.2339 + maintain the <quote>patchiness</quote> of that changeset and 9.2340 + changesets below it on the patch stack. If you try to do 9.2341 + this, it will appear to succeed, but MQ will become 9.2342 + confused.</para> 9.2343 + </listitem></itemizedlist> 9.2344 + </sect1> 9.2345 + 9.2346 + <sect1 id="sec:mq:repo"> 9.2347 + <title>Managing patches in a repository</title> 9.2348 + 9.2349 + <para id="x_423">Because MQ's <filename role="special" 9.2350 + class="directory">.hg/patches</filename> directory resides 9.2351 + outside a Mercurial repository's working directory, the 9.2352 + <quote>underlying</quote> Mercurial repository knows nothing 9.2353 + about the management or presence of patches.</para> 9.2354 + 9.2355 + <para id="x_424">This presents the interesting possibility of managing the 9.2356 + contents of the patch directory as a Mercurial repository in its 9.2357 + own right. This can be a useful way to work. For example, you 9.2358 + can work on a patch for a while, <command 9.2359 + role="hg-ext-mq">qrefresh</command> it, then <command 9.2360 + role="hg-cmd">hg commit</command> the current state of the 9.2361 + patch. This lets you <quote>roll back</quote> to that version 9.2362 + of the patch later on.</para> 9.2363 + 9.2364 + <para id="x_425">You can then share different versions of the same patch 9.2365 + stack among multiple underlying repositories. I use this when I 9.2366 + am developing a Linux kernel feature. I have a pristine copy of 9.2367 + my kernel sources for each of several CPU architectures, and a 9.2368 + cloned repository under each that contains the patches I am 9.2369 + working on. When I want to test a change on a different 9.2370 + architecture, I push my current patches to the patch repository 9.2371 + associated with that kernel tree, pop and push all of my 9.2372 + patches, and build and test that kernel.</para> 9.2373 + 9.2374 + <para id="x_426">Managing patches in a repository makes it possible for 9.2375 + multiple developers to work on the same patch series without 9.2376 + colliding with each other, all on top of an underlying source 9.2377 + base that they may or may not control.</para> 9.2378 + 9.2379 + <sect2> 9.2380 + <title>MQ support for patch repositories</title> 9.2381 + 9.2382 + <para id="x_427">MQ helps you to work with the <filename role="special" 9.2383 + class="directory">.hg/patches</filename> directory as a 9.2384 + repository; when you prepare a repository for working with 9.2385 + patches using <command role="hg-ext-mq">qinit</command>, you 9.2386 + can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg 9.2387 + -c</option> option to create the <filename role="special" 9.2388 + class="directory">.hg/patches</filename> directory as a 9.2389 + Mercurial repository.</para> 9.2390 + 9.2391 + <note> 9.2392 + <para id="x_428"> If you forget to use the <option 9.2393 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you 9.2394 + can simply go into the <filename role="special" 9.2395 + class="directory">.hg/patches</filename> directory at any 9.2396 + time and run <command role="hg-cmd">hg init</command>. 9.2397 + Don't forget to add an entry for the <filename 9.2398 + role="special">status</filename> file to the <filename 9.2399 + role="special">.hgignore</filename> file, though</para> 9.2400 + 9.2401 + <para id="x_429"> (<command role="hg-cmd">hg qinit <option 9.2402 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command> 9.2403 + does this for you automatically); you 9.2404 + <emphasis>really</emphasis> don't want to manage the 9.2405 + <filename role="special">status</filename> file.</para> 9.2406 + </note> 9.2407 + 9.2408 + <para id="x_42a">As a convenience, if MQ notices that the <filename 9.2409 + class="directory">.hg/patches</filename> directory is a 9.2410 + repository, it will automatically <command role="hg-cmd">hg 9.2411 + add</command> every patch that you create and import.</para> 9.2412 + 9.2413 + <para id="x_42b">MQ provides a shortcut command, <command 9.2414 + role="hg-ext-mq">qcommit</command>, that runs <command 9.2415 + role="hg-cmd">hg commit</command> in the <filename 9.2416 + role="special" class="directory">.hg/patches</filename> 9.2417 + directory. This saves some bothersome typing.</para> 9.2418 + 9.2419 + <para id="x_42c">Finally, as a convenience to manage the patch directory, 9.2420 + you can define the alias <command>mq</command> on Unix 9.2421 + systems. For example, on Linux systems using the 9.2422 + <command>bash</command> shell, you can include the following 9.2423 + snippet in your <filename 9.2424 + role="home">~/.bashrc</filename>.</para> 9.2425 + 9.2426 + <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting> 9.2427 + 9.2428 + <para id="x_42d">You can then issue commands of the form <command>mq 9.2429 + pull</command> from the main repository.</para> 9.2430 + </sect2> 9.2431 + 9.2432 + <sect2> 9.2433 + <title>A few things to watch out for</title> 9.2434 + 9.2435 + <para id="x_42e">MQ's support for working with a repository full of patches 9.2436 + is limited in a few small respects.</para> 9.2437 + 9.2438 + <para id="x_42f">MQ cannot automatically detect changes that you make to 9.2439 + the patch directory. If you <command role="hg-cmd">hg 9.2440 + pull</command>, manually edit, or <command role="hg-cmd">hg 9.2441 + update</command> changes to patches or the <filename 9.2442 + role="special">series</filename> file, you will have to 9.2443 + <command role="hg-cmd">hg qpop <option 9.2444 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and 9.2445 + then <command role="hg-cmd">hg qpush <option 9.2446 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in 9.2447 + the underlying repository to see those changes show up there. 9.2448 + If you forget to do this, you can confuse MQ's idea of which 9.2449 + patches are applied.</para> 9.2450 + 9.2451 + </sect2> 9.2452 + </sect1> 9.2453 + <sect1 id="sec:mq:tools"> 9.2454 + <title>Third party tools for working with patches</title> 9.2455 + 9.2456 + <para id="x_430">Once you've been working with patches for a while, you'll 9.2457 + find yourself hungry for tools that will help you to understand 9.2458 + and manipulate the patches you're dealing with.</para> 9.2459 + 9.2460 + <para id="x_431">The <command>diffstat</command> command 9.2461 + <citation>web:diffstat</citation> generates a histogram of the 9.2462 + modifications made to each file in a patch. It provides a good 9.2463 + way to <quote>get a sense of</quote> a patch&emdash;which files 9.2464 + it affects, and how much change it introduces to each file and 9.2465 + as a whole. (I find that it's a good idea to use 9.2466 + <command>diffstat</command>'s <option 9.2467 + role="cmd-opt-diffstat">-p</option> option as a matter of 9.2468 + course, as otherwise it will try to do clever things with 9.2469 + prefixes of file names that inevitably confuse at least 9.2470 + me.)</para> 9.2471 + 9.2472 +&interaction.mq.tools.tools; 9.2473 + 9.2474 + <para id="x_432">The <literal role="package">patchutils</literal> package 9.2475 + <citation>web:patchutils</citation> is invaluable. It provides a 9.2476 + set of small utilities that follow the <quote>Unix 9.2477 + philosophy;</quote> each does one useful thing with a patch. 9.2478 + The <literal role="package">patchutils</literal> command I use 9.2479 + most is <command>filterdiff</command>, which extracts subsets 9.2480 + from a patch file. For example, given a patch that modifies 9.2481 + hundreds of files across dozens of directories, a single 9.2482 + invocation of <command>filterdiff</command> can generate a 9.2483 + smaller patch that only touches files whose names match a 9.2484 + particular glob pattern. See <xref 9.2485 + linkend="mq-collab:tips:interdiff"/> for another 9.2486 + example.</para> 9.2487 + 9.2488 + </sect1> 9.2489 + <sect1> 9.2490 + <title>Good ways to work with patches</title> 9.2491 + 9.2492 + <para id="x_433">Whether you are working on a patch series to submit to a 9.2493 + free software or open source project, or a series that you 9.2494 + intend to treat as a sequence of regular changesets when you're 9.2495 + done, you can use some simple techniques to keep your work well 9.2496 + organized.</para> 9.2497 + 9.2498 + <para id="x_434">Give your patches descriptive names. A good name for a 9.2499 + patch might be <filename>rework-device-alloc.patch</filename>, 9.2500 + because it will immediately give you a hint what the purpose of 9.2501 + the patch is. Long names shouldn't be a problem; you won't be 9.2502 + typing the names often, but you <emphasis>will</emphasis> be 9.2503 + running commands like <command 9.2504 + role="hg-ext-mq">qapplied</command> and <command 9.2505 + role="hg-ext-mq">qtop</command> over and over. Good naming 9.2506 + becomes especially important when you have a number of patches 9.2507 + to work with, or if you are juggling a number of different tasks 9.2508 + and your patches only get a fraction of your attention.</para> 9.2509 + 9.2510 + <para id="x_435">Be aware of what patch you're working on. Use the <command 9.2511 + role="hg-ext-mq">qtop</command> command and skim over the text 9.2512 + of your patches frequently&emdash;for example, using <command 9.2513 + role="hg-cmd">hg tip <option 9.2514 + role="hg-opt-tip">-p</option></command>)&emdash;to be sure 9.2515 + of where you stand. I have several times worked on and <command 9.2516 + role="hg-ext-mq">qrefresh</command>ed a patch other than the 9.2517 + one I intended, and it's often tricky to migrate changes into 9.2518 + the right patch after making them in the wrong one.</para> 9.2519 + 9.2520 + <para id="x_436">For this reason, it is very much worth investing a little 9.2521 + time to learn how to use some of the third-party tools I 9.2522 + described in <xref linkend="sec:mq:tools"/>, 9.2523 + particularly 9.2524 + <command>diffstat</command> and <command>filterdiff</command>. 9.2525 + The former will give you a quick idea of what changes your patch 9.2526 + is making, while the latter makes it easy to splice hunks 9.2527 + selectively out of one patch and into another.</para> 9.2528 + 9.2529 + </sect1> 9.2530 + <sect1> 9.2531 + <title>MQ cookbook</title> 9.2532 + 9.2533 + <sect2> 9.2534 + <title>Manage <quote>trivial</quote> patches</title> 9.2535 + 9.2536 + <para id="x_437">Because the overhead of dropping files into a new 9.2537 + Mercurial repository is so low, it makes a lot of sense to 9.2538 + manage patches this way even if you simply want to make a few 9.2539 + changes to a source tarball that you downloaded.</para> 9.2540 + 9.2541 + <para id="x_438">Begin by downloading and unpacking the source tarball, and 9.2542 + turning it into a Mercurial repository.</para> 9.2543 + 9.2544 + &interaction.mq.tarball.download; 9.2545 + 9.2546 + <para id="x_439">Continue by creating a patch stack and making your 9.2547 + changes.</para> 9.2548 + 9.2549 + &interaction.mq.tarball.qinit; 9.2550 + 9.2551 + <para id="x_43a">Let's say a few weeks or months pass, and your package 9.2552 + author releases a new version. First, bring their changes 9.2553 + into the repository.</para> 9.2554 + 9.2555 + &interaction.mq.tarball.newsource; 9.2556 + 9.2557 + <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg 9.2558 + locate</command> above deletes all files in the working 9.2559 + directory, so that <command role="hg-cmd">hg 9.2560 + commit</command>'s <option 9.2561 + role="hg-opt-commit">--addremove</option> option can 9.2562 + actually tell which files have really been removed in the 9.2563 + newer version of the source.</para> 9.2564 + 9.2565 + <para id="x_43c">Finally, you can apply your patches on top of the new 9.2566 + tree.</para> 9.2567 + 9.2568 + &interaction.mq.tarball.repush; 9.2569 + </sect2> 9.2570 + 9.2571 + <sect2 id="sec:mq:combine"> 9.2572 + <title>Combining entire patches</title> 9.2573 + 9.2574 + <para id="x_43d">MQ provides a command, <command 9.2575 + role="hg-ext-mq">qfold</command> that lets you combine 9.2576 + entire patches. This <quote>folds</quote> the patches you 9.2577 + name, in the order you name them, into the topmost applied 9.2578 + patch, and concatenates their descriptions onto the end of its 9.2579 + description. The patches that you fold must be unapplied 9.2580 + before you fold them.</para> 9.2581 + 9.2582 + <para id="x_43e">The order in which you fold patches matters. If your 9.2583 + topmost applied patch is <literal>foo</literal>, and you 9.2584 + <command role="hg-ext-mq">qfold</command> 9.2585 + <literal>bar</literal> and <literal>quux</literal> into it, 9.2586 + you will end up with a patch that has the same effect as if 9.2587 + you applied first <literal>foo</literal>, then 9.2588 + <literal>bar</literal>, followed by 9.2589 + <literal>quux</literal>.</para> 9.2590 + </sect2> 9.2591 + 9.2592 + <sect2> 9.2593 + <title>Merging part of one patch into another</title> 9.2594 + 9.2595 + <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into 9.2596 + another is more difficult than combining entire 9.2597 + patches.</para> 9.2598 + 9.2599 + <para id="x_440">If you want to move changes to entire files, you can use 9.2600 + <command>filterdiff</command>'s <option 9.2601 + role="cmd-opt-filterdiff">-i</option> and <option 9.2602 + role="cmd-opt-filterdiff">-x</option> options to choose the 9.2603 + modifications to snip out of one patch, concatenating its 9.2604 + output onto the end of the patch you want to merge into. You 9.2605 + usually won't need to modify the patch you've merged the 9.2606 + changes from. Instead, MQ will report some rejected hunks 9.2607 + when you <command role="hg-ext-mq">qpush</command> it (from 9.2608 + the hunks you moved into the other patch), and you can simply 9.2609 + <command role="hg-ext-mq">qrefresh</command> the patch to drop 9.2610 + the duplicate hunks.</para> 9.2611 + 9.2612 + <para id="x_441">If you have a patch that has multiple hunks modifying a 9.2613 + file, and you only want to move a few of those hunks, the job 9.2614 + becomes more messy, but you can still partly automate it. Use 9.2615 + <command>lsdiff -nvv</command> to print some metadata about 9.2616 + the patch.</para> 9.2617 + 9.2618 + &interaction.mq.tools.lsdiff; 9.2619 + 9.2620 + <para id="x_442">This command prints three different kinds of 9.2621 + number:</para> 9.2622 + <itemizedlist> 9.2623 + <listitem><para id="x_443">(in the first column) a <emphasis>file 9.2624 + number</emphasis> to identify each file modified in the 9.2625 + patch;</para> 9.2626 + </listitem> 9.2627 + <listitem><para id="x_444">(on the next line, indented) the line number 9.2628 + within a modified file where a hunk starts; and</para> 9.2629 + </listitem> 9.2630 + <listitem><para id="x_445">(on the same line) a <emphasis>hunk 9.2631 + number</emphasis> to identify that hunk.</para> 9.2632 + </listitem></itemizedlist> 9.2633 + 9.2634 + <para id="x_446">You'll have to use some visual inspection, and reading of 9.2635 + the patch, to identify the file and hunk numbers you'll want, 9.2636 + but you can then pass them to to 9.2637 + <command>filterdiff</command>'s <option 9.2638 + role="cmd-opt-filterdiff">--files</option> and <option 9.2639 + role="cmd-opt-filterdiff">--hunks</option> options, to 9.2640 + select exactly the file and hunk you want to extract.</para> 9.2641 + 9.2642 + <para id="x_447">Once you have this hunk, you can concatenate it onto the 9.2643 + end of your destination patch and continue with the remainder 9.2644 + of <xref linkend="sec:mq:combine"/>.</para> 9.2645 + 9.2646 + </sect2> 9.2647 + </sect1> 9.2648 + <sect1> 9.2649 + <title>Differences between quilt and MQ</title> 9.2650 + 9.2651 + <para id="x_448">If you are already familiar with quilt, MQ provides a 9.2652 + similar command set. There are a few differences in the way 9.2653 + that it works.</para> 9.2654 + 9.2655 + <para id="x_449">You will already have noticed that most quilt commands have 9.2656 + MQ counterparts that simply begin with a 9.2657 + <quote><literal>q</literal></quote>. The exceptions are quilt's 9.2658 + <literal>add</literal> and <literal>remove</literal> commands, 9.2659 + the counterparts for which are the normal Mercurial <command 9.2660 + role="hg-cmd">hg add</command> and <command role="hg-cmd">hg 9.2661 + remove</command> commands. There is no MQ equivalent of the 9.2662 + quilt <literal>edit</literal> command.</para> 9.2663 + 9.2664 + </sect1> 9.2665 </chapter> 9.2666 9.2667 <!-- 9.2668 local variables: 9.2669 sgml-parent-document: ("00book.xml" "book" "chapter") 9.2670 end: 9.2671 ---> 9.2672 \ No newline at end of file 9.2673 +-->
10.1 --- a/fr/ch13-mq-collab.xml Wed Sep 09 15:25:09 2009 +0200 10.2 +++ b/fr/ch13-mq-collab.xml Wed Sep 09 16:07:36 2009 +0200 10.3 @@ -1,499 +1,525 @@ 10.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 10.5 10.6 -<chapter> 10.7 -<title>Advanced uses of Mercurial Queues</title> 10.8 -<para>\label{chap:mq-collab}</para> 10.9 - 10.10 -<para>While it's easy to pick up straightforward uses of Mercurial Queues, 10.11 -use of a little discipline and some of MQ's less frequently used 10.12 -capabilities makes it possible to work in complicated development 10.13 -environments.</para> 10.14 - 10.15 -<para>In this chapter, I will use as an example a technique I have used to 10.16 -manage the development of an Infiniband device driver for the Linux 10.17 -kernel. The driver in question is large (at least as drivers go), 10.18 -with 25,000 lines of code spread across 35 source files. It is 10.19 -maintained by a small team of developers.</para> 10.20 - 10.21 -<para>While much of the material in this chapter is specific to Linux, the 10.22 -same principles apply to any code base for which you're not the 10.23 -primary owner, and upon which you need to do a lot of development.</para> 10.24 - 10.25 -<sect1> 10.26 -<title>The problem of many targets</title> 10.27 - 10.28 -<para>The Linux kernel changes rapidly, and has never been internally 10.29 -stable; developers frequently make drastic changes between releases. 10.30 -This means that a version of the driver that works well with a 10.31 -particular released version of the kernel will not even <emphasis>compile</emphasis> 10.32 -correctly against, typically, any other version.</para> 10.33 - 10.34 -<para>To maintain a driver, we have to keep a number of distinct versions of 10.35 -Linux in mind.</para> 10.36 -<itemizedlist> 10.37 -<listitem><para>One target is the main Linux kernel development tree. 10.38 - Maintenance of the code is in this case partly shared by other 10.39 - developers in the kernel community, who make <quote>drive-by</quote> 10.40 - modifications to the driver as they develop and refine kernel 10.41 - subsystems.</para> 10.42 -</listitem> 10.43 -<listitem><para>We also maintain a number of <quote>backports</quote> to older versions of 10.44 - the Linux kernel, to support the needs of customers who are running 10.45 - older Linux distributions that do not incorporate our drivers. (To 10.46 - <emphasis>backport</emphasis> a piece of code is to modify it to work in an older 10.47 - version of its target environment than the version it was developed 10.48 - for.)</para> 10.49 -</listitem> 10.50 -<listitem><para>Finally, we make software releases on a schedule that is 10.51 - necessarily not aligned with those used by Linux distributors and 10.52 - kernel developers, so that we can deliver new features to customers 10.53 - without forcing them to upgrade their entire kernels or 10.54 - distributions. 10.55 -</para> 10.56 -</listitem></itemizedlist> 10.57 - 10.58 -<sect2> 10.59 -<title>Tempting approaches that don't work well</title> 10.60 - 10.61 -<para>There are two <quote>standard</quote> ways to maintain a piece of software that 10.62 -has to target many different environments. 10.63 -</para> 10.64 - 10.65 -<para>The first is to maintain a number of branches, each intended for a 10.66 -single target. The trouble with this approach is that you must 10.67 -maintain iron discipline in the flow of changes between repositories. 10.68 -A new feature or bug fix must start life in a <quote>pristine</quote> repository, 10.69 -then percolate out to every backport repository. Backport changes are 10.70 -more limited in the branches they should propagate to; a backport 10.71 -change that is applied to a branch where it doesn't belong will 10.72 -probably stop the driver from compiling. 10.73 -</para> 10.74 - 10.75 -<para>The second is to maintain a single source tree filled with conditional 10.76 -statements that turn chunks of code on or off depending on the 10.77 -intended target. Because these <quote>ifdefs</quote> are not allowed in the 10.78 -Linux kernel tree, a manual or automatic process must be followed to 10.79 -strip them out and yield a clean tree. A code base maintained in this 10.80 -fashion rapidly becomes a rat's nest of conditional blocks that are 10.81 -difficult to understand and maintain. 10.82 -</para> 10.83 - 10.84 -<para>Neither of these approaches is well suited to a situation where you 10.85 -don't <quote>own</quote> the canonical copy of a source tree. In the case of a 10.86 -Linux driver that is distributed with the standard kernel, Linus's 10.87 -tree contains the copy of the code that will be treated by the world 10.88 -as canonical. The upstream version of <quote>my</quote> driver can be modified 10.89 -by people I don't know, without me even finding out about it until 10.90 -after the changes show up in Linus's tree. 10.91 -</para> 10.92 - 10.93 -<para>These approaches have the added weakness of making it difficult to 10.94 -generate well-formed patches to submit upstream. 10.95 -</para> 10.96 - 10.97 -<para>In principle, Mercurial Queues seems like a good candidate to manage a 10.98 -development scenario such as the above. While this is indeed the 10.99 -case, MQ contains a few added features that make the job more 10.100 -pleasant. 10.101 -</para> 10.102 - 10.103 -<para>\section{Conditionally applying patches with 10.104 - guards} 10.105 -</para> 10.106 - 10.107 -<para>Perhaps the best way to maintain sanity with so many targets is to be 10.108 -able to choose specific patches to apply for a given situation. MQ 10.109 -provides a feature called <quote>guards</quote> (which originates with quilt's 10.110 -<literal>guards</literal> command) that does just this. To start off, let's 10.111 -create a simple repository for experimenting in. 10.112 -<!-- &interaction.mq.guards.init; --> 10.113 -This gives us a tiny repository that contains two patches that don't 10.114 -have any dependencies on each other, because they touch different files. 10.115 -</para> 10.116 - 10.117 -<para>The idea behind conditional application is that you can <quote>tag</quote> a 10.118 -patch with a <emphasis>guard</emphasis>, which is simply a text string of your 10.119 -choosing, then tell MQ to select specific guards to use when applying 10.120 -patches. MQ will then either apply, or skip over, a guarded patch, 10.121 -depending on the guards that you have selected. 10.122 -</para> 10.123 - 10.124 -<para>A patch can have an arbitrary number of guards; 10.125 -each one is <emphasis>positive</emphasis> (<quote>apply this patch if this guard is 10.126 -selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if this guard is 10.127 -selected</quote>). A patch with no guards is always applied. 10.128 -</para> 10.129 - 10.130 -</sect2> 10.131 -</sect1> 10.132 -<sect1> 10.133 -<title>Controlling the guards on a patch</title> 10.134 - 10.135 -<para>The <command role="hg-ext-mq">qguard</command> command lets you determine which guards should 10.136 -apply to a patch, or display the guards that are already in effect. 10.137 -Without any arguments, it displays the guards on the current topmost 10.138 -patch. 10.139 -<!-- &interaction.mq.guards.qguard; --> 10.140 -To set a positive guard on a patch, prefix the name of the guard with 10.141 -a <quote><literal>+</literal></quote>. 10.142 -<!-- &interaction.mq.guards.qguard.pos; --> 10.143 -To set a negative guard on a patch, prefix the name of the guard with 10.144 -a <quote><literal>-</literal></quote>. 10.145 -<!-- &interaction.mq.guards.qguard.neg; --> 10.146 -</para> 10.147 - 10.148 -<note> 10.149 -<para> The <command role="hg-ext-mq">qguard</command> command <emphasis>sets</emphasis> the guards on a patch; it 10.150 - doesn't <emphasis>modify</emphasis> them. What this means is that if you run 10.151 - <command role="hg-cmd">hg qguard +a +b</command> on a patch, then <command role="hg-cmd">hg qguard +c</command> on 10.152 - the same patch, the <emphasis>only</emphasis> guard that will be set on it 10.153 - afterwards is <literal>+c</literal>. 10.154 -</para> 10.155 -</note> 10.156 - 10.157 -<para>Mercurial stores guards in the <filename role="special">series</filename> file; the form in 10.158 -which they are stored is easy both to understand and to edit by hand. 10.159 -(In other words, you don't have to use the <command role="hg-ext-mq">qguard</command> command if 10.160 -you don't want to; it's okay to simply edit the <filename role="special">series</filename> 10.161 -file.) 10.162 -<!-- &interaction.mq.guards.series; --> 10.163 -</para> 10.164 - 10.165 -</sect1> 10.166 -<sect1> 10.167 -<title>Selecting the guards to use</title> 10.168 - 10.169 -<para>The <command role="hg-ext-mq">qselect</command> command determines which guards are active at a 10.170 -given time. The effect of this is to determine which patches MQ will 10.171 -apply the next time you run <command role="hg-ext-mq">qpush</command>. It has no other effect; in 10.172 -particular, it doesn't do anything to patches that are already 10.173 -applied. 10.174 -</para> 10.175 - 10.176 -<para>With no arguments, the <command role="hg-ext-mq">qselect</command> command lists the guards 10.177 -currently in effect, one per line of output. Each argument is treated 10.178 -as the name of a guard to apply. 10.179 -<!-- &interaction.mq.guards.qselect.foo; --> 10.180 -In case you're interested, the currently selected guards are stored in 10.181 -the <filename role="special">guards</filename> file. 10.182 -<!-- &interaction.mq.guards.qselect.cat; --> 10.183 -We can see the effect the selected guards have when we run 10.184 -<command role="hg-ext-mq">qpush</command>. 10.185 -<!-- &interaction.mq.guards.qselect.qpush; --> 10.186 -</para> 10.187 - 10.188 -<para>A guard cannot start with a <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote> 10.189 -character. The name of a guard must not contain white space, but most 10.190 -other characters are acceptable. If you try to use a guard with an 10.191 -invalid name, MQ will complain: 10.192 -<!-- &interaction.mq.guards.qselect.error; --> 10.193 -Changing the selected guards changes the patches that are applied. 10.194 -<!-- &interaction.mq.guards.qselect.quux; --> 10.195 -You can see in the example below that negative guards take precedence 10.196 -over positive guards. 10.197 -<!-- &interaction.mq.guards.qselect.foobar; --> 10.198 -</para> 10.199 - 10.200 -</sect1> 10.201 -<sect1> 10.202 -<title>MQ's rules for applying patches</title> 10.203 - 10.204 -<para>The rules that MQ uses when deciding whether to apply a patch 10.205 -are as follows. 10.206 -</para> 10.207 -<itemizedlist> 10.208 -<listitem><para>A patch that has no guards is always applied. 10.209 -</para> 10.210 -</listitem> 10.211 -<listitem><para>If the patch has any negative guard that matches any currently 10.212 - selected guard, the patch is skipped. 10.213 -</para> 10.214 -</listitem> 10.215 -<listitem><para>If the patch has any positive guard that matches any currently 10.216 - selected guard, the patch is applied. 10.217 -</para> 10.218 -</listitem> 10.219 -<listitem><para>If the patch has positive or negative guards, but none matches 10.220 - any currently selected guard, the patch is skipped. 10.221 -</para> 10.222 -</listitem></itemizedlist> 10.223 - 10.224 -</sect1> 10.225 -<sect1> 10.226 -<title>Trimming the work environment</title> 10.227 - 10.228 -<para>In working on the device driver I mentioned earlier, I don't apply the 10.229 -patches to a normal Linux kernel tree. Instead, I use a repository 10.230 -that contains only a snapshot of the source files and headers that are 10.231 -relevant to Infiniband development. This repository is 1% the size 10.232 -of a kernel repository, so it's easier to work with. 10.233 -</para> 10.234 - 10.235 -<para>I then choose a <quote>base</quote> version on top of which the patches are 10.236 -applied. This is a snapshot of the Linux kernel tree as of a revision 10.237 -of my choosing. When I take the snapshot, I record the changeset ID 10.238 -from the kernel repository in the commit message. Since the snapshot 10.239 -preserves the <quote>shape</quote> and content of the relevant parts of the 10.240 -kernel tree, I can apply my patches on top of either my tiny 10.241 -repository or a normal kernel tree. 10.242 -</para> 10.243 - 10.244 -<para>Normally, the base tree atop which the patches apply should be a 10.245 -snapshot of a very recent upstream tree. This best facilitates the 10.246 -development of patches that can easily be submitted upstream with few 10.247 -or no modifications. 10.248 -</para> 10.249 - 10.250 -</sect1> 10.251 -<sect1> 10.252 -<title>Dividing up the <filename role="special">series</filename> file</title> 10.253 - 10.254 -<para>I categorise the patches in the <filename role="special">series</filename> file into a number 10.255 -of logical groups. Each section of like patches begins with a block 10.256 -of comments that describes the purpose of the patches that follow. 10.257 -</para> 10.258 - 10.259 -<para>The sequence of patch groups that I maintain follows. The ordering of 10.260 -these groups is important; I'll describe why after I introduce the 10.261 -groups. 10.262 -</para> 10.263 -<itemizedlist> 10.264 -<listitem><para>The <quote>accepted</quote> group. Patches that the development team has 10.265 - submitted to the maintainer of the Infiniband subsystem, and which 10.266 - he has accepted, but which are not present in the snapshot that the 10.267 - tiny repository is based on. These are <quote>read only</quote> patches, 10.268 - present only to transform the tree into a similar state as it is in 10.269 - the upstream maintainer's repository. 10.270 -</para> 10.271 -</listitem> 10.272 -<listitem><para>The <quote>rework</quote> group. Patches that I have submitted, but that 10.273 - the upstream maintainer has requested modifications to before he 10.274 - will accept them. 10.275 -</para> 10.276 -</listitem> 10.277 -<listitem><para>The <quote>pending</quote> group. Patches that I have not yet submitted to 10.278 - the upstream maintainer, but which we have finished working on. 10.279 - These will be <quote>read only</quote> for a while. If the upstream maintainer 10.280 - accepts them upon submission, I'll move them to the end of the 10.281 - <quote>accepted</quote> group. If he requests that I modify any, I'll move 10.282 - them to the beginning of the <quote>rework</quote> group. 10.283 -</para> 10.284 -</listitem> 10.285 -<listitem><para>The <quote>in progress</quote> group. Patches that are actively being 10.286 - developed, and should not be submitted anywhere yet. 10.287 -</para> 10.288 -</listitem> 10.289 -<listitem><para>The <quote>backport</quote> group. Patches that adapt the source tree to 10.290 - older versions of the kernel tree. 10.291 -</para> 10.292 -</listitem> 10.293 -<listitem><para>The <quote>do not ship</quote> group. Patches that for some reason should 10.294 - never be submitted upstream. For example, one such patch might 10.295 - change embedded driver identification strings to make it easier to 10.296 - distinguish, in the field, between an out-of-tree version of the 10.297 - driver and a version shipped by a distribution vendor. 10.298 -</para> 10.299 -</listitem></itemizedlist> 10.300 - 10.301 -<para>Now to return to the reasons for ordering groups of patches in this 10.302 -way. We would like the lowest patches in the stack to be as stable as 10.303 -possible, so that we will not need to rework higher patches due to 10.304 -changes in context. Putting patches that will never be changed first 10.305 -in the <filename role="special">series</filename> file serves this purpose. 10.306 -</para> 10.307 - 10.308 -<para>We would also like the patches that we know we'll need to modify to be 10.309 -applied on top of a source tree that resembles the upstream tree as 10.310 -closely as possible. This is why we keep accepted patches around for 10.311 -a while. 10.312 -</para> 10.313 - 10.314 -<para>The <quote>backport</quote> and <quote>do not ship</quote> patches float at the end of the 10.315 -<filename role="special">series</filename> file. The backport patches must be applied on top 10.316 -of all other patches, and the <quote>do not ship</quote> patches might as well 10.317 -stay out of harm's way. 10.318 -</para> 10.319 - 10.320 -</sect1> 10.321 -<sect1> 10.322 -<title>Maintaining the patch series</title> 10.323 - 10.324 -<para>In my work, I use a number of guards to control which patches are to 10.325 -be applied. 10.326 -</para> 10.327 - 10.328 -<itemizedlist> 10.329 -<listitem><para><quote>Accepted</quote> patches are guarded with <literal>accepted</literal>. I 10.330 - enable this guard most of the time. When I'm applying the patches 10.331 - on top of a tree where the patches are already present, I can turn 10.332 - this patch off, and the patches that follow it will apply cleanly. 10.333 -</para> 10.334 -</listitem> 10.335 -<listitem><para>Patches that are <quote>finished</quote>, but not yet submitted, have no 10.336 - guards. If I'm applying the patch stack to a copy of the upstream 10.337 - tree, I don't need to enable any guards in order to get a reasonably 10.338 - safe source tree. 10.339 -</para> 10.340 -</listitem> 10.341 -<listitem><para>Those patches that need reworking before being resubmitted are 10.342 - guarded with <literal>rework</literal>. 10.343 -</para> 10.344 -</listitem> 10.345 -<listitem><para>For those patches that are still under development, I use 10.346 - <literal>devel</literal>. 10.347 -</para> 10.348 -</listitem> 10.349 -<listitem><para>A backport patch may have several guards, one for each version 10.350 - of the kernel to which it applies. For example, a patch that 10.351 - backports a piece of code to 2.6.9 will have a <literal>2.6.9</literal> guard. 10.352 -</para> 10.353 -</listitem></itemizedlist> 10.354 -<para>This variety of guards gives me considerable flexibility in 10.355 -determining what kind of source tree I want to end up with. For most 10.356 -situations, the selection of appropriate guards is automated during 10.357 -the build process, but I can manually tune the guards to use for less 10.358 -common circumstances. 10.359 -</para> 10.360 - 10.361 -<sect2> 10.362 -<title>The art of writing backport patches</title> 10.363 - 10.364 -<para>Using MQ, writing a backport patch is a simple process. All such a 10.365 -patch has to do is modify a piece of code that uses a kernel feature 10.366 -not present in the older version of the kernel, so that the driver 10.367 -continues to work correctly under that older version. 10.368 -</para> 10.369 - 10.370 -<para>A useful goal when writing a good backport patch is to make your code 10.371 -look as if it was written for the older version of the kernel you're 10.372 -targeting. The less obtrusive the patch, the easier it will be to 10.373 -understand and maintain. If you're writing a collection of backport 10.374 -patches to avoid the <quote>rat's nest</quote> effect of lots of 10.375 -<literal>#ifdef</literal>s (hunks of source code that are only used 10.376 -conditionally) in your code, don't introduce version-dependent 10.377 -<literal>#ifdef</literal>s into the patches. Instead, write several patches, 10.378 -each of which makes unconditional changes, and control their 10.379 -application using guards. 10.380 -</para> 10.381 - 10.382 -<para>There are two reasons to divide backport patches into a distinct 10.383 -group, away from the <quote>regular</quote> patches whose effects they modify. 10.384 -The first is that intermingling the two makes it more difficult to use 10.385 -a tool like the <literal role="hg-ext">patchbomb</literal> extension to automate the process of 10.386 -submitting the patches to an upstream maintainer. The second is that 10.387 -a backport patch could perturb the context in which a subsequent 10.388 -regular patch is applied, making it impossible to apply the regular 10.389 -patch cleanly <emphasis>without</emphasis> the earlier backport patch already being 10.390 -applied. 10.391 -</para> 10.392 - 10.393 -</sect2> 10.394 -</sect1> 10.395 -<sect1> 10.396 -<title>Useful tips for developing with MQ</title> 10.397 - 10.398 -<sect2> 10.399 -<title>Organising patches in directories</title> 10.400 - 10.401 -<para>If you're working on a substantial project with MQ, it's not difficult 10.402 -to accumulate a large number of patches. For example, I have one 10.403 -patch repository that contains over 250 patches. 10.404 -</para> 10.405 - 10.406 -<para>If you can group these patches into separate logical categories, you 10.407 -can if you like store them in different directories; MQ has no 10.408 -problems with patch names that contain path separators. 10.409 -</para> 10.410 - 10.411 -</sect2> 10.412 -<sect2> 10.413 -<title>Viewing the history of a patch</title> 10.414 -<para>\label{mq-collab:tips:interdiff} 10.415 -</para> 10.416 - 10.417 -<para>If you're developing a set of patches over a long time, it's a good 10.418 -idea to maintain them in a repository, as discussed in 10.419 -section <xref linkend="sec:mq:repo"/>. If you do so, you'll quickly discover that 10.420 -using the <command role="hg-cmd">hg diff</command> command to look at the history of changes to a 10.421 -patch is unworkable. This is in part because you're looking at the 10.422 -second derivative of the real code (a diff of a diff), but also 10.423 -because MQ adds noise to the process by modifying time stamps and 10.424 -directory names when it updates a patch. 10.425 -</para> 10.426 - 10.427 -<para>However, you can use the <literal role="hg-ext">extdiff</literal> extension, which is bundled 10.428 -with Mercurial, to turn a diff of two versions of a patch into 10.429 -something readable. To do this, you will need a third-party package 10.430 -called <literal role="package">patchutils</literal> <citation>web:patchutils</citation>. This provides a 10.431 -command named <command>interdiff</command>, which shows the differences between 10.432 -two diffs as a diff. Used on two versions of the same diff, it 10.433 -generates a diff that represents the diff from the first to the second 10.434 -version. 10.435 -</para> 10.436 - 10.437 -<para>You can enable the <literal role="hg-ext">extdiff</literal> extension in the usual way, by 10.438 -adding a line to the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>. 10.439 -</para> 10.440 -<programlisting> 10.441 -<para> [extensions] 10.442 - extdiff = 10.443 -</para> 10.444 -</programlisting> 10.445 -<para>The <command>interdiff</command> command expects to be passed the names of two 10.446 -files, but the <literal role="hg-ext">extdiff</literal> extension passes the program it runs a 10.447 -pair of directories, each of which can contain an arbitrary number of 10.448 -files. We thus need a small program that will run <command>interdiff</command> 10.449 -on each pair of files in these two directories. This program is 10.450 -available as <filename role="special">hg-interdiff</filename> in the <filename class="directory">examples</filename> 10.451 -directory of the source code repository that accompanies this book. 10.452 -<!-- &example.hg-interdiff; --> 10.453 -</para> 10.454 - 10.455 -<para>With the <filename role="special">hg-interdiff</filename> program in your shell's search path, 10.456 -you can run it as follows, from inside an MQ patch directory: 10.457 -</para> 10.458 -<programlisting> 10.459 -<para> hg extdiff -p hg-interdiff -r A:B my-change.patch 10.460 -</para> 10.461 -</programlisting> 10.462 -<para>Since you'll probably want to use this long-winded command a lot, you 10.463 -can get <literal role="hg-ext">hgext</literal> to make it available as a normal Mercurial 10.464 -command, again by editing your <filename role="special"> /.hgrc</filename>. 10.465 -</para> 10.466 -<programlisting> 10.467 -<para> [extdiff] 10.468 - cmd.interdiff = hg-interdiff 10.469 -</para> 10.470 -</programlisting> 10.471 -<para>This directs <literal role="hg-ext">hgext</literal> to make an <literal>interdiff</literal> command 10.472 -available, so you can now shorten the previous invocation of 10.473 -<command role="hg-ext-extdiff">extdiff</command> to something a little more wieldy. 10.474 -</para> 10.475 -<programlisting> 10.476 -<para> hg interdiff -r A:B my-change.patch 10.477 -</para> 10.478 -</programlisting> 10.479 - 10.480 -<note> 10.481 -<para> The <command>interdiff</command> command works well only if the underlying 10.482 - files against which versions of a patch are generated remain the 10.483 - same. If you create a patch, modify the underlying files, and then 10.484 - regenerate the patch, <command>interdiff</command> may not produce useful 10.485 - output. 10.486 -</para> 10.487 -</note> 10.488 - 10.489 -<para>The <literal role="hg-ext">extdiff</literal> extension is useful for more than merely improving 10.490 -the presentation of MQ patches. To read more about it, go to 10.491 -section <xref linkend="sec:hgext:extdiff"/>. 10.492 -</para> 10.493 - 10.494 -</sect2> 10.495 -</sect1> 10.496 +<chapter id="chap:mq-collab"> 10.497 + <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> 10.498 + <title>Advanced uses of Mercurial Queues</title> 10.499 + 10.500 + <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial 10.501 + Queues, use of a little discipline and some of MQ's less 10.502 + frequently used capabilities makes it possible to work in 10.503 + complicated development environments.</para> 10.504 + 10.505 + <para id="x_15e">In this chapter, I will use as an example a technique I have 10.506 + used to manage the development of an Infiniband device driver for 10.507 + the Linux kernel. The driver in question is large (at least as 10.508 + drivers go), with 25,000 lines of code spread across 35 source 10.509 + files. It is maintained by a small team of developers.</para> 10.510 + 10.511 + <para id="x_15f">While much of the material in this chapter is specific to 10.512 + Linux, the same principles apply to any code base for which you're 10.513 + not the primary owner, and upon which you need to do a lot of 10.514 + development.</para> 10.515 + 10.516 + <sect1> 10.517 + <title>The problem of many targets</title> 10.518 + 10.519 + <para id="x_160">The Linux kernel changes rapidly, and has never been 10.520 + internally stable; developers frequently make drastic changes 10.521 + between releases. This means that a version of the driver that 10.522 + works well with a particular released version of the kernel will 10.523 + not even <emphasis>compile</emphasis> correctly against, 10.524 + typically, any other version.</para> 10.525 + 10.526 + <para id="x_161">To maintain a driver, we have to keep a number of distinct 10.527 + versions of Linux in mind.</para> 10.528 + <itemizedlist> 10.529 + <listitem><para id="x_162">One target is the main Linux kernel development 10.530 + tree. Maintenance of the code is in this case partly shared 10.531 + by other developers in the kernel community, who make 10.532 + <quote>drive-by</quote> modifications to the driver as they 10.533 + develop and refine kernel subsystems.</para> 10.534 + </listitem> 10.535 + <listitem><para id="x_163">We also maintain a number of 10.536 + <quote>backports</quote> to older versions of the Linux 10.537 + kernel, to support the needs of customers who are running 10.538 + older Linux distributions that do not incorporate our 10.539 + drivers. (To <emphasis>backport</emphasis> a piece of code 10.540 + is to modify it to work in an older version of its target 10.541 + environment than the version it was developed for.)</para> 10.542 + </listitem> 10.543 + <listitem><para id="x_164">Finally, we make software releases on a schedule 10.544 + that is necessarily not aligned with those used by Linux 10.545 + distributors and kernel developers, so that we can deliver 10.546 + new features to customers without forcing them to upgrade 10.547 + their entire kernels or distributions.</para> 10.548 + </listitem></itemizedlist> 10.549 + 10.550 + <sect2> 10.551 + <title>Tempting approaches that don't work well</title> 10.552 + 10.553 + <para id="x_165">There are two <quote>standard</quote> ways to maintain a 10.554 + piece of software that has to target many different 10.555 + environments.</para> 10.556 + 10.557 + <para id="x_166">The first is to maintain a number of branches, each 10.558 + intended for a single target. The trouble with this approach 10.559 + is that you must maintain iron discipline in the flow of 10.560 + changes between repositories. A new feature or bug fix must 10.561 + start life in a <quote>pristine</quote> repository, then 10.562 + percolate out to every backport repository. Backport changes 10.563 + are more limited in the branches they should propagate to; a 10.564 + backport change that is applied to a branch where it doesn't 10.565 + belong will probably stop the driver from compiling.</para> 10.566 + 10.567 + <para id="x_167">The second is to maintain a single source tree filled with 10.568 + conditional statements that turn chunks of code on or off 10.569 + depending on the intended target. Because these 10.570 + <quote>ifdefs</quote> are not allowed in the Linux kernel 10.571 + tree, a manual or automatic process must be followed to strip 10.572 + them out and yield a clean tree. A code base maintained in 10.573 + this fashion rapidly becomes a rat's nest of conditional 10.574 + blocks that are difficult to understand and maintain.</para> 10.575 + 10.576 + <para id="x_168">Neither of these approaches is well suited to a situation 10.577 + where you don't <quote>own</quote> the canonical copy of a 10.578 + source tree. In the case of a Linux driver that is 10.579 + distributed with the standard kernel, Linus's tree contains 10.580 + the copy of the code that will be treated by the world as 10.581 + canonical. The upstream version of <quote>my</quote> driver 10.582 + can be modified by people I don't know, without me even 10.583 + finding out about it until after the changes show up in 10.584 + Linus's tree.</para> 10.585 + 10.586 + <para id="x_169">These approaches have the added weakness of making it 10.587 + difficult to generate well-formed patches to submit 10.588 + upstream.</para> 10.589 + 10.590 + <para id="x_16a">In principle, Mercurial Queues seems like a good candidate 10.591 + to manage a development scenario such as the above. While 10.592 + this is indeed the case, MQ contains a few added features that 10.593 + make the job more pleasant.</para> 10.594 + 10.595 + </sect2> 10.596 + </sect1> 10.597 + <sect1> 10.598 + <title>Conditionally applying patches with guards</title> 10.599 + 10.600 + <para id="x_16b">Perhaps the best way to maintain sanity with so many targets 10.601 + is to be able to choose specific patches to apply for a given 10.602 + situation. MQ provides a feature called <quote>guards</quote> 10.603 + (which originates with quilt's <literal>guards</literal> 10.604 + command) that does just this. To start off, let's create a 10.605 + simple repository for experimenting in.</para> 10.606 + 10.607 + &interaction.mq.guards.init; 10.608 + 10.609 + <para id="x_16c">This gives us a tiny repository that contains two patches 10.610 + that don't have any dependencies on each other, because they 10.611 + touch different files.</para> 10.612 + 10.613 + <para id="x_16d">The idea behind conditional application is that you can 10.614 + <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 10.615 + which is simply a text string of your choosing, then tell MQ to 10.616 + select specific guards to use when applying patches. MQ will 10.617 + then either apply, or skip over, a guarded patch, depending on 10.618 + the guards that you have selected.</para> 10.619 + 10.620 + <para id="x_16e">A patch can have an arbitrary number of guards; each one is 10.621 + <emphasis>positive</emphasis> (<quote>apply this patch if this 10.622 + guard is selected</quote>) or <emphasis>negative</emphasis> 10.623 + (<quote>skip this patch if this guard is selected</quote>). A 10.624 + patch with no guards is always applied.</para> 10.625 + 10.626 + </sect1> 10.627 + <sect1> 10.628 + <title>Controlling the guards on a patch</title> 10.629 + 10.630 + <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets 10.631 + you determine which guards should apply to a patch, or display 10.632 + the guards that are already in effect. Without any arguments, it 10.633 + displays the guards on the current topmost patch.</para> 10.634 + 10.635 + &interaction.mq.guards.qguard; 10.636 + 10.637 + <para id="x_170">To set a positive guard on a patch, prefix the name of the 10.638 + guard with a <quote><literal>+</literal></quote>.</para> 10.639 + 10.640 + &interaction.mq.guards.qguard.pos; 10.641 + 10.642 + <para id="x_171">To set a negative guard 10.643 + on a patch, prefix the name of the guard with a 10.644 + <quote><literal>-</literal></quote>.</para> 10.645 + 10.646 + &interaction.mq.guards.qguard.neg; 10.647 + 10.648 + <para id="x_74a">Notice that we prefixed the arguments to the <command>hg 10.649 + qguard</command> command with a <literal>--</literal> here, so 10.650 + that Mercurial would not interpret the text 10.651 + <literal>-quux</literal> as an option.</para> 10.652 + 10.653 + <note> 10.654 + <title>Setting vs. modifying</title> 10.655 + 10.656 + <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command 10.657 + <emphasis>sets</emphasis> the guards on a patch; it doesn't 10.658 + <emphasis>modify</emphasis> them. What this means is that if 10.659 + you run <command role="hg-cmd">hg qguard +a +b</command> on a 10.660 + patch, then <command role="hg-cmd">hg qguard +c</command> on 10.661 + the same patch, the <emphasis>only</emphasis> guard that will 10.662 + be set on it afterwards is <literal>+c</literal>.</para> 10.663 + </note> 10.664 + 10.665 + <para id="x_173">Mercurial stores guards in the <filename 10.666 + role="special">series</filename> file; the form in which they 10.667 + are stored is easy both to understand and to edit by hand. (In 10.668 + other words, you don't have to use the <command 10.669 + role="hg-ext-mq">qguard</command> command if you don't want 10.670 + to; it's okay to simply edit the <filename 10.671 + role="special">series</filename> file.)</para> 10.672 + 10.673 + &interaction.mq.guards.series; 10.674 + 10.675 + </sect1> 10.676 + <sect1> 10.677 + <title>Selecting the guards to use</title> 10.678 + 10.679 + <para id="x_174">The <command role="hg-ext-mq">qselect</command> command 10.680 + determines which guards are active at a given time. The effect 10.681 + of this is to determine which patches MQ will apply the next 10.682 + time you run <command role="hg-ext-mq">qpush</command>. It has 10.683 + no other effect; in particular, it doesn't do anything to 10.684 + patches that are already applied.</para> 10.685 + 10.686 + <para id="x_175">With no arguments, the <command 10.687 + role="hg-ext-mq">qselect</command> command lists the guards 10.688 + currently in effect, one per line of output. Each argument is 10.689 + treated as the name of a guard to apply.</para> 10.690 + 10.691 + &interaction.mq.guards.qselect.foo; 10.692 + 10.693 + <para id="x_176">In case you're interested, the currently selected guards are 10.694 + stored in the <filename role="special">guards</filename> file.</para> 10.695 + 10.696 + &interaction.mq.guards.qselect.cat; 10.697 + 10.698 + <para id="x_177">We can see the effect the selected guards have when we run 10.699 + <command role="hg-ext-mq">qpush</command>.</para> 10.700 + 10.701 + &interaction.mq.guards.qselect.qpush; 10.702 + 10.703 + <para id="x_178">A guard cannot start with a 10.704 + <quote><literal>+</literal></quote> or 10.705 + <quote><literal>-</literal></quote> character. The name of a 10.706 + guard must not contain white space, but most other characters 10.707 + are acceptable. If you try to use a guard with an invalid name, 10.708 + MQ will complain:</para> 10.709 + 10.710 + &interaction.mq.guards.qselect.error; 10.711 + 10.712 + <para id="x_179">Changing the selected guards changes the patches that are 10.713 + applied.</para> 10.714 + 10.715 + &interaction.mq.guards.qselect.quux; 10.716 + 10.717 + <para id="x_17a">You can see in the example below that negative guards take 10.718 + precedence over positive guards.</para> 10.719 + 10.720 + &interaction.mq.guards.qselect.foobar; 10.721 + 10.722 + </sect1> 10.723 + <sect1> 10.724 + <title>MQ's rules for applying patches</title> 10.725 + 10.726 + <para id="x_17b">The rules that MQ uses when deciding whether to apply a 10.727 + patch are as follows.</para> 10.728 + <itemizedlist> 10.729 + <listitem><para id="x_17c">A patch that has no guards is always 10.730 + applied.</para> 10.731 + </listitem> 10.732 + <listitem><para id="x_17d">If the patch has any negative guard that matches 10.733 + any currently selected guard, the patch is skipped.</para> 10.734 + </listitem> 10.735 + <listitem><para id="x_17e">If the patch has any positive guard that matches 10.736 + any currently selected guard, the patch is applied.</para> 10.737 + </listitem> 10.738 + <listitem><para id="x_17f">If the patch has positive or negative guards, 10.739 + but none matches any currently selected guard, the patch is 10.740 + skipped.</para> 10.741 + </listitem></itemizedlist> 10.742 + 10.743 + </sect1> 10.744 + <sect1> 10.745 + <title>Trimming the work environment</title> 10.746 + 10.747 + <para id="x_180">In working on the device driver I mentioned earlier, I don't 10.748 + apply the patches to a normal Linux kernel tree. Instead, I use 10.749 + a repository that contains only a snapshot of the source files 10.750 + and headers that are relevant to Infiniband development. This 10.751 + repository is 1% the size of a kernel repository, so it's easier 10.752 + to work with.</para> 10.753 + 10.754 + <para id="x_181">I then choose a <quote>base</quote> version on top of which 10.755 + the patches are applied. This is a snapshot of the Linux kernel 10.756 + tree as of a revision of my choosing. When I take the snapshot, 10.757 + I record the changeset ID from the kernel repository in the 10.758 + commit message. Since the snapshot preserves the 10.759 + <quote>shape</quote> and content of the relevant parts of the 10.760 + kernel tree, I can apply my patches on top of either my tiny 10.761 + repository or a normal kernel tree.</para> 10.762 + 10.763 + <para id="x_182">Normally, the base tree atop which the patches apply should 10.764 + be a snapshot of a very recent upstream tree. This best 10.765 + facilitates the development of patches that can easily be 10.766 + submitted upstream with few or no modifications.</para> 10.767 + 10.768 + </sect1> 10.769 + <sect1> 10.770 + <title>Dividing up the <filename role="special">series</filename> 10.771 + file</title> 10.772 + 10.773 + <para id="x_183">I categorise the patches in the <filename 10.774 + role="special">series</filename> file into a number of logical 10.775 + groups. Each section of like patches begins with a block of 10.776 + comments that describes the purpose of the patches that 10.777 + follow.</para> 10.778 + 10.779 + <para id="x_184">The sequence of patch groups that I maintain follows. The 10.780 + ordering of these groups is important; I'll describe why after I 10.781 + introduce the groups.</para> 10.782 + <itemizedlist> 10.783 + <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that 10.784 + the development team has submitted to the maintainer of the 10.785 + Infiniband subsystem, and which he has accepted, but which 10.786 + are not present in the snapshot that the tiny repository is 10.787 + based on. These are <quote>read only</quote> patches, 10.788 + present only to transform the tree into a similar state as 10.789 + it is in the upstream maintainer's repository.</para> 10.790 + </listitem> 10.791 + <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I 10.792 + have submitted, but that the upstream maintainer has 10.793 + requested modifications to before he will accept 10.794 + them.</para> 10.795 + </listitem> 10.796 + <listitem><para id="x_187">The <quote>pending</quote> group. Patches that 10.797 + I have not yet submitted to the upstream maintainer, but 10.798 + which we have finished working on. These will be <quote>read 10.799 + only</quote> for a while. If the upstream maintainer 10.800 + accepts them upon submission, I'll move them to the end of 10.801 + the <quote>accepted</quote> group. If he requests that I 10.802 + modify any, I'll move them to the beginning of the 10.803 + <quote>rework</quote> group.</para> 10.804 + </listitem> 10.805 + <listitem><para id="x_188">The <quote>in progress</quote> group. Patches 10.806 + that are actively being developed, and should not be 10.807 + submitted anywhere yet.</para> 10.808 + </listitem> 10.809 + <listitem><para id="x_189">The <quote>backport</quote> group. Patches that 10.810 + adapt the source tree to older versions of the kernel 10.811 + tree.</para> 10.812 + </listitem> 10.813 + <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches 10.814 + that for some reason should never be submitted upstream. 10.815 + For example, one such patch might change embedded driver 10.816 + identification strings to make it easier to distinguish, in 10.817 + the field, between an out-of-tree version of the driver and 10.818 + a version shipped by a distribution vendor.</para> 10.819 + </listitem></itemizedlist> 10.820 + 10.821 + <para id="x_18b">Now to return to the reasons for ordering groups of patches 10.822 + in this way. We would like the lowest patches in the stack to 10.823 + be as stable as possible, so that we will not need to rework 10.824 + higher patches due to changes in context. Putting patches that 10.825 + will never be changed first in the <filename 10.826 + role="special">series</filename> file serves this 10.827 + purpose.</para> 10.828 + 10.829 + <para id="x_18c">We would also like the patches that we know we'll need to 10.830 + modify to be applied on top of a source tree that resembles the 10.831 + upstream tree as closely as possible. This is why we keep 10.832 + accepted patches around for a while.</para> 10.833 + 10.834 + <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> 10.835 + patches float at the end of the <filename 10.836 + role="special">series</filename> file. The backport patches 10.837 + must be applied on top of all other patches, and the <quote>do 10.838 + not ship</quote> patches might as well stay out of harm's 10.839 + way.</para> 10.840 + 10.841 + </sect1> 10.842 + <sect1> 10.843 + <title>Maintaining the patch series</title> 10.844 + 10.845 + <para id="x_18e">In my work, I use a number of guards to control which 10.846 + patches are to be applied.</para> 10.847 + 10.848 + <itemizedlist> 10.849 + <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with 10.850 + <literal>accepted</literal>. I enable this guard most of 10.851 + the time. When I'm applying the patches on top of a tree 10.852 + where the patches are already present, I can turn this patch 10.853 + off, and the patches that follow it will apply 10.854 + cleanly.</para> 10.855 + </listitem> 10.856 + <listitem><para id="x_190">Patches that are <quote>finished</quote>, but 10.857 + not yet submitted, have no guards. If I'm applying the 10.858 + patch stack to a copy of the upstream tree, I don't need to 10.859 + enable any guards in order to get a reasonably safe source 10.860 + tree.</para> 10.861 + </listitem> 10.862 + <listitem><para id="x_191">Those patches that need reworking before being 10.863 + resubmitted are guarded with 10.864 + <literal>rework</literal>.</para> 10.865 + </listitem> 10.866 + <listitem><para id="x_192">For those patches that are still under 10.867 + development, I use <literal>devel</literal>.</para> 10.868 + </listitem> 10.869 + <listitem><para id="x_193">A backport patch may have several guards, one 10.870 + for each version of the kernel to which it applies. For 10.871 + example, a patch that backports a piece of code to 2.6.9 10.872 + will have a <literal>2.6.9</literal> guard.</para> 10.873 + </listitem></itemizedlist> 10.874 + <para id="x_194">This variety of guards gives me considerable flexibility in 10.875 + determining what kind of source tree I want to end up with. For 10.876 + most situations, the selection of appropriate guards is 10.877 + automated during the build process, but I can manually tune the 10.878 + guards to use for less common circumstances.</para> 10.879 + 10.880 + <sect2> 10.881 + <title>The art of writing backport patches</title> 10.882 + 10.883 + <para id="x_195">Using MQ, writing a backport patch is a simple process. 10.884 + All such a patch has to do is modify a piece of code that uses 10.885 + a kernel feature not present in the older version of the 10.886 + kernel, so that the driver continues to work correctly under 10.887 + that older version.</para> 10.888 + 10.889 + <para id="x_196">A useful goal when writing a good backport patch is to 10.890 + make your code look as if it was written for the older version 10.891 + of the kernel you're targeting. The less obtrusive the patch, 10.892 + the easier it will be to understand and maintain. If you're 10.893 + writing a collection of backport patches to avoid the 10.894 + <quote>rat's nest</quote> effect of lots of 10.895 + <literal>#ifdef</literal>s (hunks of source code that are only 10.896 + used conditionally) in your code, don't introduce 10.897 + version-dependent <literal>#ifdef</literal>s into the patches. 10.898 + Instead, write several patches, each of which makes 10.899 + unconditional changes, and control their application using 10.900 + guards.</para> 10.901 + 10.902 + <para id="x_197">There are two reasons to divide backport patches into a 10.903 + distinct group, away from the <quote>regular</quote> patches 10.904 + whose effects they modify. The first is that intermingling the 10.905 + two makes it more difficult to use a tool like the <literal 10.906 + role="hg-ext">patchbomb</literal> extension to automate the 10.907 + process of submitting the patches to an upstream maintainer. 10.908 + The second is that a backport patch could perturb the context 10.909 + in which a subsequent regular patch is applied, making it 10.910 + impossible to apply the regular patch cleanly 10.911 + <emphasis>without</emphasis> the earlier backport patch 10.912 + already being applied.</para> 10.913 + 10.914 + </sect2> 10.915 + </sect1> 10.916 + <sect1> 10.917 + <title>Useful tips for developing with MQ</title> 10.918 + 10.919 + <sect2> 10.920 + <title>Organising patches in directories</title> 10.921 + 10.922 + <para id="x_198">If you're working on a substantial project with MQ, it's 10.923 + not difficult to accumulate a large number of patches. For 10.924 + example, I have one patch repository that contains over 250 10.925 + patches.</para> 10.926 + 10.927 + <para id="x_199">If you can group these patches into separate logical 10.928 + categories, you can if you like store them in different 10.929 + directories; MQ has no problems with patch names that contain 10.930 + path separators.</para> 10.931 + 10.932 + </sect2> 10.933 + <sect2 id="mq-collab:tips:interdiff"> 10.934 + <title>Viewing the history of a patch</title> 10.935 + 10.936 + <para id="x_19a">If you're developing a set of patches over a long time, 10.937 + it's a good idea to maintain them in a repository, as 10.938 + discussed in <xref linkend="sec:mq:repo"/>. If you do 10.939 + so, you'll quickly 10.940 + discover that using the <command role="hg-cmd">hg 10.941 + diff</command> command to look at the history of changes to 10.942 + a patch is unworkable. This is in part because you're looking 10.943 + at the second derivative of the real code (a diff of a diff), 10.944 + but also because MQ adds noise to the process by modifying 10.945 + time stamps and directory names when it updates a 10.946 + patch.</para> 10.947 + 10.948 + <para id="x_19b">However, you can use the <literal 10.949 + role="hg-ext">extdiff</literal> extension, which is bundled 10.950 + with Mercurial, to turn a diff of two versions of a patch into 10.951 + something readable. To do this, you will need a third-party 10.952 + package called <literal role="package">patchutils</literal> 10.953 + <citation>web:patchutils</citation>. This provides a command 10.954 + named <command>interdiff</command>, which shows the 10.955 + differences between two diffs as a diff. Used on two versions 10.956 + of the same diff, it generates a diff that represents the diff 10.957 + from the first to the second version.</para> 10.958 + 10.959 + <para id="x_19c">You can enable the <literal 10.960 + role="hg-ext">extdiff</literal> extension in the usual way, 10.961 + by adding a line to the <literal 10.962 + role="rc-extensions">extensions</literal> section of your 10.963 + <filename role="special">~/.hgrc</filename>.</para> 10.964 + <programlisting>[extensions] 10.965 +extdiff =</programlisting> 10.966 + <para id="x_19d">The <command>interdiff</command> command expects to be 10.967 + passed the names of two files, but the <literal 10.968 + role="hg-ext">extdiff</literal> extension passes the program 10.969 + it runs a pair of directories, each of which can contain an 10.970 + arbitrary number of files. We thus need a small program that 10.971 + will run <command>interdiff</command> on each pair of files in 10.972 + these two directories. This program is available as <filename 10.973 + role="special">hg-interdiff</filename> in the <filename 10.974 + class="directory">examples</filename> directory of the 10.975 + source code repository that accompanies this book. <!-- 10.976 + &example.hg-interdiff; --></para> 10.977 + 10.978 + <para id="x_19e">With the <filename role="special">hg-interdiff</filename> 10.979 + program in your shell's search path, you can run it as 10.980 + follows, from inside an MQ patch directory:</para> 10.981 + <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> 10.982 + <para id="x_19f">Since you'll probably want to use this long-winded command 10.983 + a lot, you can get <literal role="hg-ext">hgext</literal> to 10.984 + make it available as a normal Mercurial command, again by 10.985 + editing your <filename 10.986 + role="special">~/.hgrc</filename>.</para> 10.987 + <programlisting>[extdiff] 10.988 +cmd.interdiff = hg-interdiff</programlisting> 10.989 + <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to 10.990 + make an <literal>interdiff</literal> command available, so you 10.991 + can now shorten the previous invocation of <command 10.992 + role="hg-ext-extdiff">extdiff</command> to something a 10.993 + little more wieldy.</para> 10.994 + <programlisting>hg interdiff -r A:B my-change.patch</programlisting> 10.995 + 10.996 + <note> 10.997 + <para id="x_1a1"> The <command>interdiff</command> command works well 10.998 + only if the underlying files against which versions of a 10.999 + patch are generated remain the same. If you create a patch, 10.1000 + modify the underlying files, and then regenerate the patch, 10.1001 + <command>interdiff</command> may not produce useful 10.1002 + output.</para> 10.1003 + </note> 10.1004 + 10.1005 + <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is 10.1006 + useful for more than merely improving the presentation of MQ 10.1007 + patches. To read more about it, go to <xref 10.1008 + linkend="sec:hgext:extdiff"/>.</para> 10.1009 + 10.1010 + </sect2> 10.1011 + </sect1> 10.1012 </chapter> 10.1013 10.1014 <!-- 10.1015 local variables: 10.1016 sgml-parent-document: ("00book.xml" "book" "chapter") 10.1017 end: 10.1018 ---> 10.1019 \ No newline at end of file 10.1020 +-->
11.1 --- a/fr/ch14-hgext.xml Wed Sep 09 15:25:09 2009 +0200 11.2 +++ b/fr/ch14-hgext.xml Wed Sep 09 16:07:36 2009 +0200 11.3 @@ -1,539 +1,554 @@ 11.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 11.5 11.6 -<chapter> 11.7 -<title>Adding functionality with extensions</title> 11.8 -<para>\label{chap:hgext}</para> 11.9 - 11.10 -<para>While the core of Mercurial is quite complete from a functionality 11.11 -standpoint, it's deliberately shorn of fancy features. This approach 11.12 -of preserving simplicity keeps the software easy to deal with for both 11.13 -maintainers and users.</para> 11.14 - 11.15 -<para>However, Mercurial doesn't box you in with an inflexible command set: 11.16 -you can add features to it as <emphasis>extensions</emphasis> (sometimes known as 11.17 -<emphasis>plugins</emphasis>). We've already discussed a few of these extensions in 11.18 -earlier chapters.</para> 11.19 -<itemizedlist> 11.20 -<listitem><para>Section <xref linkend="sec:tour-merge:fetch"/> covers the <literal role="hg-ext">fetch</literal> 11.21 - extension; this combines pulling new changes and merging them with 11.22 - local changes into a single command, <command role="hg-ext-fetch">fetch</command>.</para> 11.23 -</listitem> 11.24 -<listitem><para>In chapter <xref linkend="chap:hook"/>, we covered several extensions that 11.25 - are useful for hook-related functionality: <literal role="hg-ext">acl</literal> adds access 11.26 - control lists; <literal role="hg-ext">bugzilla</literal> adds integration with the Bugzilla 11.27 - bug tracking system; and <literal role="hg-ext">notify</literal> sends notification emails on 11.28 - new changes.</para> 11.29 -</listitem> 11.30 -<listitem><para>The Mercurial Queues patch management extension is so invaluable 11.31 - that it merits two chapters and an appendix all to itself. 11.32 - Chapter <xref linkend="chap:mq"/> covers the basics; 11.33 - chapter <xref linkend="chap:mq-collab"/> discusses advanced topics; and 11.34 - appendix <xref linkend="chap:mqref"/> goes into detail on each command.</para> 11.35 -</listitem></itemizedlist> 11.36 - 11.37 -<para>In this chapter, we'll cover some of the other extensions that are 11.38 -available for Mercurial, and briefly touch on some of the machinery 11.39 -you'll need to know about if you want to write an extension of your 11.40 -own.</para> 11.41 -<itemizedlist> 11.42 -<listitem><para>In section <xref linkend="sec:hgext:inotify"/>, we'll discuss the 11.43 - possibility of <emphasis>huge</emphasis> performance improvements using the 11.44 - <literal role="hg-ext">inotify</literal> extension.</para> 11.45 -</listitem></itemizedlist> 11.46 - 11.47 -<sect1> 11.48 -<title>Improve performance with the <literal role="hg-ext">inotify</literal> extension</title> 11.49 -<para>\label{sec:hgext:inotify} 11.50 -</para> 11.51 - 11.52 -<para>Are you interested in having some of the most common Mercurial 11.53 -operations run as much as a hundred times faster? Read on! 11.54 -</para> 11.55 - 11.56 -<para>Mercurial has great performance under normal circumstances. For 11.57 -example, when you run the <command role="hg-cmd">hg status</command> command, Mercurial has to 11.58 -scan almost every directory and file in your repository so that it can 11.59 -display file status. Many other Mercurial commands need to do the 11.60 -same work behind the scenes; for example, the <command role="hg-cmd">hg diff</command> command 11.61 -uses the status machinery to avoid doing an expensive comparison 11.62 -operation on files that obviously haven't changed. 11.63 -</para> 11.64 - 11.65 -<para>Because obtaining file status is crucial to good performance, the 11.66 -authors of Mercurial have optimised this code to within an inch of its 11.67 -life. However, there's no avoiding the fact that when you run 11.68 -<command role="hg-cmd">hg status</command>, Mercurial is going to have to perform at least one 11.69 -expensive system call for each managed file to determine whether it's 11.70 -changed since the last time Mercurial checked. For a sufficiently 11.71 -large repository, this can take a long time. 11.72 -</para> 11.73 - 11.74 -<para>To put a number on the magnitude of this effect, I created a 11.75 -repository containing 150,000 managed files. I timed <command role="hg-cmd">hg status</command> 11.76 -as taking ten seconds to run, even when <emphasis>none</emphasis> of those files had 11.77 -been modified. 11.78 -</para> 11.79 - 11.80 -<para>Many modern operating systems contain a file notification facility. 11.81 -If a program signs up to an appropriate service, the operating system 11.82 -will notify it every time a file of interest is created, modified, or 11.83 -deleted. On Linux systems, the kernel component that does this is 11.84 -called <literal>inotify</literal>. 11.85 -</para> 11.86 - 11.87 -<para>Mercurial's <literal role="hg-ext">inotify</literal> extension talks to the kernel's 11.88 -<literal>inotify</literal> component to optimise <command role="hg-cmd">hg status</command> commands. The 11.89 -extension has two components. A daemon sits in the background and 11.90 -receives notifications from the <literal>inotify</literal> subsystem. It also 11.91 -listens for connections from a regular Mercurial command. The 11.92 -extension modifies Mercurial's behaviour so that instead of scanning 11.93 -the filesystem, it queries the daemon. Since the daemon has perfect 11.94 -information about the state of the repository, it can respond with a 11.95 -result instantaneously, avoiding the need to scan every directory and 11.96 -file in the repository. 11.97 -</para> 11.98 - 11.99 -<para>Recall the ten seconds that I measured plain Mercurial as taking to 11.100 -run <command role="hg-cmd">hg status</command> on a 150,000 file repository. With the 11.101 -<literal role="hg-ext">inotify</literal> extension enabled, the time dropped to 0.1 seconds, a 11.102 -factor of <emphasis>one hundred</emphasis> faster. 11.103 -</para> 11.104 - 11.105 -<para>Before we continue, please pay attention to some caveats. 11.106 -</para> 11.107 -<itemizedlist> 11.108 -<listitem><para>The <literal role="hg-ext">inotify</literal> extension is Linux-specific. Because it 11.109 - interfaces directly to the Linux kernel's <literal>inotify</literal> 11.110 - subsystem, it does not work on other operating systems. 11.111 -</para> 11.112 -</listitem> 11.113 -<listitem><para>It should work on any Linux distribution that was released after 11.114 - early 2005. Older distributions are likely to have a kernel that 11.115 - lacks <literal>inotify</literal>, or a version of <literal>glibc</literal> that does not 11.116 - have the necessary interfacing support. 11.117 -</para> 11.118 -</listitem> 11.119 -<listitem><para>Not all filesystems are suitable for use with the 11.120 - <literal role="hg-ext">inotify</literal> extension. Network filesystems such as NFS are a 11.121 - non-starter, for example, particularly if you're running Mercurial 11.122 - on several systems, all mounting the same network filesystem. The 11.123 - kernel's <literal>inotify</literal> system has no way of knowing about changes 11.124 - made on another system. Most local filesystems (e.g. ext3, XFS, 11.125 - ReiserFS) should work fine. 11.126 -</para> 11.127 -</listitem></itemizedlist> 11.128 - 11.129 -<para>The <literal role="hg-ext">inotify</literal> extension is not yet shipped with Mercurial as of 11.130 -May 2007, so it's a little more involved to set up than other 11.131 -extensions. But the performance improvement is worth it! 11.132 -</para> 11.133 - 11.134 -<para>The extension currently comes in two parts: a set of patches to the 11.135 -Mercurial source code, and a library of Python bindings to the 11.136 -<literal>inotify</literal> subsystem. 11.137 -</para> 11.138 -<note> 11.139 -<para> There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding libraries. One 11.140 - of them is called <literal>pyinotify</literal>, and is packaged by some Linux 11.141 - distributions as <literal>python-inotify</literal>. This is <emphasis>not</emphasis> the 11.142 - one you'll need, as it is too buggy and inefficient to be practical. 11.143 -</para> 11.144 -</note> 11.145 -<para>To get going, it's best to already have a functioning copy of 11.146 -Mercurial installed. 11.147 -</para> 11.148 -<note> 11.149 -<para> If you follow the instructions below, you'll be <emphasis>replacing</emphasis> and 11.150 - overwriting any existing installation of Mercurial that you might 11.151 - already have, using the latest <quote>bleeding edge</quote> Mercurial code. 11.152 - Don't say you weren't warned! 11.153 -</para> 11.154 -</note> 11.155 -<orderedlist> 11.156 -<listitem><para>Clone the Python <literal>inotify</literal> binding repository. Build and 11.157 - install it. 11.158 -</para> 11.159 -</listitem><programlisting> 11.160 -<listitem><para> hg clone http://hg.kublai.com/python/inotify 11.161 - cd inotify 11.162 - python setup.py build --force 11.163 - sudo python setup.py install --skip-build 11.164 -</para> 11.165 -</listitem></programlisting> 11.166 -</para> 11.167 -</listitem> 11.168 -<listitem><para>Clone the <filename class="directory">crew</filename> Mercurial repository. Clone the 11.169 - <literal role="hg-ext">inotify</literal> patch repository so that Mercurial Queues will be 11.170 - able to apply patches to your cope of the <filename class="directory">crew</filename> repository. 11.171 -</para> 11.172 -</listitem><programlisting> 11.173 -<listitem><para> hg clone http://hg.intevation.org/mercurial/crew 11.174 - hg clone crew inotify 11.175 - hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches 11.176 -</para> 11.177 -</listitem></programlisting> 11.178 -</para> 11.179 -</listitem> 11.180 -<listitem><para>Make sure that you have the Mercurial Queues extension, 11.181 - <literal role="hg-ext">mq</literal>, enabled. If you've never used MQ, read 11.182 - section <xref linkend="sec:mq:start"/> to get started quickly. 11.183 -</para> 11.184 -</listitem> 11.185 -<listitem><para>Go into the <filename class="directory">inotify</filename> repo, and apply all of the 11.186 - <literal role="hg-ext">inotify</literal> patches using the <option role="hg-ext-mq-cmd-qpush-opt">-a</option> option to 11.187 - the <command role="hg-ext-mq">qpush</command> command. 11.188 -</para> 11.189 -</listitem><programlisting> 11.190 -<listitem><para> cd inotify 11.191 - hg qpush -a 11.192 -</para> 11.193 -</listitem></programlisting> 11.194 -<listitem><para> If you get an error message from <command role="hg-ext-mq">qpush</command>, you should not 11.195 - continue. Instead, ask for help. 11.196 -</para> 11.197 -</listitem> 11.198 -<listitem><para>Build and install the patched version of Mercurial. 11.199 -</para> 11.200 -</listitem><programlisting> 11.201 -<listitem><para> python setup.py build --force 11.202 - sudo python setup.py install --skip-build 11.203 -</para> 11.204 -</listitem></programlisting> 11.205 -</orderedlist> 11.206 -<para>Once you've build a suitably patched version of Mercurial, all you 11.207 -need to do to enable the <literal role="hg-ext">inotify</literal> extension is add an entry to 11.208 -your <filename role="special"> /.hgrc</filename>. 11.209 -</para> 11.210 -<programlisting> 11.211 -<para> [extensions] 11.212 - inotify = 11.213 -</para> 11.214 -</programlisting> 11.215 -<para>When the <literal role="hg-ext">inotify</literal> extension is enabled, Mercurial will 11.216 -automatically and transparently start the status daemon the first time 11.217 -you run a command that needs status in a repository. It runs one 11.218 -status daemon per repository. 11.219 -</para> 11.220 - 11.221 -<para>The status daemon is started silently, and runs in the background. If 11.222 -you look at a list of running processes after you've enabled the 11.223 -<literal role="hg-ext">inotify</literal> extension and run a few commands in different 11.224 -repositories, you'll thus see a few <literal>hg</literal> processes sitting 11.225 -around, waiting for updates from the kernel and queries from 11.226 -Mercurial. 11.227 -</para> 11.228 - 11.229 -<para>The first time you run a Mercurial command in a repository when you 11.230 -have the <literal role="hg-ext">inotify</literal> extension enabled, it will run with about the 11.231 -same performance as a normal Mercurial command. This is because the 11.232 -status daemon needs to perform a normal status scan so that it has a 11.233 -baseline against which to apply later updates from the kernel. 11.234 -However, <emphasis>every</emphasis> subsequent command that does any kind of status 11.235 -check should be noticeably faster on repositories of even fairly 11.236 -modest size. Better yet, the bigger your repository is, the greater a 11.237 -performance advantage you'll see. The <literal role="hg-ext">inotify</literal> daemon makes 11.238 -status operations almost instantaneous on repositories of all sizes! 11.239 -</para> 11.240 - 11.241 -<para>If you like, you can manually start a status daemon using the 11.242 -<command role="hg-ext-inotify">inserve</command> command. This gives you slightly finer 11.243 -control over how the daemon ought to run. This command will of course 11.244 -only be available when the <literal role="hg-ext">inotify</literal> extension is enabled. 11.245 -</para> 11.246 - 11.247 -<para>When you're using the <literal role="hg-ext">inotify</literal> extension, you should notice 11.248 -<emphasis>no difference at all</emphasis> in Mercurial's behaviour, with the sole 11.249 -exception of status-related commands running a whole lot faster than 11.250 -they used to. You should specifically expect that commands will not 11.251 -print different output; neither should they give different results. 11.252 -If either of these situations occurs, please report a bug. 11.253 -</para> 11.254 - 11.255 -</sect1> 11.256 -<sect1> 11.257 -<title>Flexible diff support with the <literal role="hg-ext">extdiff</literal> extension</title> 11.258 -<para>\label{sec:hgext:extdiff} 11.259 -</para> 11.260 - 11.261 -<para>Mercurial's built-in <command role="hg-cmd">hg diff</command> command outputs plaintext unified 11.262 -diffs. 11.263 -<!-- &interaction.extdiff.diff; --> 11.264 -If you would like to use an external tool to display modifications, 11.265 -you'll want to use the <literal role="hg-ext">extdiff</literal> extension. This will let you 11.266 -use, for example, a graphical diff tool. 11.267 -</para> 11.268 - 11.269 -<para>The <literal role="hg-ext">extdiff</literal> extension is bundled with Mercurial, so it's easy 11.270 -to set up. In the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>, 11.271 -simply add a one-line entry to enable the extension. 11.272 -</para> 11.273 -<programlisting> 11.274 -<para> [extensions] 11.275 - extdiff = 11.276 -</para> 11.277 -</programlisting> 11.278 -<para>This introduces a command named <command role="hg-ext-extdiff">extdiff</command>, which by 11.279 -default uses your system's <command>diff</command> command to generate a 11.280 -unified diff in the same form as the built-in <command role="hg-cmd">hg diff</command> command. 11.281 -<!-- &interaction.extdiff.extdiff; --> 11.282 -The result won't be exactly the same as with the built-in <command role="hg-cmd">hg diff</command> 11.283 -variations, because the output of <command>diff</command> varies from one 11.284 -system to another, even when passed the same options. 11.285 -</para> 11.286 - 11.287 -<para>As the <quote><literal>making snapshot</literal></quote> lines of output above imply, the 11.288 -<command role="hg-ext-extdiff">extdiff</command> command works by creating two snapshots of 11.289 -your source tree. The first snapshot is of the source revision; the 11.290 -second, of the target revision or working directory. The 11.291 -<command role="hg-ext-extdiff">extdiff</command> command generates these snapshots in a 11.292 -temporary directory, passes the name of each directory to an external 11.293 -diff viewer, then deletes the temporary directory. For efficiency, it 11.294 -only snapshots the directories and files that have changed between the 11.295 -two revisions. 11.296 -</para> 11.297 - 11.298 -<para>Snapshot directory names have the same base name as your repository. 11.299 -If your repository path is <filename class="directory">/quux/bar/foo</filename>, then <filename class="directory">foo</filename> 11.300 -will be the name of each snapshot directory. Each snapshot directory 11.301 -name has its changeset ID appended, if appropriate. If a snapshot is 11.302 -of revision <literal>a631aca1083f</literal>, the directory will be named 11.303 -<filename class="directory">foo.a631aca1083f</filename>. A snapshot of the working directory won't 11.304 -have a changeset ID appended, so it would just be <filename class="directory">foo</filename> in 11.305 -this example. To see what this looks like in practice, look again at 11.306 -the <command role="hg-ext-extdiff">extdiff</command> example above. Notice that the diff has 11.307 -the snapshot directory names embedded in its header. 11.308 -</para> 11.309 - 11.310 -<para>The <command role="hg-ext-extdiff">extdiff</command> command accepts two important options. 11.311 -The <option role="hg-ext-extdiff-cmd-extdiff-opt">-p</option> option lets you choose a program to 11.312 -view differences with, instead of <command>diff</command>. With the 11.313 -<option role="hg-ext-extdiff-cmd-extdiff-opt">-o</option> option, you can change the options that 11.314 -<command role="hg-ext-extdiff">extdiff</command> passes to the program (by default, these 11.315 -options are <quote><literal>-Npru</literal></quote>, which only make sense if you're 11.316 -running <command>diff</command>). In other respects, the 11.317 -<command role="hg-ext-extdiff">extdiff</command> command acts similarly to the built-in 11.318 -<command role="hg-cmd">hg diff</command> command: you use the same option names, syntax, and 11.319 -arguments to specify the revisions you want, the files you want, and 11.320 -so on. 11.321 -</para> 11.322 - 11.323 -<para>As an example, here's how to run the normal system <command>diff</command> 11.324 -command, getting it to generate context diffs (using the 11.325 -<option role="cmd-opt-diff">-c</option> option) instead of unified diffs, and five lines of 11.326 -context instead of the default three (passing <literal>5</literal> as the 11.327 -argument to the <option role="cmd-opt-diff">-C</option> option). 11.328 -<!-- &interaction.extdiff.extdiff-ctx; --> 11.329 -</para> 11.330 - 11.331 -<para>Launching a visual diff tool is just as easy. Here's how to launch 11.332 -the <command>kdiff3</command> viewer. 11.333 -</para> 11.334 -<programlisting> 11.335 -<para> hg extdiff -p kdiff3 -o </quote> 11.336 -</para> 11.337 -</programlisting> 11.338 - 11.339 -<para>If your diff viewing command can't deal with directories, you can 11.340 -easily work around this with a little scripting. For an example of 11.341 -such scripting in action with the <literal role="hg-ext">mq</literal> extension and the 11.342 -<command>interdiff</command> command, see 11.343 -section <xref linkend="mq-collab:tips:interdiff"/>. 11.344 -</para> 11.345 - 11.346 -<sect2> 11.347 -<title>Defining command aliases</title> 11.348 - 11.349 -<para>It can be cumbersome to remember the options to both the 11.350 -<command role="hg-ext-extdiff">extdiff</command> command and the diff viewer you want to use, 11.351 -so the <literal role="hg-ext">extdiff</literal> extension lets you define <emphasis>new</emphasis> commands 11.352 -that will invoke your diff viewer with exactly the right options. 11.353 -</para> 11.354 - 11.355 -<para>All you need to do is edit your <filename role="special"> /.hgrc</filename>, and add a section named 11.356 -<literal role="rc-extdiff">extdiff</literal>. Inside this section, you can define multiple 11.357 -commands. Here's how to add a <literal>kdiff3</literal> command. Once you've 11.358 -defined this, you can type <quote><literal>hg kdiff3</literal></quote> and the 11.359 -<literal role="hg-ext">extdiff</literal> extension will run <command>kdiff3</command> for you. 11.360 -</para> 11.361 -<programlisting> 11.362 -<para> [extdiff] 11.363 - cmd.kdiff3 = 11.364 -</para> 11.365 -</programlisting> 11.366 -<para>If you leave the right hand side of the definition empty, as above, 11.367 -the <literal role="hg-ext">extdiff</literal> extension uses the name of the command you defined 11.368 -as the name of the external program to run. But these names don't 11.369 -have to be the same. Here, we define a command named <quote>\texttt{hg 11.370 - wibble}</quote>, which runs <command>kdiff3</command>. 11.371 -</para> 11.372 -<programlisting> 11.373 -<para> [extdiff] 11.374 - cmd.wibble = kdiff3 11.375 -</para> 11.376 -</programlisting> 11.377 - 11.378 -<para>You can also specify the default options that you want to invoke your 11.379 -diff viewing program with. The prefix to use is <quote><literal>opts.</literal></quote>, 11.380 -followed by the name of the command to which the options apply. This 11.381 -example defines a <quote><literal>hg vimdiff</literal></quote> command that runs the 11.382 -<command>vim</command> editor's <literal>DirDiff</literal> extension. 11.383 -</para> 11.384 -<programlisting> 11.385 -<para> [extdiff] 11.386 - cmd.vimdiff = vim 11.387 - opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)' 11.388 -</para> 11.389 -</programlisting> 11.390 - 11.391 -</sect2> 11.392 -</sect1> 11.393 -<sect1> 11.394 -<title>Cherrypicking changes with the <literal role="hg-ext">transplant</literal> extension</title> 11.395 -<para>\label{sec:hgext:transplant} 11.396 -</para> 11.397 - 11.398 -<para>Need to have a long chat with Brendan about this. 11.399 -</para> 11.400 - 11.401 -</sect1> 11.402 -<sect1> 11.403 -<title>Send changes via email with the <literal role="hg-ext">patchbomb</literal> extension</title> 11.404 -<para>\label{sec:hgext:patchbomb} 11.405 -</para> 11.406 - 11.407 -<para>Many projects have a culture of <quote>change review</quote>, in which people 11.408 -send their modifications to a mailing list for others to read and 11.409 -comment on before they commit the final version to a shared 11.410 -repository. Some projects have people who act as gatekeepers; they 11.411 -apply changes from other people to a repository to which those others 11.412 -don't have access. 11.413 -</para> 11.414 - 11.415 -<para>Mercurial makes it easy to send changes over email for review or 11.416 -application, via its <literal role="hg-ext">patchbomb</literal> extension. The extension is so 11.417 -namd because changes are formatted as patches, and it's usual to send 11.418 -one changeset per email message. Sending a long series of changes by 11.419 -email is thus much like <quote>bombing</quote> the recipient's inbox, hence 11.420 -<quote>patchbomb</quote>. 11.421 -</para> 11.422 - 11.423 -<para>As usual, the basic configuration of the <literal role="hg-ext">patchbomb</literal> extension 11.424 -takes just one or two lines in your <filename role="special"> /.hgrc</filename>. 11.425 -</para> 11.426 -<programlisting> 11.427 -<para> [extensions] 11.428 - patchbomb = 11.429 -</para> 11.430 -</programlisting> 11.431 -<para>Once you've enabled the extension, you will have a new command 11.432 -available, named <command role="hg-ext-patchbomb">email</command>. 11.433 -</para> 11.434 - 11.435 -<para>The safest and best way to invoke the <command role="hg-ext-patchbomb">email</command> 11.436 -command is to <emphasis>always</emphasis> run it first with the 11.437 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option. This will show you what the 11.438 -command <emphasis>would</emphasis> send, without actually sending anything. Once 11.439 -you've had a quick glance over the changes and verified that you are 11.440 -sending the right ones, you can rerun the same command, with the 11.441 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option removed. 11.442 -</para> 11.443 - 11.444 -<para>The <command role="hg-ext-patchbomb">email</command> command accepts the same kind of 11.445 -revision syntax as every other Mercurial command. For example, this 11.446 -command will send every revision between 7 and <literal>tip</literal>, 11.447 -inclusive. 11.448 -</para> 11.449 -<programlisting> 11.450 -<para> hg email -n 7:tip 11.451 -</para> 11.452 -</programlisting> 11.453 -<para>You can also specify a <emphasis>repository</emphasis> to compare with. If you 11.454 -provide a repository but no revisions, the <command role="hg-ext-patchbomb">email</command> 11.455 -command will send all revisions in the local repository that are not 11.456 -present in the remote repository. If you additionally specify 11.457 -revisions or a branch name (the latter using the 11.458 -<option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option), this will constrain the 11.459 -revisions sent. 11.460 -</para> 11.461 - 11.462 -<para>It's perfectly safe to run the <command role="hg-ext-patchbomb">email</command> command 11.463 -without the names of the people you want to send to: if you do this, 11.464 -it will just prompt you for those values interactively. (If you're 11.465 -using a Linux or Unix-like system, you should have enhanced 11.466 -<literal>readline</literal>-style editing capabilities when entering those 11.467 -headers, too, which is useful.) 11.468 -</para> 11.469 - 11.470 -<para>When you are sending just one revision, the <command role="hg-ext-patchbomb">email</command> 11.471 -command will by default use the first line of the changeset 11.472 -description as the subject of the single email message it sends. 11.473 -</para> 11.474 - 11.475 -<para>If you send multiple revisions, the <command role="hg-ext-patchbomb">email</command> command 11.476 -will usually send one message per changeset. It will preface the 11.477 -series with an introductory message, in which you should describe the 11.478 -purpose of the series of changes you're sending. 11.479 -</para> 11.480 - 11.481 -<sect2> 11.482 -<title>Changing the behaviour of patchbombs</title> 11.483 - 11.484 -<para>Not every project has exactly the same conventions for sending changes 11.485 -in email; the <literal role="hg-ext">patchbomb</literal> extension tries to accommodate a 11.486 -number of variations through command line options. 11.487 -</para> 11.488 -<itemizedlist> 11.489 -<listitem><para>You can write a subject for the introductory message on the 11.490 - command line using the <option role="hg-ext-patchbomb-cmd-email-opt">-s</option> option. This 11.491 - takes one argument, the text of the subject to use. 11.492 -</para> 11.493 -</listitem> 11.494 -<listitem><para>To change the email address from which the messages originate, 11.495 - use the <option role="hg-ext-patchbomb-cmd-email-opt">-f</option> option. This takes one 11.496 - argument, the email address to use. 11.497 -</para> 11.498 -</listitem> 11.499 -<listitem><para>The default behaviour is to send unified diffs (see 11.500 - section <xref linkend="sec:mq:patch"/> for a description of the format), one per 11.501 - message. You can send a binary bundle instead with the 11.502 - <option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option. 11.503 -</para> 11.504 -</listitem> 11.505 -<listitem><para>Unified diffs are normally prefaced with a metadata header. You 11.506 - can omit this, and send unadorned diffs, with the 11.507 - <option role="hg-ext-patchbomb-cmd-email-opt">--plain</option> option. 11.508 -</para> 11.509 -</listitem> 11.510 -<listitem><para>Diffs are normally sent <quote>inline</quote>, in the same body part as the 11.511 - description of a patch. This makes it easiest for the largest 11.512 - number of readers to quote and respond to parts of a diff, as some 11.513 - mail clients will only quote the first MIME body part in a message. 11.514 - If you'd prefer to send the description and the diff in separate 11.515 - body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">-a</option> option. 11.516 -</para> 11.517 -</listitem> 11.518 -<listitem><para>Instead of sending mail messages, you can write them to an 11.519 - <literal>mbox</literal>-format mail folder using the 11.520 - <option role="hg-ext-patchbomb-cmd-email-opt">-m</option> option. That option takes one 11.521 - argument, the name of the file to write to. 11.522 -</para> 11.523 -</listitem> 11.524 -<listitem><para>If you would like to add a <command>diffstat</command>-format summary to 11.525 - each patch, and one to the introductory message, use the 11.526 - <option role="hg-ext-patchbomb-cmd-email-opt">-d</option> option. The <command>diffstat</command> 11.527 - command displays a table containing the name of each file patched, 11.528 - the number of lines affected, and a histogram showing how much each 11.529 - file is modified. This gives readers a qualitative glance at how 11.530 - complex a patch is. 11.531 -</para> 11.532 -</listitem></itemizedlist> 11.533 - 11.534 -</sect2> 11.535 -</sect1> 11.536 +<chapter id="chap:hgext"> 11.537 + <?dbhtml filename="adding-functionality-with-extensions.html"?> 11.538 + <title>Adding functionality with extensions</title> 11.539 + 11.540 + <para id="x_4fe">While the core of Mercurial is quite complete from a 11.541 + functionality standpoint, it's deliberately shorn of fancy 11.542 + features. This approach of preserving simplicity keeps the 11.543 + software easy to deal with for both maintainers and users.</para> 11.544 + 11.545 + <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 11.546 + command set: you can add features to it as 11.547 + <emphasis>extensions</emphasis> (sometimes known as 11.548 + <emphasis>plugins</emphasis>). We've already discussed a few of 11.549 + these extensions in earlier chapters.</para> 11.550 + <itemizedlist> 11.551 + <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/> 11.552 + covers the <literal role="hg-ext">fetch</literal> extension; 11.553 + this combines pulling new changes and merging them with local 11.554 + changes into a single command, <command 11.555 + role="hg-ext-fetch">fetch</command>.</para> 11.556 + </listitem> 11.557 + <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered 11.558 + several extensions that are useful for hook-related 11.559 + functionality: <literal role="hg-ext">acl</literal> adds 11.560 + access control lists; <literal 11.561 + role="hg-ext">bugzilla</literal> adds integration with the 11.562 + Bugzilla bug tracking system; and <literal 11.563 + role="hg-ext">notify</literal> sends notification emails on 11.564 + new changes.</para> 11.565 + </listitem> 11.566 + <listitem><para id="x_502">The Mercurial Queues patch management extension is 11.567 + so invaluable that it merits two chapters and an appendix all 11.568 + to itself. <xref linkend="chap:mq"/> covers the 11.569 + basics; <xref 11.570 + linkend="chap:mq-collab"/> discusses advanced topics; 11.571 + and <xref linkend="chap:mqref"/> goes into detail on 11.572 + each 11.573 + command.</para> 11.574 + </listitem></itemizedlist> 11.575 + 11.576 + <para id="x_503">In this chapter, we'll cover some of the other extensions that 11.577 + are available for Mercurial, and briefly touch on some of the 11.578 + machinery you'll need to know about if you want to write an 11.579 + extension of your own.</para> 11.580 + <itemizedlist> 11.581 + <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>, 11.582 + we'll discuss the possibility of <emphasis>huge</emphasis> 11.583 + performance improvements using the <literal 11.584 + role="hg-ext">inotify</literal> extension.</para> 11.585 + </listitem></itemizedlist> 11.586 + 11.587 + <sect1 id="sec:hgext:inotify"> 11.588 + <title>Improve performance with the <literal 11.589 + role="hg-ext">inotify</literal> extension</title> 11.590 + 11.591 + <para id="x_505">Are you interested in having some of the most common 11.592 + Mercurial operations run as much as a hundred times faster? 11.593 + Read on!</para> 11.594 + 11.595 + <para id="x_506">Mercurial has great performance under normal circumstances. 11.596 + For example, when you run the <command role="hg-cmd">hg 11.597 + status</command> command, Mercurial has to scan almost every 11.598 + directory and file in your repository so that it can display 11.599 + file status. Many other Mercurial commands need to do the same 11.600 + work behind the scenes; for example, the <command 11.601 + role="hg-cmd">hg diff</command> command uses the status 11.602 + machinery to avoid doing an expensive comparison operation on 11.603 + files that obviously haven't changed.</para> 11.604 + 11.605 + <para id="x_507">Because obtaining file status is crucial to good 11.606 + performance, the authors of Mercurial have optimised this code 11.607 + to within an inch of its life. However, there's no avoiding the 11.608 + fact that when you run <command role="hg-cmd">hg 11.609 + status</command>, Mercurial is going to have to perform at 11.610 + least one expensive system call for each managed file to 11.611 + determine whether it's changed since the last time Mercurial 11.612 + checked. For a sufficiently large repository, this can take a 11.613 + long time.</para> 11.614 + 11.615 + <para id="x_508">To put a number on the magnitude of this effect, I created a 11.616 + repository containing 150,000 managed files. I timed <command 11.617 + role="hg-cmd">hg status</command> as taking ten seconds to 11.618 + run, even when <emphasis>none</emphasis> of those files had been 11.619 + modified.</para> 11.620 + 11.621 + <para id="x_509">Many modern operating systems contain a file notification 11.622 + facility. If a program signs up to an appropriate service, the 11.623 + operating system will notify it every time a file of interest is 11.624 + created, modified, or deleted. On Linux systems, the kernel 11.625 + component that does this is called 11.626 + <literal>inotify</literal>.</para> 11.627 + 11.628 + <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 11.629 + extension talks to the kernel's <literal>inotify</literal> 11.630 + component to optimise <command role="hg-cmd">hg status</command> 11.631 + commands. The extension has two components. A daemon sits in 11.632 + the background and receives notifications from the 11.633 + <literal>inotify</literal> subsystem. It also listens for 11.634 + connections from a regular Mercurial command. The extension 11.635 + modifies Mercurial's behavior so that instead of scanning the 11.636 + filesystem, it queries the daemon. Since the daemon has perfect 11.637 + information about the state of the repository, it can respond 11.638 + with a result instantaneously, avoiding the need to scan every 11.639 + directory and file in the repository.</para> 11.640 + 11.641 + <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 11.642 + taking to run <command role="hg-cmd">hg status</command> on a 11.643 + 150,000 file repository. With the <literal 11.644 + role="hg-ext">inotify</literal> extension enabled, the time 11.645 + dropped to 0.1 seconds, a factor of <emphasis>one 11.646 + hundred</emphasis> faster.</para> 11.647 + 11.648 + <para id="x_50c">Before we continue, please pay attention to some 11.649 + caveats.</para> 11.650 + <itemizedlist> 11.651 + <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 11.652 + extension is Linux-specific. Because it interfaces directly 11.653 + to the Linux kernel's <literal>inotify</literal> subsystem, 11.654 + it does not work on other operating systems.</para> 11.655 + </listitem> 11.656 + <listitem><para id="x_50e">It should work on any Linux distribution that 11.657 + was released after early 2005. Older distributions are 11.658 + likely to have a kernel that lacks 11.659 + <literal>inotify</literal>, or a version of 11.660 + <literal>glibc</literal> that does not have the necessary 11.661 + interfacing support.</para> 11.662 + </listitem> 11.663 + <listitem><para id="x_50f">Not all filesystems are suitable for use with 11.664 + the <literal role="hg-ext">inotify</literal> extension. 11.665 + Network filesystems such as NFS are a non-starter, for 11.666 + example, particularly if you're running Mercurial on several 11.667 + systems, all mounting the same network filesystem. The 11.668 + kernel's <literal>inotify</literal> system has no way of 11.669 + knowing about changes made on another system. Most local 11.670 + filesystems (e.g. ext3, XFS, ReiserFS) should work 11.671 + fine.</para> 11.672 + </listitem></itemizedlist> 11.673 + 11.674 + <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 11.675 + not yet shipped with Mercurial as of May 2007, so it's a little 11.676 + more involved to set up than other extensions. But the 11.677 + performance improvement is worth it!</para> 11.678 + 11.679 + <para id="x_511">The extension currently comes in two parts: a set of patches 11.680 + to the Mercurial source code, and a library of Python bindings 11.681 + to the <literal>inotify</literal> subsystem.</para> 11.682 + <note> 11.683 + <para id="x_512"> There are <emphasis>two</emphasis> Python 11.684 + <literal>inotify</literal> binding libraries. One of them is 11.685 + called <literal>pyinotify</literal>, and is packaged by some 11.686 + Linux distributions as <literal>python-inotify</literal>. 11.687 + This is <emphasis>not</emphasis> the one you'll need, as it is 11.688 + too buggy and inefficient to be practical.</para> 11.689 + </note> 11.690 + <para id="x_513">To get going, it's best to already have a functioning copy 11.691 + of Mercurial installed.</para> 11.692 + <note> 11.693 + <para id="x_514"> If you follow the instructions below, you'll be 11.694 + <emphasis>replacing</emphasis> and overwriting any existing 11.695 + installation of Mercurial that you might already have, using 11.696 + the latest <quote>bleeding edge</quote> Mercurial code. Don't 11.697 + say you weren't warned!</para> 11.698 + </note> 11.699 + <orderedlist> 11.700 + <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 11.701 + binding repository. Build and install it.</para> 11.702 + <programlisting>hg clone http://hg.kublai.com/python/inotify 11.703 +cd inotify 11.704 +python setup.py build --force 11.705 +sudo python setup.py install --skip-build</programlisting> 11.706 + </listitem> 11.707 + <listitem><para id="x_516">Clone the <filename 11.708 + class="directory">crew</filename> Mercurial repository. 11.709 + Clone the <literal role="hg-ext">inotify</literal> patch 11.710 + repository so that Mercurial Queues will be able to apply 11.711 + patches to your cope of the <filename 11.712 + class="directory">crew</filename> repository.</para> 11.713 + <programlisting>hg clone http://hg.intevation.org/mercurial/crew 11.714 +hg clone crew inotify 11.715 +hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 11.716 + </listitem> 11.717 + <listitem><para id="x_517">Make sure that you have the Mercurial Queues 11.718 + extension, <literal role="hg-ext">mq</literal>, enabled. If 11.719 + you've never used MQ, read <xref 11.720 + linkend="sec:mq:start"/> to get started 11.721 + quickly.</para> 11.722 + </listitem> 11.723 + <listitem><para id="x_518">Go into the <filename 11.724 + class="directory">inotify</filename> repo, and apply all 11.725 + of the <literal role="hg-ext">inotify</literal> patches 11.726 + using the <option role="hg-ext-mq-cmd-qpush-opt">hg 11.727 + -a</option> option to the <command 11.728 + role="hg-ext-mq">qpush</command> command.</para> 11.729 + <programlisting>cd inotify 11.730 +hg qpush -a</programlisting> 11.731 + </listitem> 11.732 + <listitem><para id="x_519"> If you get an error message from <command 11.733 + role="hg-ext-mq">qpush</command>, you should not continue. 11.734 + Instead, ask for help.</para> 11.735 + </listitem> 11.736 + <listitem><para id="x_51a">Build and install the patched version of 11.737 + Mercurial.</para> 11.738 + <programlisting>python setup.py build --force 11.739 +sudo python setup.py install --skip-build</programlisting> 11.740 + </listitem> 11.741 + </orderedlist> 11.742 + <para id="x_51b">Once you've build a suitably patched version of Mercurial, 11.743 + all you need to do to enable the <literal 11.744 + role="hg-ext">inotify</literal> extension is add an entry to 11.745 + your <filename role="special">~/.hgrc</filename>.</para> 11.746 + <programlisting>[extensions] inotify =</programlisting> 11.747 + <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 11.748 + is enabled, Mercurial will automatically and transparently start 11.749 + the status daemon the first time you run a command that needs 11.750 + status in a repository. It runs one status daemon per 11.751 + repository.</para> 11.752 + 11.753 + <para id="x_51d">The status daemon is started silently, and runs in the 11.754 + background. If you look at a list of running processes after 11.755 + you've enabled the <literal role="hg-ext">inotify</literal> 11.756 + extension and run a few commands in different repositories, 11.757 + you'll thus see a few <literal>hg</literal> processes sitting 11.758 + around, waiting for updates from the kernel and queries from 11.759 + Mercurial.</para> 11.760 + 11.761 + <para id="x_51e">The first time you run a Mercurial command in a repository 11.762 + when you have the <literal role="hg-ext">inotify</literal> 11.763 + extension enabled, it will run with about the same performance 11.764 + as a normal Mercurial command. This is because the status 11.765 + daemon needs to perform a normal status scan so that it has a 11.766 + baseline against which to apply later updates from the kernel. 11.767 + However, <emphasis>every</emphasis> subsequent command that does 11.768 + any kind of status check should be noticeably faster on 11.769 + repositories of even fairly modest size. Better yet, the bigger 11.770 + your repository is, the greater a performance advantage you'll 11.771 + see. The <literal role="hg-ext">inotify</literal> daemon makes 11.772 + status operations almost instantaneous on repositories of all 11.773 + sizes!</para> 11.774 + 11.775 + <para id="x_51f">If you like, you can manually start a status daemon using 11.776 + the <command role="hg-ext-inotify">inserve</command> command. 11.777 + This gives you slightly finer control over how the daemon ought 11.778 + to run. This command will of course only be available when the 11.779 + <literal role="hg-ext">inotify</literal> extension is 11.780 + enabled.</para> 11.781 + 11.782 + <para id="x_520">When you're using the <literal 11.783 + role="hg-ext">inotify</literal> extension, you should notice 11.784 + <emphasis>no difference at all</emphasis> in Mercurial's 11.785 + behavior, with the sole exception of status-related commands 11.786 + running a whole lot faster than they used to. You should 11.787 + specifically expect that commands will not print different 11.788 + output; neither should they give different results. If either of 11.789 + these situations occurs, please report a bug.</para> 11.790 + 11.791 + </sect1> 11.792 + <sect1 id="sec:hgext:extdiff"> 11.793 + <title>Flexible diff support with the <literal 11.794 + role="hg-ext">extdiff</literal> extension</title> 11.795 + 11.796 + <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 11.797 + diff</command> command outputs plaintext unified diffs.</para> 11.798 + 11.799 + &interaction.extdiff.diff; 11.800 + 11.801 + <para id="x_522">If you would like to use an external tool to display 11.802 + modifications, you'll want to use the <literal 11.803 + role="hg-ext">extdiff</literal> extension. This will let you 11.804 + use, for example, a graphical diff tool.</para> 11.805 + 11.806 + <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 11.807 + bundled with Mercurial, so it's easy to set up. In the <literal 11.808 + role="rc-extensions">extensions</literal> section of your 11.809 + <filename role="special">~/.hgrc</filename>, simply add a 11.810 + one-line entry to enable the extension.</para> 11.811 + <programlisting>[extensions] 11.812 +extdiff =</programlisting> 11.813 + <para id="x_524">This introduces a command named <command 11.814 + role="hg-ext-extdiff">extdiff</command>, which by default uses 11.815 + your system's <command>diff</command> command to generate a 11.816 + unified diff in the same form as the built-in <command 11.817 + role="hg-cmd">hg diff</command> command.</para> 11.818 + 11.819 + &interaction.extdiff.extdiff; 11.820 + 11.821 + <para id="x_525">The result won't be exactly the same as with the built-in 11.822 + <command role="hg-cmd">hg diff</command> variations, because the 11.823 + output of <command>diff</command> varies from one system to 11.824 + another, even when passed the same options.</para> 11.825 + 11.826 + <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 11.827 + lines of output above imply, the <command 11.828 + role="hg-ext-extdiff">extdiff</command> command works by 11.829 + creating two snapshots of your source tree. The first snapshot 11.830 + is of the source revision; the second, of the target revision or 11.831 + working directory. The <command 11.832 + role="hg-ext-extdiff">extdiff</command> command generates 11.833 + these snapshots in a temporary directory, passes the name of 11.834 + each directory to an external diff viewer, then deletes the 11.835 + temporary directory. For efficiency, it only snapshots the 11.836 + directories and files that have changed between the two 11.837 + revisions.</para> 11.838 + 11.839 + <para id="x_527">Snapshot directory names have the same base name as your 11.840 + repository. If your repository path is <filename 11.841 + class="directory">/quux/bar/foo</filename>, then <filename 11.842 + class="directory">foo</filename> will be the name of each 11.843 + snapshot directory. Each snapshot directory name has its 11.844 + changeset ID appended, if appropriate. If a snapshot is of 11.845 + revision <literal>a631aca1083f</literal>, the directory will be 11.846 + named <filename class="directory">foo.a631aca1083f</filename>. 11.847 + A snapshot of the working directory won't have a changeset ID 11.848 + appended, so it would just be <filename 11.849 + class="directory">foo</filename> in this example. To see what 11.850 + this looks like in practice, look again at the <command 11.851 + role="hg-ext-extdiff">extdiff</command> example above. Notice 11.852 + that the diff has the snapshot directory names embedded in its 11.853 + header.</para> 11.854 + 11.855 + <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 11.856 + accepts two important options. The <option 11.857 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 11.858 + lets you choose a program to view differences with, instead of 11.859 + <command>diff</command>. With the <option 11.860 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, 11.861 + you can change the options that <command 11.862 + role="hg-ext-extdiff">extdiff</command> passes to the program 11.863 + (by default, these options are 11.864 + <quote><literal>-Npru</literal></quote>, which only make sense 11.865 + if you're running <command>diff</command>). In other respects, 11.866 + the <command role="hg-ext-extdiff">extdiff</command> command 11.867 + acts similarly to the built-in <command role="hg-cmd">hg 11.868 + diff</command> command: you use the same option names, syntax, 11.869 + and arguments to specify the revisions you want, the files you 11.870 + want, and so on.</para> 11.871 + 11.872 + <para id="x_529">As an example, here's how to run the normal system 11.873 + <command>diff</command> command, getting it to generate context 11.874 + diffs (using the <option role="cmd-opt-diff">-c</option> option) 11.875 + instead of unified diffs, and five lines of context instead of 11.876 + the default three (passing <literal>5</literal> as the argument 11.877 + to the <option role="cmd-opt-diff">-C</option> option).</para> 11.878 + 11.879 + &interaction.extdiff.extdiff-ctx; 11.880 + 11.881 + <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 11.882 + launch the <command>kdiff3</command> viewer.</para> 11.883 + <programlisting>hg extdiff -p kdiff3 -o</programlisting> 11.884 + 11.885 + <para id="x_52b">If your diff viewing command can't deal with directories, 11.886 + you can easily work around this with a little scripting. For an 11.887 + example of such scripting in action with the <literal 11.888 + role="hg-ext">mq</literal> extension and the 11.889 + <command>interdiff</command> command, see <xref 11.890 + linkend="mq-collab:tips:interdiff"/>.</para> 11.891 + 11.892 + <sect2> 11.893 + <title>Defining command aliases</title> 11.894 + 11.895 + <para id="x_52c">It can be cumbersome to remember the options to both the 11.896 + <command role="hg-ext-extdiff">extdiff</command> command and 11.897 + the diff viewer you want to use, so the <literal 11.898 + role="hg-ext">extdiff</literal> extension lets you define 11.899 + <emphasis>new</emphasis> commands that will invoke your diff 11.900 + viewer with exactly the right options.</para> 11.901 + 11.902 + <para id="x_52d">All you need to do is edit your <filename 11.903 + role="special">~/.hgrc</filename>, and add a section named 11.904 + <literal role="rc-extdiff">extdiff</literal>. Inside this 11.905 + section, you can define multiple commands. Here's how to add 11.906 + a <literal>kdiff3</literal> command. Once you've defined 11.907 + this, you can type <quote><literal>hg kdiff3</literal></quote> 11.908 + and the <literal role="hg-ext">extdiff</literal> extension 11.909 + will run <command>kdiff3</command> for you.</para> 11.910 + <programlisting>[extdiff] 11.911 +cmd.kdiff3 =</programlisting> 11.912 + <para id="x_52e">If you leave the right hand side of the definition empty, 11.913 + as above, the <literal role="hg-ext">extdiff</literal> 11.914 + extension uses the name of the command you defined as the name 11.915 + of the external program to run. But these names don't have to 11.916 + be the same. Here, we define a command named 11.917 + <quote><literal>hg wibble</literal></quote>, which runs 11.918 + <command>kdiff3</command>.</para> 11.919 + <programlisting>[extdiff] 11.920 + cmd.wibble = kdiff3</programlisting> 11.921 + 11.922 + <para id="x_52f">You can also specify the default options that you want to 11.923 + invoke your diff viewing program with. The prefix to use is 11.924 + <quote><literal>opts.</literal></quote>, followed by the name 11.925 + of the command to which the options apply. This example 11.926 + defines a <quote><literal>hg vimdiff</literal></quote> command 11.927 + that runs the <command>vim</command> editor's 11.928 + <literal>DirDiff</literal> extension.</para> 11.929 + <programlisting>[extdiff] 11.930 + cmd.vimdiff = vim 11.931 +opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> 11.932 + 11.933 + </sect2> 11.934 + </sect1> 11.935 + <sect1 id="sec:hgext:transplant"> 11.936 + <title>Cherrypicking changes with the <literal 11.937 + role="hg-ext">transplant</literal> extension</title> 11.938 + 11.939 + <para id="x_530">Need to have a long chat with Brendan about this.</para> 11.940 + 11.941 + </sect1> 11.942 + <sect1 id="sec:hgext:patchbomb"> 11.943 + <title>Send changes via email with the <literal 11.944 + role="hg-ext">patchbomb</literal> extension</title> 11.945 + 11.946 + <para id="x_531">Many projects have a culture of <quote>change 11.947 + review</quote>, in which people send their modifications to a 11.948 + mailing list for others to read and comment on before they 11.949 + commit the final version to a shared repository. Some projects 11.950 + have people who act as gatekeepers; they apply changes from 11.951 + other people to a repository to which those others don't have 11.952 + access.</para> 11.953 + 11.954 + <para id="x_532">Mercurial makes it easy to send changes over email for 11.955 + review or application, via its <literal 11.956 + role="hg-ext">patchbomb</literal> extension. The extension is 11.957 + so named because changes are formatted as patches, and it's usual 11.958 + to send one changeset per email message. Sending a long series 11.959 + of changes by email is thus much like <quote>bombing</quote> the 11.960 + recipient's inbox, hence <quote>patchbomb</quote>.</para> 11.961 + 11.962 + <para id="x_533">As usual, the basic configuration of the <literal 11.963 + role="hg-ext">patchbomb</literal> extension takes just one or 11.964 + two lines in your <filename role="special"> 11.965 + /.hgrc</filename>.</para> 11.966 + <programlisting>[extensions] 11.967 +patchbomb =</programlisting> 11.968 + <para id="x_534">Once you've enabled the extension, you will have a new 11.969 + command available, named <command 11.970 + role="hg-ext-patchbomb">email</command>.</para> 11.971 + 11.972 + <para id="x_535">The safest and best way to invoke the <command 11.973 + role="hg-ext-patchbomb">email</command> command is to 11.974 + <emphasis>always</emphasis> run it first with the <option 11.975 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 11.976 + This will show you what the command <emphasis>would</emphasis> 11.977 + send, without actually sending anything. Once you've had a 11.978 + quick glance over the changes and verified that you are sending 11.979 + the right ones, you can rerun the same command, with the <option 11.980 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 11.981 + removed.</para> 11.982 + 11.983 + <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 11.984 + accepts the same kind of revision syntax as every other 11.985 + Mercurial command. For example, this command will send every 11.986 + revision between 7 and <literal>tip</literal>, inclusive.</para> 11.987 + <programlisting>hg email -n 7:tip</programlisting> 11.988 + <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 11.989 + compare with. If you provide a repository but no revisions, the 11.990 + <command role="hg-ext-patchbomb">email</command> command will 11.991 + send all revisions in the local repository that are not present 11.992 + in the remote repository. If you additionally specify revisions 11.993 + or a branch name (the latter using the <option 11.994 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 11.995 + this will constrain the revisions sent.</para> 11.996 + 11.997 + <para id="x_538">It's perfectly safe to run the <command 11.998 + role="hg-ext-patchbomb">email</command> command without the 11.999 + names of the people you want to send to: if you do this, it will 11.1000 + just prompt you for those values interactively. (If you're 11.1001 + using a Linux or Unix-like system, you should have enhanced 11.1002 + <literal>readline</literal>-style editing capabilities when 11.1003 + entering those headers, too, which is useful.)</para> 11.1004 + 11.1005 + <para id="x_539">When you are sending just one revision, the <command 11.1006 + role="hg-ext-patchbomb">email</command> command will by 11.1007 + default use the first line of the changeset description as the 11.1008 + subject of the single email message it sends.</para> 11.1009 + 11.1010 + <para id="x_53a">If you send multiple revisions, the <command 11.1011 + role="hg-ext-patchbomb">email</command> command will usually 11.1012 + send one message per changeset. It will preface the series with 11.1013 + an introductory message, in which you should describe the 11.1014 + purpose of the series of changes you're sending.</para> 11.1015 + 11.1016 + <sect2> 11.1017 + <title>Changing the behavior of patchbombs</title> 11.1018 + 11.1019 + <para id="x_53b">Not every project has exactly the same conventions for 11.1020 + sending changes in email; the <literal 11.1021 + role="hg-ext">patchbomb</literal> extension tries to 11.1022 + accommodate a number of variations through command line 11.1023 + options.</para> 11.1024 + <itemizedlist> 11.1025 + <listitem><para id="x_53c">You can write a subject for the introductory 11.1026 + message on the command line using the <option 11.1027 + role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 11.1028 + option. This takes one argument, the text of the subject 11.1029 + to use.</para> 11.1030 + </listitem> 11.1031 + <listitem><para id="x_53d">To change the email address from which the 11.1032 + messages originate, use the <option 11.1033 + role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 11.1034 + option. This takes one argument, the email address to 11.1035 + use.</para> 11.1036 + </listitem> 11.1037 + <listitem><para id="x_53e">The default behavior is to send unified diffs 11.1038 + (see <xref linkend="sec:mq:patch"/> for a 11.1039 + description of the 11.1040 + format), one per message. You can send a binary bundle 11.1041 + instead with the <option 11.1042 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 11.1043 + option.</para> 11.1044 + </listitem> 11.1045 + <listitem><para id="x_53f">Unified diffs are normally prefaced with a 11.1046 + metadata header. You can omit this, and send unadorned 11.1047 + diffs, with the <option 11.1048 + role="hg-ext-patchbomb-cmd-email-opt">hg 11.1049 + --plain</option> option.</para> 11.1050 + </listitem> 11.1051 + <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 11.1052 + in the same body part as the description of a patch. This 11.1053 + makes it easiest for the largest number of readers to 11.1054 + quote and respond to parts of a diff, as some mail clients 11.1055 + will only quote the first MIME body part in a message. If 11.1056 + you'd prefer to send the description and the diff in 11.1057 + separate body parts, use the <option 11.1058 + role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 11.1059 + option.</para> 11.1060 + </listitem> 11.1061 + <listitem><para id="x_541">Instead of sending mail messages, you can 11.1062 + write them to an <literal>mbox</literal>-format mail 11.1063 + folder using the <option 11.1064 + role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 11.1065 + option. That option takes one argument, the name of the 11.1066 + file to write to.</para> 11.1067 + </listitem> 11.1068 + <listitem><para id="x_542">If you would like to add a 11.1069 + <command>diffstat</command>-format summary to each patch, 11.1070 + and one to the introductory message, use the <option 11.1071 + role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> 11.1072 + option. The <command>diffstat</command> command displays 11.1073 + a table containing the name of each file patched, the 11.1074 + number of lines affected, and a histogram showing how much 11.1075 + each file is modified. This gives readers a qualitative 11.1076 + glance at how complex a patch is.</para> 11.1077 + </listitem></itemizedlist> 11.1078 + 11.1079 + </sect2> 11.1080 + </sect1> 11.1081 </chapter> 11.1082 11.1083 <!-- 11.1084 local variables: 11.1085 sgml-parent-document: ("00book.xml" "book" "chapter") 11.1086 end: 11.1087 ---> 11.1088 \ No newline at end of file 11.1089 +-->