hgbook
changeset 996:6f8c48362758
merge with trunk
author | Romain PELISSE <belaran@gmail.com> |
---|---|
date | Sat Sep 12 17:58:56 2009 +0200 (2009-09-12) |
parents | 56953b292c8a c05663baf56b |
children | c9ad85fd2f38 |
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/appA-svn.xml Sat Sep 12 17:58:26 2009 +0200 1.2 +++ b/fr/appA-svn.xml Sat Sep 12 17:58:56 2009 +0200 1.3 @@ -11,7 +11,7 @@ 1.4 1.5 <para id="x_6e2">Dans cette annexe, nous discuterons comment importer 1.6 l'historique d'un projet dans Mercurial, et à quoi faire attention 1.7 - si vous êtes habitué à un autre outil de gestion de révisions. 1.8 + si vous êtes habitués à un autre outil de gestion de révisions. 1.9 </para> 1.10 1.11 <sect1> 1.12 @@ -70,7 +70,7 @@ 1.13 manière incrémentale. En d'autres mots, après une première exécution de 1.14 la commande <command>hg convert</command>, les exécutions ultérieures 1.15 importeront les révisions ultérieures à l'exécution précédente. 1.16 - La conversion incrémentale ne réussiera que si 1.17 + La conversion incrémentale ne réussira que si 1.18 vous exécutez <command>hg convert</command> dans le même dépôt que vous 1.19 aviez utilisé à l'origine, ceci parce que l'extension <literal>convert</literal> 1.20 sauvegarde un certain nombre de méta-données privées dans le fichier 1.21 @@ -93,7 +93,7 @@ 1.22 à la place l'URL <literal>http://python-nose.googlecode.com/svn</literal>, 1.23 Mercurial va automatiquement détecter la 1.24 <literal>branche principale (trunk)</literal>, les <literal>étiquettes 1.25 - (tags)</literal>, et les <literal>branches</literal> que les dépôt 1.26 + (tags)</literal>, et les <literal>branches</literal> que les dépôts 1.27 Subversion utilisent généralement, et les importera chacun dans 1.28 une branche Mercurial distincte.</para> 1.29 1.30 @@ -162,7 +162,7 @@ 1.31 <para id="x_6f5">Pour indiquer le fichier d'association, on utilise 1.32 l'option <option>--filemap</option> en lui fournissant un nom de 1.33 fichier. Le fichier d'association contient des lignes de la forme 1.34 - suivante:</para> 1.35 + suivante :</para> 1.36 1.37 <programlisting># Ceci est un commentaire. 1.38 # Les lignes vides sont ignorées. 1.39 @@ -196,8 +196,8 @@ 1.40 1.41 <para id="x_70b">Vous aurez souvent besoin de plusieurs essais 1.42 avant d'arriver à la parfaite combinaison de fichier d'association de fichiers, 1.43 - de fichier d'association de noms d'utilisateurs et des autres paramètres. Hors, 1.44 - convertir un dépôt Mercurial via un protocol comme <literal>ssh</literal> 1.45 + de fichier d'association de noms d'utilisateurs et des autres paramètres. Or, 1.46 + convertir un dépôt Mercurial via un protocole comme <literal>ssh</literal> 1.47 ou <literal>http</literal> peut être des milliers de fois plus long 1.48 que ce dont le système d'exploitation est en fait capable de faire, 1.49 à cause des latence réseau. Ceci peut rendre la conception de cette 1.50 @@ -212,7 +212,7 @@ 1.51 Mercurial.</para> 1.52 1.53 <para id="x_70d">Supposez que nous voulions convertir le dépôt 1.54 - Subversion du populaire projet Memcached en une arboresence Mercurial. 1.55 + Subversion du populaire projet Memcached en une arborescence Mercurial. 1.56 Tout d'abord, nous créons un dépôt Subversion local.</para> 1.57 1.58 <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen> 1.59 @@ -244,7 +244,7 @@ 1.60 Il suffit d'exécuter de nouveau <command>svnsync</command> pour 1.61 récupérer les récentes modifications dans notre miroir, puis <command>hg 1.62 convert</command> 1.63 - les importe dans notre arboresence Mercurial.</para> 1.64 + les importe dans notre arborescence Mercurial.</para> 1.65 1.66 <para id="x_713">Il y a deux avantages à utiliser un import à deux 1.67 étages comme avec <command>svnsync</command>. Le premier 1.68 @@ -253,7 +253,7 @@ 1.69 et donc transfère moins de données par le réseau. Le deuxième 1.70 est que l'import depuis un dépôt Subversion local est si rapide que 1.71 vous pouvez peaufiner et réitérer les paramètres de conversion de 1.72 - ce dernier sans souffrir de la qualité de la connection réseau.</para> 1.73 + ce dernier sans souffrir de la qualité de la connexion réseau.</para> 1.74 </sect2> 1.75 </sect1> 1.76 1.77 @@ -275,7 +275,7 @@ 1.78 l'historique d'un projet sur votre disque dur local, il n'a besoin 1.79 d'effectuer des accès au réseau que lorsque vous voulez 1.80 explicitement communiquer avec un autre dépôt. Subversion, par contre, 1.81 - ne conserve que peu d'information localement, et le client 1.82 + ne conserve que peu d'informations localement, et le client 1.83 doit donc communiquer avec le serveur central pour la 1.84 plupart des opérations communes.</para> 1.85 1.86 @@ -293,21 +293,21 @@ 1.87 traite la plupart des commandes comme des requêtes à exécuter sur le 1.88 répertoire où vous vous situez, et ses sous répertoires. Par exemple, 1.89 si vous exécutez <command>svn log</command>, vous verrez l'historique 1.90 - de la partie de l'arboresence où vous vous situez, et non de la 1.91 + de la partie de l'arborescence où vous vous situez, et non de la 1.92 hiérarchie entière.</para> 1.93 1.94 <para id="x_6fc">Les commandes de Mercurial ont un comportement 1.95 - différent : toutes les commandes s'appliquent à l'ensemble de l'arboresence 1.96 + différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence 1.97 du dépôt. Exécutez la commande <command>hg log</command> et elle vous 1.98 - donnera l'historique de l'ensemble de l'arboresence, quel que soit le 1.99 + donnera l'historique de l'ensemble de l'arborescence, quel que soit le 1.100 sous-répertoire où vous vous situez. Si 1.101 vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un 1.102 fichier, ajouter simplement le nom de celui-ci à la commande, par 1.103 exemple <command>hg log src</command>.</para> 1.104 1.105 <para id="x_6fd">De ma propre expérience, cette différence dans leur 1.106 - comportement par défaut est le plus probablement ce qui risque de vous 1.107 - surprendre si vous passez régulièrement d'un outil à l'autre.</para> 1.108 + comportement par défaut est probablement ce qui risque de vous 1.109 + surprendre le plus si vous passez régulièrement d'un outil à l'autre.</para> 1.110 </sect3> 1.111 1.112 <sect3> 1.113 @@ -316,7 +316,7 @@ 1.114 <para id="x_6fe">Avec Subversion, il est normal (bien que légèrement 1.115 désapprouvé) que différentes personnes collaborent sur une seule 1.116 branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses 1.117 - modications à leur branche partagée, Bob doit alors mettre à jour 1.118 + modifications à leur branche partagée, Bob doit alors mettre à jour 1.119 sa vue de la branche avant de pouvoir appliquer un commit. 1.120 Puisqu'il n'a, à ce moment, pas effectué de commit 1.121 des modifications qu'il a faites, il se peut qu'il ne corrompe 1.122 @@ -340,7 +340,7 @@ 1.123 est assez complexe pour que, en pratique, elle ne soit que rarement utilisé. 1.124 Mercurial propose de son côté un mode un peu moins sûr, permettant de 1.125 récupérer des modifications par dessus des modifications non 1.126 - commitées, qui reste toutefois très peu répandu.</para> 1.127 + committées, qui reste toutefois très peu répandu.</para> 1.128 </sect3> 1.129 1.130 <sect3> 1.131 @@ -355,16 +355,16 @@ 1.132 enregistrées localement, et doivent être par la suite transférés par 1.133 la commande <command>hg push</command>.</para> 1.134 1.135 - <para id="x_703">Chaque approche à ses avantages et ses inconvénients. 1.136 + <para id="x_703">Chaque approche a ses avantages et ses inconvénients. 1.137 Le modèle Subversion implique que les modifications soient publiées, et 1.138 donc disponibles immédiatement. D'un autre coté, cela implique aussi 1.139 que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit 1.140 avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé 1.141 facilement par la plupart des projets Open Source.</para> 1.142 1.143 - <para id="x_704">L'approche de Mercurial permet à quiquonque de faire 1.144 + <para id="x_704">L'approche de Mercurial permet à quiconque de faire 1.145 un clone du dépôt et d'y ajouter ses modifications sans jamais avoir 1.146 - besoin de la permission de quiquonque, et l'on peut même publier ses 1.147 + besoin de la permission de quiconque, et l'on peut même publier ses 1.148 modifications et continuer à participer comme on le désire. Toutefois, la 1.149 distinction entre les commits et le transfert de ces derniers présente 1.150 le risque que quelqu'un applique ses modifications par un commit local 1.151 @@ -533,15 +533,15 @@ 1.152 <command>hg log -r104654 -p</command>.</para> 1.153 1.154 <para id="x_706">Quand vous exécutez la commande <command>hg status</command> 1.155 - sans aucun arguments, elle affiche l'état de l'ensemble de l'arboresence, 1.156 - avec des chemins relatifs partant de la raçine du dépôt. Ceci rend 1.157 + sans aucun argument, elle affiche l'état de l'ensemble de l'arborescence, 1.158 + avec des chemins relatifs partant de la racine du dépôt. Ceci rend 1.159 difficile de copier un nom de fichier depuis la sortie de la commande 1.160 <command>hg status</command> dans une autre ligne de commande. Si vous 1.161 fournissez un fichier ou un répertoire à la commande <command>hg 1.162 status</command>, elle va afficher les chemins relatif depuis votre 1.163 répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble 1.164 - de l'arboresence à l'aide de <command>hg status</command>, avec des 1.165 - chemins relatifs à votre répertoire courant, et non le racine du dépôt, 1.166 + de l'arborescence à l'aide de <command>hg status</command>, avec des 1.167 + chemins relatifs à votre répertoire courant, et non la racine du dépôt, 1.168 ajoutez la sortie de <command>hg root</command> à la commande 1.169 <command>hg status</command>. Vous pouvez le faire aisément sur un 1.170 système Unix ainsi :</para>
2.1 --- a/fr/appC-srcinstall.xml Sat Sep 12 17:58:26 2009 +0200 2.2 +++ b/fr/appC-srcinstall.xml Sat Sep 12 17:58:56 2009 +0200 2.3 @@ -18,7 +18,7 @@ 2.4 <programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting> 2.5 </listitem> 2.6 <listitem><para id="x_5e3">Allez dans le répertoires où les sources ont 2.7 - été extraites et executez le script d'installation. Ce dernier compilera 2.8 + été extraites et exécutez le script d'installation. Ce dernier compilera 2.9 Mercurial et l'installera dans votre répertoire utilisateur.</para> 2.10 <programlisting>cd mercurial-MYVERSION 2.11 python setup.py install --force --home=$HOME</programlisting> 2.12 @@ -32,7 +32,7 @@ 2.13 2.14 <para id="x_5e5">Vous devrez vraisemblablement définir la variable 2.15 d'environnement <envar>PYTHONPATH</envar> de manière à ce que 2.16 - l'executable de Mercurial puisse trouver le reste des paquets logiciels. 2.17 + l'exécutable de Mercurial puisse trouver le reste des paquets logiciels. 2.18 Par exemple, sur mon ordinateur portable, je dois le définir ainsi: 2.19 <literal>/home/bos/lib/python</literal>. Le chemin exact à utiliser 2.20 dépendra de la manière dont Python aura été construit pour votre
3.1 --- a/fr/appD-license.xml Sat Sep 12 17:58:26 2009 +0200 3.2 +++ b/fr/appD-license.xml Sat Sep 12 17:58:56 2009 +0200 3.3 @@ -1,185 +1,179 @@ 3.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 3.5 3.6 -<chapter> 3.7 -<title>Open Publication License</title> 3.8 -<para>\label{cha:opl}</para> 3.9 +<appendix id="cha:opl"> 3.10 + <?dbhtml filename="open-publication-license.html"?> 3.11 + <title>Open Publication License</title> 3.12 3.13 -<para>Version 1.0, 8 June 1999</para> 3.14 + <para id="x_638">Version 1.0, 8 June 1999</para> 3.15 3.16 -<sect1> 3.17 -<title>Requirements on both unmodified and modified versions</title> 3.18 + <sect1> 3.19 + <title>Requirements on both unmodified and modified 3.20 + versions</title> 3.21 3.22 -<para>The Open Publication works may be reproduced and distributed in whole 3.23 -or in part, in any medium physical or electronic, provided that the 3.24 -terms of this license are adhered to, and that this license or an 3.25 -incorporation of it by reference (with any options elected by the 3.26 -author(s) and/or publisher) is displayed in the reproduction.</para> 3.27 + <para id="x_639">The Open Publication works may be reproduced and distributed 3.28 + in whole or in part, in any medium physical or electronic, 3.29 + provided that the terms of this license are adhered to, and that 3.30 + this license or an incorporation of it by reference (with any 3.31 + options elected by the author(s) and/or publisher) is displayed 3.32 + in the reproduction.</para> 3.33 3.34 -<para>Proper form for an incorporation by reference is as follows:</para> 3.35 + <para id="x_63a">Proper form for an incorporation by reference is as 3.36 + follows:</para> 3.37 3.38 -<blockquote> 3.39 -<para> Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or designee</emphasis>. This 3.40 - material may be distributed only subject to the terms and conditions 3.41 - set forth in the Open Publication License, v<emphasis>x.y</emphasis> or later (the 3.42 - latest version is presently available at 3.43 - <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para> 3.44 -</blockquote> 3.45 + <blockquote> 3.46 + <para id="x_63b"> Copyright (c) <emphasis>year</emphasis> by 3.47 + <emphasis>author's name or designee</emphasis>. This material 3.48 + may be distributed only subject to the terms and conditions 3.49 + set forth in the Open Publication License, 3.50 + v<emphasis>x.y</emphasis> or later (the latest version is 3.51 + presently available at <ulink 3.52 + url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para> 3.53 + </blockquote> 3.54 3.55 -<para>The reference must be immediately followed with any options elected by 3.56 -the author(s) and/or publisher of the document (see 3.57 -section <xref linkend="sec:opl:options"/>).</para> 3.58 + <para id="x_63c">The reference must be immediately followed with any options 3.59 + elected by the author(s) and/or publisher of the document (see 3.60 + <xref linkend="sec:opl:options"/>).</para> 3.61 3.62 -<para>Commercial redistribution of Open Publication-licensed material is 3.63 -permitted.</para> 3.64 + <para id="x_63d">Commercial redistribution of Open Publication-licensed 3.65 + material is permitted.</para> 3.66 3.67 -<para>Any publication in standard (paper) book form shall require the 3.68 -citation of the original publisher and author. The publisher and 3.69 -author's names shall appear on all outer surfaces of the book. On all 3.70 -outer surfaces of the book the original publisher's name shall be as 3.71 -large as the title of the work and cited as possessive with respect to 3.72 -the title.</para> 3.73 + <para id="x_63e">Any publication in standard (paper) book form shall require 3.74 + the citation of the original publisher and author. The publisher 3.75 + and author's names shall appear on all outer surfaces of the 3.76 + book. On all outer surfaces of the book the original publisher's 3.77 + name shall be as large as the title of the work and cited as 3.78 + possessive with respect to the title.</para> 3.79 3.80 -</sect1> 3.81 -<sect1> 3.82 -<title>Copyright</title> 3.83 + </sect1> 3.84 + <sect1> 3.85 + <title>Copyright</title> 3.86 3.87 -<para>The copyright to each Open Publication is owned by its author(s) or 3.88 -designee. 3.89 -</para> 3.90 + <para id="x_63f">The copyright to each Open Publication is owned by its 3.91 + author(s) or designee.</para> 3.92 3.93 -</sect1> 3.94 -<sect1> 3.95 -<title>Scope of license</title> 3.96 + </sect1> 3.97 + <sect1> 3.98 + <title>Scope of license</title> 3.99 3.100 -<para>The following license terms apply to all Open Publication works, 3.101 -unless otherwise explicitly stated in the document. 3.102 -</para> 3.103 + <para id="x_640">The following license terms apply to all Open Publication 3.104 + works, unless otherwise explicitly stated in the 3.105 + document.</para> 3.106 3.107 -<para>Mere aggregation of Open Publication works or a portion of an Open 3.108 -Publication work with other works or programs on the same media shall 3.109 -not cause this license to apply to those other works. The aggregate 3.110 -work shall contain a notice specifying the inclusion of the Open 3.111 -Publication material and appropriate copyright notice. 3.112 -</para> 3.113 + <para id="x_641">Mere aggregation of Open Publication works or a portion of 3.114 + an Open Publication work with other works or programs on the 3.115 + same media shall not cause this license to apply to those other 3.116 + works. The aggregate work shall contain a notice specifying the 3.117 + inclusion of the Open Publication material and appropriate 3.118 + copyright notice.</para> 3.119 3.120 -<para><emphasis role="bold">Severability</emphasis>. If any part of this license is found to be 3.121 -unenforceable in any jurisdiction, the remaining portions of the 3.122 -license remain in force. 3.123 -</para> 3.124 + <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part 3.125 + of this license is found to be unenforceable in any 3.126 + jurisdiction, the remaining portions of the license remain in 3.127 + force.</para> 3.128 3.129 -<para><emphasis role="bold">No warranty</emphasis>. Open Publication works are licensed and provided 3.130 -<quote>as is</quote> without warranty of any kind, express or implied, including, 3.131 -but not limited to, the implied warranties of merchantability and 3.132 -fitness for a particular purpose or a warranty of non-infringement. 3.133 -</para> 3.134 + <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open 3.135 + Publication works are licensed and provided <quote>as is</quote> 3.136 + without warranty of any kind, express or implied, including, but 3.137 + not limited to, the implied warranties of merchantability and 3.138 + fitness for a particular purpose or a warranty of 3.139 + non-infringement.</para> 3.140 3.141 -</sect1> 3.142 -<sect1> 3.143 -<title>Requirements on modified works</title> 3.144 + </sect1> 3.145 + <sect1> 3.146 + <title>Requirements on modified works</title> 3.147 3.148 -<para>All modified versions of documents covered by this license, including 3.149 -translations, anthologies, compilations and partial documents, must 3.150 -meet the following requirements: 3.151 -</para> 3.152 + <para id="x_644">All modified versions of documents covered by this license, 3.153 + including translations, anthologies, compilations and partial 3.154 + documents, must meet the following requirements:</para> 3.155 3.156 -<orderedlist> 3.157 -<listitem><para>The modified version must be labeled as such. 3.158 -</para> 3.159 -</listitem> 3.160 -<listitem><para>The person making the modifications must be identified and the 3.161 - modifications dated. 3.162 -</para> 3.163 -</listitem> 3.164 -<listitem><para>Acknowledgement of the original author and publisher if 3.165 - applicable must be retained according to normal academic citation 3.166 - practices. 3.167 -</para> 3.168 -</listitem> 3.169 -<listitem><para>The location of the original unmodified document must be 3.170 - identified. 3.171 -</para> 3.172 -</listitem> 3.173 -<listitem><para>The original author's (or authors') name(s) may not be used to 3.174 - assert or imply endorsement of the resulting document without the 3.175 - original author's (or authors') permission. 3.176 -</para> 3.177 -</listitem></orderedlist> 3.178 + <orderedlist> 3.179 + <listitem><para id="x_645">The modified version must be labeled as 3.180 + such.</para> 3.181 + </listitem> 3.182 + <listitem><para id="x_646">The person making the modifications must be 3.183 + identified and the modifications dated.</para> 3.184 + </listitem> 3.185 + <listitem><para id="x_647">Acknowledgement of the original author and 3.186 + publisher if applicable must be retained according to normal 3.187 + academic citation practices.</para> 3.188 + </listitem> 3.189 + <listitem><para id="x_648">The location of the original unmodified document 3.190 + must be identified.</para> 3.191 + </listitem> 3.192 + <listitem><para id="x_649">The original author's (or authors') name(s) may 3.193 + not be used to assert or imply endorsement of the resulting 3.194 + document without the original author's (or authors') 3.195 + permission.</para> 3.196 + </listitem></orderedlist> 3.197 3.198 -</sect1> 3.199 -<sect1> 3.200 -<title>Good-practice recommendations</title> 3.201 + </sect1> 3.202 + <sect1> 3.203 + <title>Good-practice recommendations</title> 3.204 3.205 -<para>In addition to the requirements of this license, it is requested from 3.206 -and strongly recommended of redistributors that: 3.207 -</para> 3.208 + <para id="x_64a">In addition to the requirements of this license, it is 3.209 + requested from and strongly recommended of redistributors 3.210 + that:</para> 3.211 3.212 -<orderedlist> 3.213 -<listitem><para>If you are distributing Open Publication works on hardcopy or 3.214 - CD-ROM, you provide email notification to the authors of your intent 3.215 - to redistribute at least thirty days before your manuscript or media 3.216 - freeze, to give the authors time to provide updated documents. This 3.217 - notification should describe modifications, if any, made to the 3.218 - document. 3.219 -</para> 3.220 -</listitem> 3.221 -<listitem><para>All substantive modifications (including deletions) be either 3.222 - clearly marked up in the document or else described in an attachment 3.223 - to the document. 3.224 -</para> 3.225 -</listitem> 3.226 -<listitem><para>Finally, while it is not mandatory under this license, it is 3.227 - considered good form to offer a free copy of any hardcopy and CD-ROM 3.228 - expression of an Open Publication-licensed work to its author(s). 3.229 -</para> 3.230 -</listitem></orderedlist> 3.231 + <orderedlist> 3.232 + <listitem><para id="x_64b">If you are distributing Open Publication works 3.233 + on hardcopy or CD-ROM, you provide email notification to the 3.234 + authors of your intent to redistribute at least thirty days 3.235 + before your manuscript or media freeze, to give the authors 3.236 + time to provide updated documents. This notification should 3.237 + describe modifications, if any, made to the document.</para> 3.238 + </listitem> 3.239 + <listitem><para id="x_64c">All substantive modifications (including 3.240 + deletions) be either clearly marked up in the document or 3.241 + else described in an attachment to the document.</para> 3.242 + </listitem> 3.243 + <listitem><para id="x_64d">Finally, while it is not mandatory under this 3.244 + license, it is considered good form to offer a free copy of 3.245 + any hardcopy and CD-ROM expression of an Open 3.246 + Publication-licensed work to its author(s).</para> 3.247 + </listitem></orderedlist> 3.248 3.249 -</sect1> 3.250 -<sect1> 3.251 -<title>License options</title> 3.252 -<para>\label{sec:opl:options} 3.253 -</para> 3.254 + </sect1> 3.255 + <sect1 id="sec:opl:options"> 3.256 + <title>License options</title> 3.257 3.258 -<para>The author(s) and/or publisher of an Open Publication-licensed 3.259 -document may elect certain options by appending language to the 3.260 -reference to or copy of the license. These options are considered part 3.261 -of the license instance and must be included with the license (or its 3.262 -incorporation by reference) in derived works. 3.263 -</para> 3.264 + <para id="x_64e">The author(s) and/or publisher of an Open 3.265 + Publication-licensed document may elect certain options by 3.266 + appending language to the reference to or copy of the license. 3.267 + These options are considered part of the license instance and 3.268 + must be included with the license (or its incorporation by 3.269 + reference) in derived works.</para> 3.270 3.271 -<orderedlist> 3.272 -<listitem><para>To prohibit distribution of substantively modified versions 3.273 - without the explicit permission of the author(s). <quote>Substantive 3.274 - modification</quote> is defined as a change to the semantic content of the 3.275 - document, and excludes mere changes in format or typographical 3.276 - corrections. 3.277 -</para> 3.278 -</listitem> 3.279 -<listitem><para> To accomplish this, add the phrase <quote>Distribution of substantively 3.280 - modified versions of this document is prohibited without the 3.281 - explicit permission of the copyright holder.</quote> to the license 3.282 - reference or copy. 3.283 -</para> 3.284 -</listitem> 3.285 -</para> 3.286 -</listitem> 3.287 -<listitem><para>To prohibit any publication of this work or derivative works in 3.288 - whole or in part in standard (paper) book form for commercial 3.289 - purposes is prohibited unless prior permission is obtained from the 3.290 - copyright holder. 3.291 -</para> 3.292 -</listitem> 3.293 -<listitem><para> To accomplish this, add the phrase <quote>Distribution of the work or 3.294 - derivative of the work in any standard (paper) book form is 3.295 - prohibited unless prior permission is obtained from the copyright 3.296 - holder.</quote> to the license reference or copy. 3.297 -</para> 3.298 -</listitem></orderedlist> 3.299 + <orderedlist> 3.300 + <listitem><para id="x_64f">To prohibit distribution of substantively 3.301 + modified versions without the explicit permission of the 3.302 + author(s). <quote>Substantive modification</quote> is 3.303 + defined as a change to the semantic content of the document, 3.304 + and excludes mere changes in format or typographical 3.305 + corrections.</para> 3.306 + </listitem> 3.307 + <listitem><para id="x_650"> To accomplish this, add the phrase 3.308 + <quote>Distribution of substantively modified versions of 3.309 + this document is prohibited without the explicit 3.310 + permission of the copyright holder.</quote> to the license 3.311 + reference or copy.</para> 3.312 + </listitem> 3.313 + <listitem><para id="x_651">To prohibit any publication of this work or 3.314 + derivative works in whole or in part in standard (paper) 3.315 + book form for commercial purposes is prohibited unless prior 3.316 + permission is obtained from the copyright holder.</para> 3.317 + </listitem> 3.318 + <listitem><para id="x_652">To accomplish this, add the phrase 3.319 + <quote>Distribution of the work or derivative of the work in 3.320 + any standard (paper) book form is prohibited unless prior 3.321 + permission is obtained from the copyright holder.</quote> 3.322 + to the license reference or copy.</para> 3.323 + </listitem></orderedlist> 3.324 3.325 -</sect1> 3.326 -</chapter> 3.327 + </sect1> 3.328 +</appendix> 3.329 3.330 <!-- 3.331 local variables: 3.332 -sgml-parent-document: ("00book.xml" "book" "chapter") 3.333 +sgml-parent-document: ("00book.xml" "book" "appendix") 3.334 end: 3.335 ---> 3.336 \ No newline at end of file 3.337 +-->
4.1 --- a/fr/ch00-preface.xml Sat Sep 12 17:58:26 2009 +0200 4.2 +++ b/fr/ch00-preface.xml Sat Sep 12 17:58:56 2009 +0200 4.3 @@ -8,13 +8,13 @@ 4.4 <title>Un conte technique</title> 4.5 4.6 <para id="x_72e">Il y a quelques années, quand j'ai voulu expliqué 4.7 - pourquoi je pensais que le gestion de révision distribué est importante, 4.8 + pourquoi je pensais que le gestion de révision distribuée est importante, 4.9 le domaine était encore si nouveau qu'il n'y avait presque aucune 4.10 - littérature publiée pour servir de référence aux personnes intéressés.</para> 4.11 - 4.12 - <para id="x_72f">Bien que à cette époque je passais beaucoup de temps 4.13 + littérature publiée pour servir de référence aux personnes intéressées.</para> 4.14 + 4.15 + <para id="x_72f">Bien qu'à cette époque je passais beaucoup de temps 4.16 à travailler sur les entrailles de Mercurial, je me suis mis à la 4.17 - rédaction de ce livre parce qu'il me semblait la manière la plus efficase 4.18 + rédaction de ce livre parce qu'il me semblait la manière la plus efficace 4.19 d'aider notre logiciel à atteindre un vaste auditoire, toujours avec 4.20 l'idée que la gestion de révision devrait être distribuée par nature. J'ai 4.21 publié ce libre en ligne sous une licence libre pour la même raison : pour 4.22 @@ -24,54 +24,54 @@ 4.23 qui ressemble de près au fait de conter une histoire : Pourquoi ceci est ? 4.24 Pourquoi ceci est important ? Comment peut il m'aider ? Comment m'en 4.25 servir ? Dans ce livre, j'essaye de répondre à toutes ces questions pour 4.26 - la gestion de révision distribuée en générale, et pour Mercurial en 4.27 - particuliers.</para> 4.28 + la gestion de révision distribuée en général, et pour Mercurial en 4.29 + particulier.</para> 4.30 </sect1> 4.31 4.32 <sect1> 4.33 <title>Merci de votre soutien à Mercurial</title> 4.34 4.35 <para id="x_731">En achetant une copie de ce livre, vous soutenez le 4.36 - développement et la libérté de Mercurial en particulier, et dans 4.37 - l'Open Source et du logiciel libre en général. O'Reilly Media et 4.38 - moi-même donnons le revenu issu des ventes de ce livre à la 4.39 + développement et la liberté de Mercurial en particulier, et dans 4.40 + l'Open Source, au logiciel libre en général. O'Reilly Media et 4.41 + moi-même donnons les revenus issus des ventes de ce livre à la 4.42 Software Freedom Conservancy (<ulink 4.43 url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 4.44 qui fournit un support juridique à Mercurial et à de 4.45 - nombreux autres projets Open Source proméminent et de qualité.</para> 4.46 + nombreux autres projets Open Source proéminents et de qualité.</para> 4.47 </sect1> 4.48 4.49 <sect1> 4.50 <title>Remerciements</title> 4.51 4.52 - <para id="x_732">Ce livre ne serait pas venu au jour sans les 4.53 + <para id="x_732">Ce livre n'aurait pas vu le jour sans les 4.54 efforts de Matt Mackal, l'auteur et le chef du projet Mercurial. 4.55 - Il est assisté très efficasement par des centaines de contributeurs 4.56 - volontaire à travers le monde.</para> 4.57 - 4.58 - <para id="x_733">Les enfants, Cian and Ruairi, ont toujours été prêt 4.59 - à m'aider à me reposer avec de merveilleux, impulsif jeux d'enfants. 4.60 + Il est assisté très efficacement par des centaines de contributeurs 4.61 + volontaires à travers le monde.</para> 4.62 + 4.63 + <para id="x_733">Les enfants, Cian et Ruairi, ont toujours été prêt 4.64 + à m'aider à me reposer avec de merveilleux et impulsif jeux d'enfants. 4.65 Je tiens aussi à remercier mon ex-femme, Shannon, pour son soutien. 4.66 </para> 4.67 4.68 <para id="x_734">Mes collègues et amis m'ont aidé et assisté de 4.69 - de nombreuse manière indénombrable. Cette liste de personne est 4.70 - nécessaire mais très incomplète : Stephen Hahn, Karyn Ritter, 4.71 - Bonnie Corwin, James Vasile, Matt Norwood, Eben Moglen, Bradley Kuhn, 4.72 - Robert Walsh, Jeremy Fitzhardinge, Rachel Chalmers.</para> 4.73 + de nombreuses manières. Cette liste de personne est nécessaire mais très 4.74 + incomplète : Stephen Hahn, Karyn Ritter, Bonnie Corwin, James Vasile, 4.75 + Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh, Jeremy 4.76 + Fitzhardinge, Rachel Chalmers.</para> 4.77 4.78 <para id="x_735">J'ai conçu ce livre de manière ouverte, en publiant 4.79 - des brouillons des chapitres du libre sur des site web, au fur et à 4.80 - mesure que je les réalisés. Leurs lecteurs m'ont fait des retours 4.81 - utilisant l'application web que j'avais développé. A la fin de sa 4.82 + des brouillons des chapitres du livre sur des site web, au fur et à 4.83 + mesure que je les réalisais. Leurs lecteurs m'ont fait des retours 4.84 + utilisant l'application web que j'avais développée. A la fin de sa 4.85 conception, plus de 100 personnes m'avaient fait des commentaires, 4.86 un chiffre incroyable quand l'on considère que ce système de 4.87 - commentaire n'a tourné que dans les deux dernièrs mois de la 4.88 + commentaire n'a tourné que dans les deux derniers mois de la 4.89 rédaction du livre.</para> 4.90 4.91 <para id="x_736">J'aimerais particulièrement remercier les 4.92 personnes suivantes, dont les commentaires représentent plus 4.93 - d'un tiers des l'ensemble de ces derniers. Je voudrais les 4.94 + d'un tiers de l'ensemble de ces derniers. Je voudrais les 4.95 remercier pour leur attention et effort à me faire des retours 4.96 très détaillés.</para> 4.97 4.98 @@ -113,15 +113,16 @@ 4.99 <sect1> 4.100 <title>Conventions utilisées dans ce livre</title> 4.101 4.102 - <para id="x_73a">Les conventions typographiques suivantes sont utilisées dans ce livre.:</para> 4.103 + <para id="x_73a">Les conventions typographiques suivantes sont utilisées dans ce livre :</para> 4.104 4.105 <variablelist> 4.106 <varlistentry> 4.107 <term>Italique</term> 4.108 4.109 <listitem> 4.110 - <para id="x_73b">Indique les termes nouveaux, les URLs, les adresse mail, les noms de fichiers, 4.111 - et les extensions de fichier.</para> 4.112 + <para id="x_73b">Indique les termes nouveaux, les URLs, les 4.113 + adresses mail, les noms de fichiers et les extensions de 4.114 + fichier.</para> 4.115 </listitem> 4.116 </varlistentry> 4.117 4.118 @@ -129,11 +130,11 @@ 4.119 <term><literal>Taille constante</literal></term> 4.120 4.121 <listitem> 4.122 - <para id="x_73c">Utilisé pour les extrait de code, comme 4.123 + <para id="x_73c">Utilisé pour les extraits de code, comme 4.124 dans les paragraphes pour référer aux éléments du programme, 4.125 - tel que les variables ou les noms de fonctions, de base 4.126 - de données, de types de données, de variables d'environement, 4.127 - d'instructions, et de mot clés.</para> 4.128 + tels que les variables ou les noms de fonctions, de bases 4.129 + de données, de types de données, de variables d'environnement, 4.130 + d'instructions, et de mots clés.</para> 4.131 </listitem> 4.132 </varlistentry> 4.133 4.134 @@ -142,7 +143,7 @@ 4.135 4.136 <listitem> 4.137 <para id="x_73d">Afficher les commandes ou autres textes qui 4.138 - devraient saisie par l'utilisateur.</para> 4.139 + devraient être saisis par l'utilisateur.</para> 4.140 </listitem> 4.141 </varlistentry> 4.142 4.143 @@ -158,20 +159,20 @@ 4.144 </variablelist> 4.145 4.146 <tip> 4.147 - <para id="x_73f">Cette icone indique une astuce, une suggestion ou 4.148 + <para id="x_73f">Cette icône indique une astuce, une suggestion ou 4.149 une note d'ordre général.</para> 4.150 </tip> 4.151 4.152 <caution> 4.153 - <para id="x_740">Cette icone est un message d'alerte ou de prudence.</para> 4.154 + <para id="x_740">Cette icône est un message d'alerte ou de prudence.</para> 4.155 </caution> 4.156 </sect1> 4.157 4.158 <sect1> 4.159 - <title>Utiliser les examples de codes</title> 4.160 + <title>Utiliser les exemples de code</title> 4.161 4.162 <para id="x_741">Ce livre est ici pour vous aider dans votre 4.163 - travail. De manière général, vous pouvez donc utiliser le code 4.164 + travail. De manière générale, vous pouvez donc utiliser le code 4.165 de ce livre dans vos programmes et votre documentation. Vous 4.166 n'avez pas à nous contacter pour nous demander la permission 4.167 de le faire, à moins que vous ne reproduisiez une partie significative 4.168 @@ -199,17 +200,17 @@ 4.169 4.170 <note role="safarienabled"> 4.171 <para id="x_744">Quand vous voyez l'icône de Safari® Books Online 4.172 - sur la couverture d'un de vos livres techniques préféré, il signifie 4.173 + sur la couverture d'un de vos livres techniques préférés, cela signifie 4.174 que le livre est disponible, en ligne, à travers le O’Reilly Network Safari 4.175 Bookshelf.</para> 4.176 </note> 4.177 4.178 - <para id="x_745">Safari offre une solution qui est meilleur que 4.179 + <para id="x_745">Safari offre une solution qui est meilleure que 4.180 les e-books. C'est une bibliothèque virtuelle qui vous laisse 4.181 aisément rechercher dans des milliers de livres, mais aussi 4.182 - copier-coller leur exemples, télécharger des chapitres, et 4.183 + copier-coller leurs exemples, télécharger des chapitres, et 4.184 trouver des réponses rapides quand vous avez besoin d'une 4.185 - information précise et à jour. Essaye le gratuitement : 4.186 + information précise et à jour. Essayez le gratuitement : 4.187 <ulink role="orm:hideurl:ital" 4.188 url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para> 4.189 </sect1> 4.190 @@ -254,8 +255,8 @@ 4.191 </simplelist> 4.192 4.193 <para id="x_749">Pour plus d'informations sur nos livres, nos 4.194 - conférences, nos centre d'informations, et le O’Reilly Network, 4.195 - voyez notre site web site:</para> 4.196 + conférences, nos centres d'informations, et le réseau O’Reilly, 4.197 + voyez notre site web :</para> 4.198 4.199 <simplelist type="vert"> 4.200 <member><ulink url="http://www.oreilly.com"></ulink></member>
5.1 --- a/fr/ch01-intro.xml Sat Sep 12 17:58:26 2009 +0200 5.2 +++ b/fr/ch01-intro.xml Sat Sep 12 17:58:56 2009 +0200 5.3 @@ -14,7 +14,7 @@ 5.4 à chaque fois plus grand que celui de la version précédente.</para> 5.5 5.6 <para id="x_6e">Ce genre de gestion de version manuelle est cependant facilement sujette 5.7 -à des erreurs, ainsi, depuis longtemps, des logiciels existent pour 5.8 +aux erreurs, ainsi, depuis longtemps, des logiciels existent pour 5.9 résoudre cette problématique. Les premiers outils de gestion de sources 5.10 étaient destinés à aider un seul utilisateur, à automatiser la gestion 5.11 des versions d'un seul fichier. Dans les dernières décades, cette cible 5.12 @@ -26,15 +26,15 @@ 5.13 5.14 <para id="x_6f">L'arrivée de la gestion de révision distribuée est 5.15 relativement récente, et, pour le moment, ce nouveau domaine a grandi 5.16 - grâce à la volonté des gens d'explorer ces territoires encores inconnues. 5.17 + grâce à la volonté des gens d'explorer ces territoires encore inconnus. 5.18 </para> 5.19 5.20 <para id="x_70">J'écris un livre sur la gestion de révision distribuée 5.21 parce que je pense qu'il s'agit d'un sujet important qui mérite un guide 5.22 du terrain. J'ai choisi d'écrire un livre sur Mercurial car il est 5.23 l'outil le plus facile pour découvrir ce nouveau domaine, tout en étant 5.24 - un outil efficase qui répond aux demandes d'environement réel et 5.25 - difficile, là où d'autres outils de révisions s'effondre.</para> 5.26 + un outil efficace qui répond aux demandes d'environnements réels et 5.27 + difficiles, là où d'autres outils de gestions de versions s'effondrent.</para> 5.28 5.29 <sect2> 5.30 <title>Pourquoi utiliser un gestionnaire de source ?</title> 5.31 @@ -44,10 +44,10 @@ 5.32 5.33 <itemizedlist> 5.34 <listitem><para id="x_72">L'outil se chargera de suivre l'évolution de votre projet, sans 5.35 -que vous n'ayez à le faire. Pour chaque modification, vous aurez à votre 5.36 +que vous ayez à le faire. Pour chaque modification, vous aurez à votre 5.37 disposition un journal indiquant <emphasis>qui</emphasis> a fait quoi, <emphasis>pourquoi</emphasis> 5.38 -ils l'ont fait, <emphasis>quand</emphasis> ils l'ont fait, et <emphasis>ce</emphasis> qu'ils ont 5.39 -modifiés.</para> 5.40 +il l'a fait, <emphasis>quand</emphasis> il l'a fait, et 5.41 +<emphasis>ce</emphasis> qu'il a modifié.</para> 5.42 </listitem> 5.43 <listitem><para id="x_73">Quand vous travaillez avec d'autres personnes, les logiciels de 5.44 gestion de source facilitent le travail collaboratif. Par exemple, quand 5.45 @@ -62,42 +62,48 @@ 5.46 de détails).</para> 5.47 </listitem> 5.48 <listitem><para id="x_75">L'outil vous permettra aussi de travailler sur plusieurs versions différentes 5.49 -de votre projet et à gérer l'écart entre chacune.</para> 5.50 +de votre projet et de gérer l'écart entre chacune.</para> 5.51 </listitem></itemizedlist> 5.52 -<para id="x_76">La plupart de ces raisons ont autant d'importances &emdash;du moins en théorie&emdash; que 5.53 -vous travailliez sur un projet pour vous, ou avec une centaine d'autres 5.54 -personnes. 5.55 +<para id="x_76">La plupart de ces raisons ont autant d'importances &emdash;du 5.56 + moins en théorie&emdash; que vous travailliez sur un projet pour vous, ou 5.57 + avec une centaine d'autres personnes. 5.58 </para> 5.59 5.60 -<para id="x_77">Une question fondamentale à propos des outils de gestion de source, qu'il s'agisse 5.61 -du projet d'une personne ou d'une grande équipe, est quels sont ses 5.62 -<emphasis>avantages</emphasis> par rapport à ses <emphasis>coûts</emphasis>. Un outil qui est difficile à 5.63 -utiliser ou à comprendre exigera un lourd effort d'adaptation. 5.64 +<para id="x_77">Une question fondamentale à propos des outils de gestion de 5.65 + source, qu'il s'agisse du projet d'une personne ou d'une grande équipe, est 5.66 + quels sont ses <emphasis>avantages</emphasis> par rapport à ses 5.67 + <emphasis>coûts</emphasis>. Un outil qui est difficile à utiliser ou à 5.68 + comprendre exigera un lourd effort d'adaptation. 5.69 </para> 5.70 5.71 -<para id="x_78">)Un projet de cinq milles personnes s'effondrera très certainement de lui même 5.72 -sans aucun processus et outil de gestion de source. Dans ce cas, le coût 5.73 -d'utilisation d'un logiciel de gestion de source est dérisoire puisque 5.74 -<emphasis>sans</emphasis>, l'échec est presque garanti. 5.75 +<para id="x_78">)Un projet de cinq milles personnes s'effondrera très 5.76 + certainement de lui même sans aucun processus et outil de gestion de 5.77 + source. Dans ce cas, le coût d'utilisation d'un logiciel de gestion de 5.78 + source est dérisoire puisque <emphasis>sans</emphasis>, l'échec est presque 5.79 + garanti. 5.80 </para> 5.81 5.82 -<para id="x_79">D'un autre coté, un <quote>rapide hack</quote> d'une personne peut sembler un contexte 5.83 -bien pauvre pour utiliser un outil de gestion de source, car, bien évidement 5.84 -le coût d'utilisation dépasse le coût total du projet. N'est ce pas ? 5.85 +<para id="x_79">D'un autre coté, un <quote>rapide hack</quote> d'une personne 5.86 + peut sembler un contexte bien pauvre pour utiliser un outil de gestion de 5.87 + source, car, bien évidement le coût d'utilisation dépasse le coût total du 5.88 + projet. N'est ce pas ? 5.89 </para> 5.90 5.91 - <para id="x_7a">Mercurial supporte ces <emphasis>deux</emphasis> échelles de travail. Vous pouvez apprendre 5.92 -les bases en quelques minutes seulement, et, grâce à sa performance, vous pouvez 5.93 -l'utiliser avec facilité sur le plus petit des projets. Cette simplicité 5.94 -signifie que vous n'avez pas de concept obscurs ou de séquence de commandes 5.95 -défiant l'imagination, sans aucune corrélation avec <emphasis>ce que vous 5.96 -êtes entrain de faire</emphasis>. En même temps, ces mêmes performances et sa 5.97 -nature <quote>peer-to-peer</quote> vous permettent d'augmenter, sans difficulté, son 5.98 -utilisation à de très grands projets. 5.99 + <para id="x_7a">Mercurial supporte ces <emphasis>deux</emphasis> 5.100 + échelles de travail. Vous pouvez apprendre les bases en quelques 5.101 + minutes seulement, et, grâce à sa performance, vous pouvez l'utiliser 5.102 + avec facilité sur le plus petit des projets. Cette simplicité 5.103 + signifie que vous n'avez pas de concept obscurs ou de séquence de 5.104 + commandes défiant l'imagination, sans aucune corrélation avec 5.105 + <emphasis>ce que vous êtes entrain de faire</emphasis>. En même 5.106 + temps, ces mêmes performances et sa nature 5.107 + <quote>peer-to-peer</quote> vous permettent d'adapter, sans 5.108 + difficulté, son utilisation à de très grands projets. 5.109 </para> 5.110 5.111 - <para id="x_7b">Aucun outil de gestion de source ne peut sauver un projet mal mené, mais un 5.112 -bon outil peut rendre beaucoup plus fluide votre travail. 5.113 + <para id="x_7b">Aucun outil de gestion de source ne peut sauver un 5.114 + projet mal mené, mais un bon outil peut rendre beaucoup plus fluide 5.115 + votre travail. 5.116 </para> 5.117 5.118 </sect2> 5.119 @@ -105,19 +111,21 @@ 5.120 <sect2> 5.121 <title>Les multiples noms de la gestion de source</title> 5.122 5.123 - <para id="x_7c">La gestion de source<!-- 5.124 - TODO:<footnote><J'ai utilisé systématiquement le terme 5.125 -<quote>gestion de source</quote> à travers tout l'ouvrage. Ce n'est pas forcement la 5.126 -meilleure traduction, et ceci peut rendre la lecture un peu lourde, mais je 5.127 -pense que le document y gagne en clarté et en précision. --> est un domaine 5.128 -divers, tellement qu'il n'existe pas une seul nom ou acronyme pour le désigner. 5.129 -Voilà quelqu'uns des noms ou 5.130 -acronymes que vous rencontrerez le plus souvent <!-- TODO:<footnote> J'ai conservé la 5.131 -liste des noms en anglais pour des raisons de commodité (ils sont plus 5.132 -<quote>googelable</quote>). En outre, j'ai opté pour conserver l'ensemble des opérations de 5.133 -Mercurial (\textit{commit},\textit{push}, \textit{pull},...) en anglais, là 5.134 -aussi pour faciliter la lecture d'autres documents en anglais, ainsi que 5.135 -l'utilisation de Mercurial. --> 5.136 + <para id="x_7c">La gestion de source 5.137 + <!-- TODO:<footnote><J'ai utilisé systématiquement le terme 5.138 + <quote>gestion de source</quote> à travers tout l'ouvrage. Ce 5.139 + n'est pas forcement la meilleure traduction, et ceci peut rendre 5.140 + la lecture un peu lourde, mais je pense que le document y gagne 5.141 + en clarté et en précision. --> 5.142 + est un domaine tellement large qu'il n'existe pas qu'un seul nom ou 5.143 + acronyme pour le désigner. Voici quelques noms ou acronymes que vous 5.144 + rencontrerez le plus souvent. 5.145 + <!-- TODO:<footnote> J'ai conservé la liste des noms en anglais pour 5.146 + des raisons de commodité (ils sont plus <quote>googelable</quote>). 5.147 + En outre, j'ai opté pour conserver l'ensemble des opérations de 5.148 + Mercurial (\textit{commit},\textit{push}, \textit{pull},...) en 5.149 + anglais, là aussi pour faciliter la lecture d'autres documents en 5.150 + anglais, ainsi que l'utilisation de Mercurial. --> 5.151 </para> 5.152 5.153 <para>: 5.154 @@ -125,58 +133,60 @@ 5.155 5.156 <itemizedlist> 5.157 <listitem><para id="x_7d">Revision control (RCS)</para></listitem> 5.158 - <listitem><para id="x_7e">Software configuration management (SCM), or 5.159 + <listitem><para id="x_7e">Software configuration management (SCM), ou 5.160 configuration management</para></listitem> 5.161 <listitem><para id="x_7f">Source code management</para></listitem> 5.162 - <listitem><para id="x_80">Source code control, or source 5.163 - control</para></listitem> 5.164 - <listitem><para id="x_81">Version control 5.165 - (VCS)</para></listitem></itemizedlist> 5.166 - 5.167 - <para id="x_82">Certaines personnes prétendent que ces termes ont en fait des sens 5.168 -différents mais en pratique ils se recouvrent tellement qu'il n'y a pas 5.169 -réellement de manière pertinente de les distinguer. 5.170 -</para> 5.171 + <listitem><para id="x_80">Source code control, ou source control</para></listitem> 5.172 + <listitem><para id="x_81">Version control (VCS)</para></listitem></itemizedlist> 5.173 + 5.174 + <para id="x_82">Certaines personnes prétendent que ces termes ont en fait 5.175 + des sens différents mais en pratique ils se recouvrent tellement qu'il n'y 5.176 + a pas réellement de manière pertinente de les distinguer. </para> 5.177 5.178 </sect2> 5.179 </sect1> 5.180 5.181 <sect1> 5.182 5.183 -<title>About the examples in this book</title> 5.184 - 5.185 - <para id="x_84">This book takes an unusual approach to code samples. Every 5.186 - example is <quote>live</quote>&emdash;each one is actually the result 5.187 - of a shell script that executes the Mercurial commands you see. 5.188 - Every time an image of the book is built from its sources, all 5.189 - the example scripts are automatically run, and their current 5.190 - results compared against their expected results.</para> 5.191 - 5.192 - <para id="x_85">The advantage of this approach is that the examples are 5.193 - always accurate; they describe <emphasis>exactly</emphasis> the 5.194 - behavior of the version of Mercurial that's mentioned at the 5.195 - front of the book. If I update the version of Mercurial that 5.196 - I'm documenting, and the output of some command changes, the 5.197 - build fails.</para> 5.198 - 5.199 - <para id="x_86">There is a small disadvantage to this approach, which is 5.200 - that the dates and times you'll see in examples tend to be 5.201 - <quote>squashed</quote> together in a way that they wouldn't be 5.202 - if the same commands were being typed by a human. Where a human 5.203 - can issue no more than one command every few seconds, with any 5.204 - resulting timestamps correspondingly spread out, my automated 5.205 - example scripts run many commands in one second.</para> 5.206 - 5.207 - <para id="x_87">As an instance of this, several consecutive commits in an 5.208 - example can show up as having occurred during the same second. 5.209 - You can see this occur in the <literal 5.210 - role="hg-ext">bisect</literal> example in <xref 5.211 - linkend="sec:undo:bisect"/>, for instance.</para> 5.212 - 5.213 - <para id="x_88">So when you're reading examples, don't place too much weight 5.214 - on the dates or times you see in the output of commands. But 5.215 - <emphasis>do</emphasis> be confident that the behavior you're 5.216 - seeing is consistent and reproducible.</para> 5.217 +<title>A propos des exemples dans ce livre</title> 5.218 + 5.219 + <para id="x_84">Ce livre prend une approche non usuel pour les exemples 5.220 + de code. Tous les exemples sont en <quote>live</quote> &emdash; Chacun 5.221 + est actuellement le résultat d'un script shell qui exécute les 5.222 + commandes Mercurial que vous voyez. A chaque fois qu'une image du livre 5.223 + est construite à partir des sources, tous les scripts d'exemple sont 5.224 + lancés automatiquement, et leurs résultats effectifs sont comparés aux 5.225 + résultats attendus.</para> 5.226 + 5.227 + <para id="x_85">L'avantage de dette approche est que les exemples sont 5.228 + toujours précis ; ils décrivent <emphasis>exactement</emphasis> la 5.229 + conduite de la version de Mercurial qui est mentionnée en entête du 5.230 + livre. Si je met à jour la version de Mercurial que je suis en train de 5.231 + documenter, et que la sortie de certaines commandes change, la 5.232 + construction du livre échoue.</para> 5.233 + 5.234 + <para id="x_86"> 5.235 + Il existe un petit désavantage à cette approche qui est que les dates et 5.236 + heures que vous verrez dans les exemples tendent à être 5.237 + <quote>écrasés</quote> ensemble, dans le sens où elles ne sont pas 5.238 + celles qu'elles auraient été si un humain avait tapé les commandes. En 5.239 + effet, humain ne peut pas taper plus d'une commande toutes les quelques 5.240 + secondes, avec le temps qui s'écoule, mes scripts d'exemples exécutent 5.241 + plusieurs commandes en une seconde. 5.242 + </para> 5.243 + 5.244 + <para id="x_87">Une circonstance de ceci est que plusieurs commits 5.245 + consécutifs dans un exemple peuvent apparaître comme ayant eu lieu 5.246 + durant la même seconde. 5.247 + Vous pouvez observer le phénomène dans l'exemple <literal 5.248 + role="hg-ext">bisect</literal> dans <xref linkend="sec:undo:bisect"/> 5.249 + </para> 5.250 + 5.251 + <para id="x_88">Donc, lorsque vous lisez ces exemples, ne prêtez pas trop 5.252 + d'importance aux dates et heures que vous voyez dans la sortie des 5.253 + commandes. Cependant, <emphasis>soyez</emphasis> confiants que le 5.254 + comportement que vous voyez est consistent et reproductible 5.255 + </para> 5.256 5.257 </sect1> 5.258 5.259 @@ -185,604 +195,657 @@ 5.260 <sect1> 5.261 <title>Tendances de la gestion de source</title> 5.262 5.263 - <para id="x_89">Il y a eu une tendance évidente dans le développement et l'utilisation d'outils 5.264 -de gestion de source depuis les quatre dernières décades, au fur et à mesure 5.265 -que les utilisateurs se sont habitués à leur outils et se sont sentis contraints 5.266 -par leurs limitations. 5.267 -</para> 5.268 - 5.269 - <para id="x_8a">La première génération commença simplement par gérer un fichier unique sur un 5.270 -ordinateur individuel. Cependant, même si ces outils présentaient une grande 5.271 -avancée par rapport à la gestion manuelle des versions, leur modèle de 5.272 -verrouillage et leur utilisation limitée à un seul ordinateur rendaient leur 5.273 -utilisation possible uniquement dans une très petite équipe. 5.274 -</para> 5.275 - 5.276 - <para id="x_8b">La seconde génération a assoupli ces contraintes en adoptant une architecture 5.277 -réseau et centralisée, permettant de gérer plusieurs projets entiers en même 5.278 -temps. Alors que les projets grandirent en taille, ils rencontrèrent de nouveaux 5.279 -problèmes. Avec les clients discutant régulièrement avec le serveurs, la montée 5.280 -en charge devint un réel problème sur les gros projets. Une connexion réseau 5.281 -peu fiable pouvait complètement empêcher les utilisateurs distants de dialoguer 5.282 -avec le serveur. Alors que les projets <emphasis remap="it">Open Source</emphasis> commencèrent à 5.283 -mettre en place des accès en lecture seule disponible anonymement, les 5.284 -utilisateurs sans les privilèges de <quote>commit</quote> réalisèrent qu'ils ne pouvaient 5.285 -pas utiliser les outils pour collaborer naturellement avec le projet, comme ils 5.286 -ne pouvaient pas non plus enregistrer leurs modifications. 5.287 -</para> 5.288 - 5.289 - <para id="x_8c">La génération actuelle des outils de gestion de source est <quote>peer-to-peer</quote> par 5.290 -nature. Tout ces systèmes ont abandonné la dépendance à un serveur central, et 5.291 -ont permis à leur utilisateur de distribuer les données de leur gestion de 5.292 -source à qui en a besoin. La collaboration à travers Internet a transformé la 5.293 -contrainte technologique en une simple question de choix et de consencus. Les 5.294 -outils modernes peuvent maintenant fonctionner en mode déconnecté sans limite et 5.295 -de manière autonome, la connexion au réseau n'étant nécessaire que pour 5.296 -synchroniser les modifications avec les autres dépôts. 5.297 -</para> 5.298 - 5.299 + <para id="x_89">Il y a eu une tendance évidente dans le développement et 5.300 + l'utilisation d'outils de gestion de source depuis les quatre dernières 5.301 + décades, au fur et à mesure que les utilisateurs se sont habitués à 5.302 + leur outils et se sont sentis contraints par leurs limitations. 5.303 + </para> 5.304 + 5.305 + <para id="x_8a">La première génération commença simplement par gérer un 5.306 + fichier unique sur un ordinateur individuel. Cependant, même si ces 5.307 + outils présentaient une grande avancée par rapport à la gestion 5.308 + manuelle des versions, leur modèle de verrouillage et leur utilisation 5.309 + limitée à un seul ordinateur rendaient leur utilisation possible 5.310 + uniquement dans une très petite équipe. 5.311 + </para> 5.312 + 5.313 + <para id="x_8b">La seconde génération a assoupli ces contraintes en 5.314 + adoptant une architecture réseau et centralisée, permettant de gérer 5.315 + plusieurs projets entiers en même temps. Alors que les projets 5.316 + grandirent en taille, ils rencontrèrent de nouveaux problèmes. Avec les 5.317 + clients discutant régulièrement avec le serveurs, la montée en charge 5.318 + devint un réel problème sur les gros projets. Une connexion réseau peu 5.319 + fiable pouvait complètement empêcher les utilisateurs distants de 5.320 + dialoguer avec le serveur. Alors que les projets <emphasis 5.321 + remap="it">Open Source</emphasis> commencèrent à mettre en place des 5.322 + accès en lecture seule disponible anonymement, les utilisateurs sans 5.323 + les privilèges de <quote>commit</quote> réalisèrent qu'ils ne pouvaient 5.324 + pas utiliser les outils pour collaborer naturellement avec le projet, 5.325 + comme ils ne pouvaient pas non plus enregistrer leurs modifications. 5.326 + </para> 5.327 + 5.328 + <para id="x_8c">La génération actuelle des outils de gestion de source 5.329 + est <quote>peer-to-peer</quote> par nature. Tous ces systèmes ont 5.330 + abandonné la dépendance à un serveur central, et ont permis à leur 5.331 + utilisateur de distribuer les données de leur gestion de source à qui 5.332 + en a besoin. La collaboration à travers Internet a transformé la 5.333 + contrainte technologique en une simple question de choix et de 5.334 + consensus. Les outils modernes peuvent maintenant fonctionner en mode 5.335 + déconnecté sans limite et de manière autonome, la connexion au réseau 5.336 + n'étant nécessaire que pour synchroniser les modifications avec les 5.337 + autres dépôts. 5.338 + </para> 5.339 </sect1> 5.340 + 5.341 <sect1> 5.342 <title>Quelques avantages des gestionnaires de source distribués</title> 5.343 - 5.344 -<para id="x_8d">Même si les gestionnaire de source distribués sont depuis plusieurs années 5.345 -assez robustes et aussi utilisables que leurs prédécesseurs, les utilisateurs 5.346 -d'autres outils n'y ont pas encore été sensibilisés. Les gestionnaires 5.347 -de source distribués se distinguent particulièrement de leurs équivalents 5.348 -centralisés de nombreuses manières. 5.349 -</para> 5.350 - 5.351 - <para id="x_8e">Pour un développeur individuel, ils restent beaucoup plus rapides que les 5.352 -outils centralisés. Cela pour une raison simple : un outil centralisé doit 5.353 -toujours dialoguer à travers le réseau pour la plupart des opérations, car 5.354 -presque toutes les métadonnées sont stockées sur la seule copie du serveur 5.355 -central. Un outil distribué stocke toute ses métadonnées localement. À tâche 5.356 -égale, effectuer un échange avec le réseau ajoute un délai aux outils 5.357 -centralisés. Ne sous-estimez pas la valeur d'un outil rapide : vous allez 5.358 -passer beaucoup de temps à interagir avec un logiciel de gestion de source. 5.359 -</para> 5.360 - 5.361 - <para id="x_8f">Les outils distribués sont complètement indépendants des aléas de votre serveur, 5.362 -d'autant plus qu'ils répliquent les métadonnées à beaucoup d'endroits. Si 5.363 -votre serveur central prend feu, vous avez intérêt à ce que les médias de 5.364 -sauvegardes soient fiables, et que votre dernier <quote>backup</quote> soit récent et 5.365 -fonctionne sans problème. Avec un outil distribué, vous avez autant de 5.366 -<quote>backup</quote> que de contributeurs. 5.367 -</para> 5.368 - 5.369 - <para id="x_90">En outre, la fiabilité de votre réseau affectera beaucoup moins les 5.370 -outils distribués. Vous ne pouvez même pas utiliser un outil centralisé 5.371 -sans connexion réseau, à l'exception de quelques commandes, très limitées. 5.372 -Avec un outil distribué, si votre connexion réseau tombe pendant que vous 5.373 -travaillez, vous pouvez ne même pas vous en rendre compte. La seule chose 5.374 -que vous ne serez pas capable de faire sera de communiquer avec des dépôts 5.375 -distants, opération somme toute assez rare en comparaison aux opérations 5.376 -locales. Si vous avez une équipe de collaborateurs très dispersée ceci peut 5.377 -être significatif. 5.378 -</para> 5.379 - 5.380 + 5.381 + <para id="x_8d">Même si les gestionnaire de source distribués sont depuis 5.382 + plusieurs années assez robustes et aussi utilisables que leurs 5.383 + prédécesseurs, les utilisateurs d'autres outils n'y ont pas encore été 5.384 + sensibilisés. Les gestionnaires de source distribués se distinguent 5.385 + particulièrement de leurs équivalents centralisés de nombreuses 5.386 + manières. 5.387 + </para> 5.388 + 5.389 + <para id="x_8e">Pour un développeur individuel, ils restent beaucoup plus 5.390 + rapides que les outils centralisés. Cela pour une raison simple : un 5.391 + outil centralisé doit toujours dialoguer à travers le réseau pour la 5.392 + plupart des opérations, car presque toutes les métadonnées sont 5.393 + stockées sur la seule copie du serveur central. Un outil distribué 5.394 + stocke toute ses métadonnées localement. À tâche égale, effectuer un 5.395 + échange avec le réseau ajoute un délai aux outils centralisés. Ne 5.396 + sous-estimez pas la valeur d'un outil rapide : vous allez passer 5.397 + beaucoup de temps à interagir avec un logiciel de gestion de source. 5.398 + </para> 5.399 + 5.400 + <para id="x_8f">Les outils distribués sont complètement indépendants des 5.401 + aléas de votre serveur, d'autant plus qu'ils répliquent les métadonnées 5.402 + à beaucoup d'endroits. Si votre serveur central prend feu, vous avez 5.403 + intérêt à ce que les médias de sauvegardes soient fiables, et que votre 5.404 + dernier <quote>backup</quote> soit récent et fonctionne sans problème. 5.405 + Avec un outil distribué, vous avez autant de <quote>backup</quote> que 5.406 + de contributeurs. 5.407 + </para> 5.408 + 5.409 + <para id="x_90">En outre, la fiabilité de votre réseau affectera beaucoup 5.410 + moins les outils distribués. Vous ne pouvez même pas utiliser un outil 5.411 + centralisé sans connexion réseau, à l'exception de quelques commandes, 5.412 + très limitées. Avec un outil distribué, si votre connexion réseau tombe 5.413 + pendant que vous travaillez, vous pouvez ne même pas vous en rendre 5.414 + compte. La seule chose que vous ne serez pas capable de faire sera de 5.415 + communiquer avec des dépôts distants, opération somme toute assez rare 5.416 + en comparaison aux opérations locales. Si vous avez une équipe de 5.417 + collaborateurs très dispersée ceci peut être significatif. 5.418 + </para> 5.419 5.420 <sect2> 5.421 <title>Avantages pour les projets Open Source</title> 5.422 5.423 - <para id="x_91">Si vous prenez goût à un projet <emphasis remap="it">Open Source</emphasis> et que vous 5.424 -décidez de commencer à toucher à son code, et que le projet utilise 5.425 -un gestionnaire de source distribué, vous êtes immédiatement un "pair" 5.426 -avec les personnes formant le <quote>cœur</quote> du projet. Si ils publient 5.427 -leurs dépôts, vous pouvez immédiatement copier leurs historiques de 5.428 -projet, faire des modifications, enregistrer votre travail en utilisant 5.429 -les même outils qu'eux. Par comparaison, avec un outil centralisé, vous 5.430 -devez utiliser un logiciel en mode <quote>lecture seule</quote> à moins que 5.431 -quelqu'un ne vous donne les privilèges de <quote>commit</quote> sur le serveur 5.432 -central. Avant ça, vous ne serez pas capable d'enregistrer vos 5.433 -modifications, et vos propres modifications risqueront de se 5.434 -corrompre chaque fois que vous essayerez de mettre à jour à votre 5.435 -espace de travail avec le serveur central. 5.436 -</para> 5.437 - 5.438 - <sect3> 5.439 - <title>Le non-problème du "fork"</title> 5.440 - 5.441 - <para id="x_92">Il a été souvent suggéré que les gestionnaires de source distribués 5.442 -posent un risque pour les projets <emphasis remap="it">Open Source</emphasis> car ils 5.443 -facilitent grandement la création de <quote>fork</quote>.<!-- footnote{NdT:Création 5.444 -d'une 5.445 -<ulink url="version alternative du logiciel">version alternative du 5.446 -logiciel</ulink>{http://fr.wikipedia.org/wiki/Fork#Embranchement_d.27un_projet_informatique} 5.447 ---> 5.448 -Un <quote>fork</quote> apparait quand il y des divergences d'opinion ou d'attitude 5.449 -au sein d'un groupe de développeurs qui aboutissent à la décision de ne 5.450 -plus travailler ensemble. Chaque parti s'empare d'une copie plus ou moins 5.451 -complète du code source du projet et continue dans sa propre direction. 5.452 -</para> 5.453 - 5.454 - <para id="x_93">Parfois ces différents partis décident de se réconcilier. Avec un 5.455 -serveur central, l'aspect <emphasis>technique</emphasis> de cette réconciliation 5.456 -est un processus douloureux, et essentiellement manuel. Vous devez 5.457 -décider quelle modification est <quote>la gagnante</quote>, et replacer, par un 5.458 -moyen ou un autre, les modifications de l'autre équipe dans l'arborescence 5.459 -du projet. Ceci implique généralement la perte d'une partie de l'historique 5.460 -d'un des partis, ou même des deux. 5.461 -</para> 5.462 - 5.463 - <para id="x_94">Ce que les outils distribués permettent à ce sujet est probablement 5.464 -la <emphasis>meilleure</emphasis> façon de développer un projet. Chaque modification 5.465 -que vous effectuez est potentiellement un <quote>fork</quote>. La grande force de 5.466 -cette approche est que les gestionnaires de source distribués doivent être 5.467 -vraiment très efficaces pour <emphasis>fusionner</emphasis><!-- TODO footnote{NdT:j'ai choisi de 5.468 -traduire ici <emphasis remap="it">merging</emphasis> par <quote>fusionner</quote> pour des raisons 5.469 -de clarté} --> des <quote>forks</quote>, car les <quote>forks</quote>, dans ce contexte, arrivent 5.470 -tout le temps.</para> 5.471 - 5.472 - <para id="x_95">Si chaque altération que n'importe qui effectue, à tout moment, est vue 5.473 -comme un <quote>fork</quote> à fusionner, alors ce que le monde de 5.474 -l'<emphasis remap="it">Open Source</emphasis> 5.475 -Source} voit comme un <quote>fork</quote> devient <emphasis>uniquement</emphasis> une problématique 5.476 -sociale. En fait, les outils de gestions de source distribués <emphasis>réduisent</emphasis> 5.477 -les chances de <quote>fork</quote>: 5.478 -</para> 5.479 -<itemizedlist> 5.480 - <listitem> 5.481 - <para>Ils éliminent la distinction sociale qu'imposent les outils centralisés 5.482 - entre les membres du projets (ceux qui ont accès au <quote>commit</quote>) et ceux de 5.483 - l'extérieur (ce qui ne l'ont pas).</para> 5.484 - <para>rendent plus facile la réconciliation après un <quote>fork</quote> social, car tout ce 5.485 - qu'elle implique est une simple fusion.</para> 5.486 - </listitem> 5.487 -</itemizedlist> 5.488 - 5.489 - <para id="x_98">Certaines personnes font de la résistance envers les gestionnaires de source 5.490 -distribués parce qu'ils veulent garder un contrôle ferme sur leur projet, et 5.491 -ils pensent que les outils centralisés leur fournissent ce contrôle. Néanmoins, 5.492 -si c'est votre cas, sachez que si vous publiez votre dépôt CVS ou Subversion 5.493 -de manière publique, il existe une quantité d'outils disponibles pour récupérer 5.494 -entièrement votre projet et son historique (quoique lentement) et le récréer 5.495 -ailleurs, sans votre contrôle. En fait, votre contrôle sur votre projet est 5.496 -illusoire, vous ne faites qu'interdire à vos collaborateurs de travailler 5.497 -de manière fluide, en disposant d'un miroir ou d'un <quote>fork</quote> de votre 5.498 -historique. 5.499 -%%%TODO: Fussy, those last sentences are not really well translated: 5.500 -%%%no problem for me (wilk) 5.501 -%However, if you're of this belief, and you publish your CVS or Subversion 5.502 -%repositories publically, there are plenty of tools available that can pull 5.503 -%out your entire project's history (albeit slowly) and recreate it somewhere 5.504 -%that you don't control. So while your control in this case is illusory, you are 5.505 -%forgoing the ability to fluidly collaborate with whatever people feel 5.506 -%compelled to mirror and fork your history. 5.507 -</para> 5.508 - 5.509 - </sect3> 5.510 + <para id="x_91">Si vous prenez goût à un projet <emphasis 5.511 + remap="it">Open Source</emphasis> et que vous décidez de commencer 5.512 + à toucher à son code, et que le projet utilise un gestionnaire de 5.513 + source distribué, vous êtes immédiatement un "pair" avec les 5.514 + personnes formant le <quote>cœur</quote> du projet. S'ils publient 5.515 + leurs dépôts, vous pouvez immédiatement copier leurs historiques de 5.516 + projet, faire des modifications, enregistrer votre travail en 5.517 + utilisant les mêmes outils qu'eux. Par comparaison avec un outil 5.518 + centralisé, vous devez utiliser un logiciel en mode <quote>lecture 5.519 + seule</quote> à moins que quelqu'un ne vous donne les privilèges de 5.520 + <quote>commit</quote> sur le serveur central. Avant ça, vous ne serez 5.521 + pas capable d'enregistrer vos modifications, et vos propres 5.522 + modifications risqueront de se corrompre chaque fois que vous 5.523 + essayerez de mettre à jour à votre espace de travail avec le serveur 5.524 + central. 5.525 + </para> 5.526 + 5.527 + <sect3> 5.528 + <title>Le non-problème du "fork"</title> 5.529 + 5.530 + <para id="x_92">Il a été souvent suggéré que les gestionnaires de 5.531 + source distribués posent un risque pour les projets <emphasis 5.532 + remap="it">Open Source</emphasis> car ils facilitent grandement la 5.533 + création de <quote>fork</quote>. 5.534 + <!--footnote{NdT:Création d'une <ulink url="version alternative du 5.535 + logiciel">version alternative du 5.536 + logiciel</ulink>{http://fr.wikipedia.org/wiki/Fork#Embranchement_d.27un_projet_informatique} 5.537 + --> 5.538 + Un <quote>fork</quote> apparait quand il y des divergences d'opinion 5.539 + ou d'attitude au sein d'un groupe de développeurs qui aboutissent à 5.540 + la décision de ne plus travailler ensemble. Chaque parti s'empare 5.541 + d'une copie plus ou moins complète du code source du projet et 5.542 + continue dans sa propre direction. 5.543 + </para> 5.544 + 5.545 + 5.546 + <para id="x_93">Parfois ces différents partis décident de se 5.547 + réconcilier. Avec un serveur central, l'aspect 5.548 + <emphasis>technique</emphasis> de cette réconciliation est un 5.549 + processus douloureux, et essentiellement manuel. Vous devez décider 5.550 + quelle modification est <quote>la gagnante</quote>, et replacer, par 5.551 + un moyen ou un autre, les modifications de l'autre équipe dans 5.552 + l'arborescence du projet. Ceci implique généralement la perte d'une 5.553 + partie de l'historique d'un des partis, ou même des deux. 5.554 + </para> 5.555 + 5.556 + <para id="x_94">Ce que les outils distribués permettent à ce sujet est 5.557 + probablement la <emphasis>meilleure</emphasis> façon de développer un 5.558 + projet. Chaque modification que vous effectuez est potentiellement un 5.559 + <quote>fork</quote>. La grande force de cette approche est que les 5.560 + gestionnaires de source distribués doivent être vraiment très 5.561 + efficaces pour <emphasis>fusionner (merge)</emphasis> 5.562 + <!-- TODO footnote{NdT:j'ai choisi de traduire ici <emphasis 5.563 + remap="it">merging</emphasis> par <quote>fusionner</quote> pour des 5.564 + raisons de clarté} --> 5.565 + des <quote>forks</quote>, car les <quote>forks</quote>, dans ce 5.566 + contexte, arrivent tout le temps. 5.567 + </para> 5.568 + 5.569 + <para id="x_95">Si chaque altération que n'importe qui effectue, à tout 5.570 + moment, est vue comme un <quote>fork</quote> à fusionner, alors ce 5.571 + que le monde de l'<emphasis remap="it">Open Source</emphasis> voit 5.572 + comme un <quote>fork</quote> devient <emphasis>uniquement</emphasis> 5.573 + une problématique sociale. En fait, les outils de gestions de source 5.574 + distribués <emphasis>réduisent</emphasis> les chances de 5.575 + <quote>fork</quote> : 5.576 + </para> 5.577 + 5.578 + <itemizedlist> 5.579 + <listitem> 5.580 + <para>Ils éliminent la distinction sociale qu'imposent les outils 5.581 + centralisés entre les membres du projets (ceux qui ont accès au 5.582 + <quote>commit</quote>) et ceux de l'extérieur (ce qui ne l'ont 5.583 + pas). 5.584 + </para> 5.585 + <para>Ils rendent plus facile la réconciliation après un 5.586 + <quote>fork</quote> social, car tout ce qu'elle implique est une 5.587 + simple fusion. 5.588 + </para> 5.589 + </listitem> 5.590 + </itemizedlist> 5.591 + 5.592 + <para id="x_98">Certaines personnes font de la résistance envers les 5.593 + gestionnaires de source distribués parce qu'ils veulent garder un 5.594 + contrôle ferme sur leur projet, et ils pensent que les outils 5.595 + centralisés leur fournissent ce contrôle. Néanmoins, si c'est votre 5.596 + cas, sachez que si vous publiez votre dépôt CVS ou Subversion de 5.597 + manière publique, il existe une quantité d'outils disponibles pour 5.598 + récupérer entièrement votre projet et son historique (quoique 5.599 + lentement) et le récréer ailleurs, sans votre contrôle. En fait, 5.600 + votre contrôle sur votre projet est illusoire, vous ne faites 5.601 + qu'interdire à vos collaborateurs de travailler de manière fluide, en 5.602 + disposant d'un miroir ou d'un <quote>fork</quote> de votre 5.603 + historique. 5.604 + </para> 5.605 + 5.606 + </sect3> 5.607 </sect2> 5.608 <sect2> 5.609 <title>Avantages pour les projets commerciaux</title> 5.610 5.611 - <para id="x_99">Beaucoup de projets commerciaux sont réalisés par des équipes éparpillées 5.612 -à travers le globe. Les contributeurs qui sont loin du serveur central 5.613 -devront subir des commandes lentes et même parfois peu fiables. Les 5.614 -solutions propriétaires de gestion de source tentent de palier ce problème 5.615 -avec des réplications de sites distants qui sont à la fois coûteuses à mettre 5.616 -en place et lourdes à administrer. Un système distribué ne souffre pas 5.617 -de ce genre de problèmes. En outre, il est très aisé de mettre en place 5.618 -plusieurs serveurs de références, disons un par site, de manière à ce qu'il 5.619 -n'y ait pas de communication redondante entre les dépôts, sur une connexion 5.620 -longue distance souvent onéreuse. 5.621 -</para> 5.622 - 5.623 - <para id="x_9a">Les systèmes de gestion de source supportent généralement assez mal la 5.624 -montée en charge. Ce n'est pas rare pour un gestionnaire de source centralisé 5.625 -pourtant onéreux de s'effondrer sous la charge combinée d'une douzaine 5.626 -d'utilisateurs concurrents seulement. Une fois encore, la réponse à cette problématique 5.627 -est généralement encore la mise en place d'un ensemble complexe de serveurs 5.628 -synchronisés par un mécanisme de réplication. Dans le cas d'un gestionnaire 5.629 -de source distribué, la charge du serveur central &emdash; si vous avez un&emdash; est 5.630 -plusieurs fois inférieure (car toutes les données sont déjà répliquées ailleurs), 5.631 -un simple serveur, pas très cher, peut gérer les besoins d'une plus grande 5.632 -équipe, et la réplication pour balancer la charge devient le 5.633 -travail d'un simple script. 5.634 -</para> 5.635 - 5.636 - <para id="x_9b">Si vous avez des employés sur le terrain, en train de chercher à résoudre un souci sur 5.637 -le site d'un client, ils bénéficieront aussi d'un gestionnaire de source 5.638 -distribué. Cet outil leur permettra de générer des versions personnalisées, 5.639 -d'essayer différentes solutions, en les isolant aisément les unes des autres, 5.640 -et de rechercher efficacement à travers l'historique des sources, la cause 5.641 -des bugs ou des régressions, tout ceci sans avoir besoin de la moindre 5.642 -connexion au réseau de votre compagnie. 5.643 -</para> 5.644 + <para id="x_99">Beaucoup de projets commerciaux sont réalisés par des 5.645 + équipes éparpillées à travers le globe. Les contributeurs qui sont 5.646 + loin du serveur central devront subir des commandes lentes et même 5.647 + parfois peu fiables. Les solutions propriétaires de gestion de source 5.648 + tentent de palier ce problème avec des réplications de sites distants 5.649 + qui sont à la fois coûteuses à mettre en place et lourdes à 5.650 + administrer. Un système distribué ne souffre pas de ce genre de 5.651 + problèmes. En outre, il est très aisé de mettre en place plusieurs 5.652 + serveurs de références, disons un par site, de manière à ce qu'il n'y 5.653 + ait pas de communication redondante entre les dépôts, sur une 5.654 + connexion longue distance souvent onéreuse. 5.655 + </para> 5.656 + 5.657 + <para id="x_9a">Les systèmes de gestion de source supportent 5.658 + généralement assez mal la monté en charge. Il n'est pas rare pour un 5.659 + gestionnaire de source centralisé pourtant onéreux de s'effondrer 5.660 + sous la charge combinée d'une douzaine d'utilisateurs concurrents 5.661 + seulement. Une fois encore, la réponse à cette problématique est 5.662 + généralement encore la mise en place d'un ensemble complexe de 5.663 + serveurs synchronisés par un mécanisme de réplication. Dans le cas 5.664 + d'un gestionnaire de source distribué, la charge du serveur central 5.665 + &emdash; si vous avez un&emdash; est plusieurs fois inférieure (car 5.666 + toutes les données sont déjà répliquées ailleurs), un simple serveur, 5.667 + pas très cher, peut gérer les besoins d'une plus grande équipe, et la 5.668 + réplication pour balancer la charge devient le travail d'un simple 5.669 + script. 5.670 + </para> 5.671 + 5.672 + <para id="x_9b">Si vous avez des employés sur le terrain, en train de 5.673 + chercher à résoudre un souci sur le site d'un client, ils 5.674 + bénéficieront aussi d'un gestionnaire de source distribué. Cet outil 5.675 + leur permettra de générer des versions personnalisées, d'essayer 5.676 + différentes solutions, en les isolant aisément les unes des autres, 5.677 + et de rechercher efficacement à travers l'historique des sources, la 5.678 + cause des bugs ou des régressions, tout ceci sans avoir besoin de la 5.679 + moindre connexion au réseau de votre compagnie. 5.680 + </para> 5.681 5.682 </sect2> 5.683 - </sect1> 5.684 - <sect1> 5.685 - <title>Pourquoi choisir Mercurial?</title> 5.686 - 5.687 - <para id="x_9c">Mercurial a plusieurs caractéristiques qui en font un choix particulièrement 5.688 -pertinent pour la gestion de source: 5.689 -</para> 5.690 + </sect1> 5.691 + <sect1> 5.692 + <title>Pourquoi choisir Mercurial?</title> 5.693 + 5.694 + <para id="x_9c">Mercurial a plusieurs caractéristiques qui en font un 5.695 + choix particulièrement pertinent pour la gestion de source : 5.696 + </para> 5.697 <itemizedlist> 5.698 - <listitem><para id="x_9d">It is easy to learn and use.</para></listitem> 5.699 - <listitem><para id="x_9e">It is lightweight.</para></listitem> 5.700 - <listitem><para id="x_9f">It scales excellently.</para></listitem> 5.701 - <listitem><para id="x_a0">It is easy to 5.702 - customise.</para></listitem></itemizedlist> 5.703 - 5.704 - <para id="x_a1">Si vous êtes déjà familier d'un outil de gestion de source, vous serez 5.705 -capable de l'utiliser en moins de 5 minutes. Sinon, ça ne sera pas beaucoup 5.706 -plus long. 5.707 -Les commandes utilisées par Mercurial, comme ses fonctionnalités, sont 5.708 -généralement uniformes et cohérentes, et vous pouvez donc ainsi garder en tête 5.709 -simplement quelques règles générales, plutôt qu'un lot complexe d'exceptions. 5.710 -</para> 5.711 - 5.712 - <para id="x_a2">Sur un petit projet, vous pouvez commencer à travailler avec Mercurial en 5.713 -quelques instants. Ajouter des modifications ou des branches, transférer 5.714 -ces modifications (localement ou via le réseau), et les opérations 5.715 -d'historique ou de statut sont aussi très rapides. Mercurial reste hors de 5.716 -votre chemin grâce à sa simplicité d'utilisation et sa rapidité d'exécution. 5.717 -</para> 5.718 - 5.719 - <para id="x_a3">L'utilité de Mercurial ne se limite pas à de petits projets: il est 5.720 -aussi utilisé par des projets ayant des centaines ou même des milliers 5.721 -de contributeurs, avec plusieurs dizaines de milliers de fichiers, et des 5.722 -centaines de méga de code source. 5.723 -</para> 5.724 - 5.725 - <para id="x_a4">Si les fonctionnalités cœur de Mercurial ne sont pas suffisantes pour vous, 5.726 -il est très aisé d'en construire d'autres. Mercurial est adapté à l'utilisation 5.727 -de scripts, et son implémentation interne en Python, propre et claire, 5.728 -rend encore plus facile l'ajout de fonctionnalités sous forme d'extensions. Il 5.729 -en existe déjà un certain nombre de très populaires et très utiles, 5.730 -dont le périmètre va de la recherche de bugs à l'amélioration des performances. 5.731 -</para> 5.732 + <listitem><para id="x_9d">Il est simple à apprendre et à utiliser.</para></listitem> 5.733 + <listitem><para id="x_9e">Il est léger.</para></listitem> 5.734 + <listitem><para id="x_9f">Il s'adapte très bien à la charge.</para></listitem> 5.735 + <listitem><para id="x_a0">Il se personnalise facilement.</para></listitem> 5.736 + </itemizedlist> 5.737 + 5.738 + <para id="x_a1">Si vous êtes déjà familier d'un outil de gestion de 5.739 + source, vous serez capable de l'utiliser en moins de 5 minutes. Sinon, 5.740 + ça ne sera pas beaucoup plus long. Les commandes utilisées par 5.741 + Mercurial, comme ses fonctionnalités, sont généralement uniformes et 5.742 + cohérentes, et vous pouvez ainsi garder en tête simplement quelques 5.743 + règles générales, plutôt qu'un lot complexe d'exceptions. 5.744 + </para> 5.745 + 5.746 + <para id="x_a2">Sur un petit projet, vous pouvez commencer à travailler 5.747 + avec Mercurial en quelques instants. Ajouter des modifications ou des 5.748 + branches, transférer ces modifications (localement ou via le réseau), 5.749 + et les opérations d'historique ou de statut sont aussi très rapides. 5.750 + Mercurial reste hors de votre chemin grâce à sa simplicité 5.751 + d'utilisation et sa rapidité d'exécution. 5.752 + </para> 5.753 + 5.754 + <para id="x_a3">L'utilité de Mercurial ne se limite pas à de petits 5.755 + projets: il est aussi utilisé par des projets ayant des centaines ou 5.756 + même des milliers de contributeurs, avec plusieurs dizaines de milliers 5.757 + de fichiers, et des centaines de méga octets de code source. 5.758 + </para> 5.759 + 5.760 + <para id="x_a4">Si les fonctionnalités au cœur de Mercurial ne sont pas 5.761 + suffisantes pour vous, il est très aisé d'en construire d'autres. 5.762 + Mercurial est adapté à l'utilisation de scripts, et son implémentation 5.763 + interne en Python, propre et claire, rend encore plus facile l'ajout de 5.764 + fonctionnalités sous forme d'extensions. Il en existe déjà un certain 5.765 + nombre de très populaires et très utiles, dont le périmètre va de la 5.766 + recherche de bugs à l'amélioration des performances. 5.767 + </para> 5.768 5.769 </sect1> 5.770 <sect1> 5.771 <title>Mercurial comparé aux autres outils</title> 5.772 5.773 - <para id="x_a5">Avant que vous n'alliez plus loin, comprenez bien que cette section 5.774 -reflète mes propres expériences, et elle est donc (j'ose le dire) 5.775 -peu objective. Néanmoins, j'ai utilisé les outils de gestion de source 5.776 -listés ci dessous, dans la plupart des cas, pendant plusieurs années. 5.777 -%% TODO: Fussy translation. 5.778 -</para> 5.779 - 5.780 + <para id="x_a5">Avant que vous n'alliez plus loin, comprenez bien que 5.781 + cette section reflète mes propres expériences, et elle est donc (j'ose 5.782 + le dire) peu objective. Néanmoins, j'ai utilisé les outils de gestion 5.783 + de source listés ci dessous, dans la plupart des cas, pendant plusieurs 5.784 + années. 5.785 + </para> 5.786 5.787 <sect2> 5.788 <title>Subversion</title> 5.789 5.790 - <para id="x_a6">Subversion est un des outils de gestion de source les plus populaire, il fût 5.791 -développé pour remplacer CVS. Il a une architecture client/server centralisée. 5.792 -</para> 5.793 - 5.794 - <para id="x_a7">Subversion et Mercurial ont des noms de commandes très similaires pour 5.795 -les mêmes opérations, ainsi si vous êtes familier avec l'un, c'est facile 5.796 -d'apprendre l'autre. Ces deux outils sont portables sur les systèmes 5.797 -d'exploitation les plus populaires 5.798 -</para> 5.799 - 5.800 - <para id="x_a8">Avant la version 1.5, Subversion n'offrait aucune forme de support pour les fusions. Lors 5.801 -de l'écriture de ce livre, ses capacités de fusion étaient nouvelles, et réputées pour être 5.802 -<ulink url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword"> 5.803 -complexes et boguées</ulink>. 5.804 -</para> 5.805 - 5.806 - <para id="x_a9">Mercurial dispose d'un avantage substantiel en terme de performance par rapport à 5.807 -Subversion sur la plupart des opérations que j'ai pu tester. J'ai mesuré 5.808 -une différence de performance allant de deux à six fois plus rapide avec 5.809 -le système de stockage de fichier local de Subversion 1.4.3 5.810 -(<emphasis>ra_local</emphasis>), qui est la méthode d'accès la plus rapide disponible. Dans 5.811 -un déploiement plus réaliste, impliquant un stockage réseau, Subversion 5.812 -serait encore plus désavantagé. Parce que la plupart des commandes Subversion 5.813 -doivent communiquer avec le serveur et que Subversion n'a pas de mécanisme 5.814 -de réplication, la capacité du serveur et la bande passante sont devenues des 5.815 -goulots d'étranglement pour les projets de taille moyenne ou grande. 5.816 -</para> 5.817 - 5.818 - <para id="x_aa">En outre, Subversion implique une surcharge substantielle dans le stockage local 5.819 -de certaines données, pour éviter des transactions avec le serveur, pour 5.820 -certaines opérations communes, telles que la recherche des fichiers modifiés 5.821 -(<literal>status</literal>) et l'affichage des modifications par rapport à la révision 5.822 -courante (<literal>diff</literal>). En conséquence, un répertoire de travail Subversion 5.823 -a souvent la même taille, ou est plus grand, qu'un dépôt Mercurial et son 5.824 -espace de travail, et ceci bien que le dépôt Mercurial contienne l'intégralité 5.825 -de l'historique. 5.826 -</para> 5.827 - 5.828 - <para id="x_ab">Subversion est largement supporté par les outils tierces. Mercurial est 5.829 -actuellement encore en retrait de ce point de vue. L'écart se réduit, néanmoins, 5.830 -et en effet certains des outils graphiques sont maintenant supérieurs à leurs 5.831 -équivalents Subversion. Comme Mercurial, Subversion dispose d'un excellent 5.832 -manuel utilisateur. 5.833 -</para> 5.834 - 5.835 - <para id="x_ac">Parce que Subversion ne stocke pas l'historique chez ses clients, il est 5.836 -parfaitement adapté à la gestion de projets qui doivent suivre un ensemble 5.837 -de larges fichiers binaires et opaques. Si vous suivez une cinquantaine de 5.838 -versions d'un fichier incompressible de 10MB, l'occupation disque coté client 5.839 -d'un projet sous Subversion restera à peu près constante. A l'inverse, 5.840 -l'occupation disque du même projet sous n'importe lequel des gestionnaires 5.841 -de source distribués grandira rapidement, proportionnellement aux nombres 5.842 -de versions, car les différences entre chaque révisions seront très grandes. 5.843 -</para> 5.844 - 5.845 - <para id="x_ad">En outre, c'est souvent difficile ou, généralement, impossible de fusionner 5.846 -des différences dans un fichier binaire. La capacité de Subversion de 5.847 -verrouiller des fichiers, pour permettre à l'utilisateur d'être le seul 5.848 -à le mettre à jour (<quote>commit</quote>) temporairement, est un avantage significatif 5.849 -dans un projet doté de beaucoup de fichiers binaires. 5.850 -</para> 5.851 - 5.852 - <para id="x_ae">Mercurial peut importer l'historique depuis un dépôt Subversion. Il peut 5.853 -aussi exporter l'ensemble des révisions d'un projet vers un dépôt Subversion. 5.854 -Ceci rend très facile de <quote>prendre la température</quote> et d'utiliser Mercurial et Subversion 5.855 -en parallèle, avant de décider de migrer vers Mercurial. La conversion de 5.856 -l'historique est incrémentale, donc vous pouvez effectuer une conversion 5.857 -initiale, puis de petites additions par la suite pour ajouter les nouvelles 5.858 -modifications. 5.859 -</para> 5.860 + <para id="x_a6">Subversion est un des outils de gestion de source les 5.861 + plus populaire, il fût développé pour remplacer CVS. Il a une 5.862 + architecture client/server centralisée. 5.863 + </para> 5.864 + 5.865 + <para id="x_a7">Subversion et Mercurial ont des noms de commandes très 5.866 + similaires pour les mêmes opérations, ainsi si vous êtes familier 5.867 + avec l'un, c'est facile d'apprendre l'autre. Ces deux outils sont 5.868 + portables sur les systèmes d'exploitation les plus populaires. 5.869 + </para> 5.870 + 5.871 + <para id="x_a8">Avant la version 1.5, Subversion n'offrait aucune forme 5.872 + de support pour les fusions. Lors de l'écriture de ce livre, ses 5.873 + capacités de fusion étaient nouvelles, et réputées pour être <ulink 5.874 + url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword"> 5.875 + complexes et buguées</ulink>. 5.876 + </para> 5.877 + 5.878 + <para id="x_a9">Mercurial dispose d'un avantage substantiel en terme de 5.879 + performance par rapport à Subversion sur la plupart des opérations 5.880 + que j'ai pu tester. J'ai mesuré une différence de performance allant 5.881 + de deux à six fois plus rapide avec le système de stockage de fichier 5.882 + local de Subversion 1.4.3 (<emphasis>ra_local</emphasis>), qui est la 5.883 + méthode d'accès la plus rapide disponible. Dans un déploiement plus 5.884 + réaliste, impliquant un stockage réseau, Subversion serait encore 5.885 + plus désavantagé. Parce que la plupart des commandes Subversion 5.886 + doivent communiquer avec le serveur et que Subversion n'a pas de 5.887 + mécanisme de réplication, la capacité du serveur et la bande passante 5.888 + sont devenues des goulots d'étranglement pour les projets de taille 5.889 + moyenne ou grande. 5.890 + </para> 5.891 + 5.892 + <para id="x_aa">En outre, Subversion implique une surcharge 5.893 + substantielle dans le stockage local de certaines données, pour 5.894 + éviter des transactions avec le serveur, pour certaines opérations 5.895 + communes, telles que la recherche des fichiers modifiés 5.896 + (<literal>status</literal>) et l'affichage des modifications par 5.897 + rapport à la révision courante (<literal>diff</literal>). En 5.898 + conséquence, un répertoire de travail Subversion a souvent la même 5.899 + taille, ou est plus grand, qu'un dépôt Mercurial et son espace de 5.900 + travail, et ceci bien que le dépôt Mercurial contienne l'intégralité 5.901 + de l'historique. 5.902 + </para> 5.903 + 5.904 + <para id="x_ab">Subversion est largement supporté par les outils 5.905 + tierces. Mercurial est actuellement encore en retrait de ce point de 5.906 + vue. L'écart se réduit néanmoins, en effet, certains des outils 5.907 + graphiques sont maintenant supérieurs à leurs équivalents Subversion. 5.908 + Comme Mercurial, Subversion dispose d'un excellent manuel 5.909 + utilisateur. 5.910 + </para> 5.911 + 5.912 + <para id="x_ac">Parce que Subversion ne stocke pas l'historique chez 5.913 + ses clients, il est parfaitement adapté à la gestion de projets qui 5.914 + doivent suivre un ensemble de larges fichiers binaires et opaques. Si 5.915 + vous suivez une cinquantaine de versions d'un fichier incompressible 5.916 + de 10MB, l'occupation disque coté client d'un projet sous Subversion 5.917 + restera à peu près constante. A l'inverse, l'occupation disque du 5.918 + même projet sous n'importe lequel des gestionnaires de source 5.919 + distribués grandira rapidement, proportionnellement aux nombres de 5.920 + versions, car les différences entre chaque révisions seront très 5.921 + grandes. 5.922 + </para> 5.923 + 5.924 + <para id="x_ad">En outre, c'est souvent difficile ou, généralement, 5.925 + impossible de fusionner des différences dans un fichier binaire. La 5.926 + capacité de Subversion de verrouiller des fichiers, pour permettre à 5.927 + l'utilisateur d'être le seul à le mettre à jour 5.928 + (<quote>commit</quote>) temporairement, est un avantage significatif 5.929 + dans un projet doté de beaucoup de fichiers binaires. 5.930 + </para> 5.931 + 5.932 + <para id="x_ae">Mercurial peut importer l'historique depuis un dépôt 5.933 + Subversion. Il peut aussi exporter l'ensemble des révisions d'un 5.934 + projet vers un dépôt Subversion. Ceci rend très facile de 5.935 + <quote>prendre la température</quote> et d'utiliser Mercurial et 5.936 + Subversion en parallèle, avant de décider de migrer vers Mercurial. 5.937 + La conversion de l'historique est incrémentale, donc vous pouvez 5.938 + effectuer une conversion initiale, puis de petites additions par la 5.939 + suite pour ajouter les nouvelle modifications. 5.940 + </para> 5.941 5.942 5.943 </sect2> 5.944 <sect2> 5.945 <title>Git</title> 5.946 5.947 - <para id="x_af">Git est un outil de gestion de source distribué qui fût développé pour gérer 5.948 -le code source de noyau de Linux. Comme Mercurial, sa conception initiale a 5.949 -été inspirée par Monotone. 5.950 -</para> 5.951 - 5.952 - <para id="x_b0">Git dispose d'un ensemble conséquent de commandes, avec plus de 139 commandes 5.953 -individuelles pour la version 1.5.0. Il a aussi la réputation d'être difficile 5.954 -à apprendre. Comparé à Git, le point fort de Mercurial est clairement sa 5.955 -simplicité. 5.956 -</para> 5.957 - 5.958 - <para id="x_b1">En terme de performance, Git est extrêmement rapide. Dans la plupart des 5.959 -cas, il est plus rapide que Mercurial, tout du moins sur Linux, alors que 5.960 -Mercurial peut être plus performant sur d'autres opérations. Néanmoins, sur 5.961 -Windows, les performances et le niveau de support général fourni par Git, 5.962 -au moment de l'écriture de cet ouvrage, est bien derrière celui de Mercurial. 5.963 -</para> 5.964 - 5.965 - <para id="x_b2">Alors que le dépôt Mercurial ne demande aucune maintenance, un dépôt Git 5.966 -exige d'exécuter manuellement et régulièrement la commande <quote>repacks</quote> sur 5.967 -ces métadonnées. Sans ceci, les performances de git se dégradent et la 5.968 -consommation de l'espace disque augmente rapidement. Un serveur qui contient 5.969 -plusieurs dépôts Git qui ne sont pas régulièrement et fréquemment <quote>repacked</quote> 5.970 -deviendra un vrai problème lors des <quote>backups</quote> du disque, et il y eu des 5.971 -cas, où un <quote>backup</quote> journalier pouvait durer plus de 24 heures. Un dépôt 5.972 -fraichement <quote>repacked</quote> sera légèrement plus petit qu'un dépôt Mercurial, 5.973 -mais un dépôt non <quote>repacked</quote> est beaucoup plus grand. 5.974 -</para> 5.975 - 5.976 - <para id="x_b3">Le cœur de Git est écrit en C. La plupart des commandes Git sont implémentées 5.977 -sous forme de scripts Shell ou Perl, et la qualité de ces scripts varie 5.978 -grandement. J'ai plusieurs fois constaté que certains de ces scripts étaient 5.979 -chargés en mémoire aveuglément et que la présence d'erreurs pouvait s'avérer 5.980 -fatal. 5.981 -</para> 5.982 - 5.983 - <para id="x_b4">Mercurial peut importer l'historique d'un dépôt Git. 5.984 -</para> 5.985 - 5.986 - 5.987 + <para id="x_af">Git est un outil de gestion de source distribué qui fût 5.988 + développé pour gérer le code source de noyau de Linux. Comme 5.989 + Mercurial, sa conception initiale a été inspirée par Monotone. 5.990 + </para> 5.991 + 5.992 + <para id="x_b0">Git dispose d'un ensemble conséquent de commandes, avec 5.993 + plus de 139 commandes individuelles pour la version 1.5.0. Il a aussi 5.994 + la réputation d'être difficile à apprendre. Comparé à Git, le point 5.995 + fort de Mercurial est clairement sa simplicité. 5.996 + </para> 5.997 + 5.998 + <para id="x_b1">En terme de performance, Git est extrêmement rapide. 5.999 + Dans la plupart des cas, il est plus rapide que Mercurial, tout du 5.1000 + moins sur Linux, alors que Mercurial peut être plus performant sur 5.1001 + d'autres opérations. Néanmoins, sur Windows, les performances et le 5.1002 + niveau de support général fourni par Git, au moment de l'écriture de 5.1003 + cet ouvrage, est bien derrière celui de Mercurial. 5.1004 + </para> 5.1005 + 5.1006 + <para id="x_b2">Alors que le dépôt Mercurial ne demande aucune 5.1007 + maintenance, un dépôt Git exige d'exécuter manuellement et 5.1008 + régulièrement la commande <quote>repacks</quote> sur ses métadonnées. 5.1009 + Sans ceci, les performances de git se dégradent et la consommation de 5.1010 + l'espace disque augmente rapidement. Un serveur qui contient 5.1011 + plusieurs dépôts Git qui ne sont pas régulièrement et fréquemment 5.1012 + <quote>repacked</quote> deviendra un vrai problème lors des 5.1013 + <quote>backups</quote> du disque, et il y eu des cas, où un 5.1014 + <quote>backup</quote> journalier pouvait durer plus de 24 heures. Un 5.1015 + dépôt fraichement <quote>repacked</quote> sera légèrement plus petit 5.1016 + qu'un dépôt Mercurial, mais un dépôt non <quote>repacked</quote> est 5.1017 + beaucoup plus grand. 5.1018 + </para> 5.1019 + 5.1020 + <para id="x_b3">Le cœur de Git est écrit en C. La plupart des commandes 5.1021 + Git sont implémentées sous forme de scripts Shell ou Perl, et la 5.1022 + qualité de ces scripts varie grandement. J'ai plusieurs fois constaté 5.1023 + que certains de ces scripts étaient chargés en mémoire aveuglément et 5.1024 + que la présence d'erreurs pouvait s'avérer fatal. 5.1025 + </para> 5.1026 + 5.1027 + <para id="x_b4">Mercurial peut importer l'historique d'un dépôt Git.</para> 5.1028 5.1029 </sect2> 5.1030 <sect2> 5.1031 <title>CVS</title> 5.1032 5.1033 - <para id="x_b5">CVS est probablement l'outil de gestion de source le plus utilisé aujourd'hui 5.1034 -dans le monde. À cause de son manque de clarté interne, il n'est plus 5.1035 -maintenu depuis plusieurs années. 5.1036 -</para> 5.1037 - 5.1038 - <para id="x_b6">Il a une architecture client/serveur centralisée. Il ne regroupe pas les 5.1039 -modifications de fichiers dans une opération de <quote>commit</quote> atomique, ce 5.1040 -qui permet à ses utilisateurs de <quote>casser le <emphasis>build</emphasis></quote> assez 5.1041 -facilement : une personne peut effectuer une opération de <quote>commit</quote> 5.1042 -sans problème puis être bloquée par besoin de fusion, avec comme conséquence 5.1043 -néfaste, que les autres utilisateurs ne récupèreront qu'une partie de ses 5.1044 -modifications. Ce problème affecte aussi la manière de travailler avec 5.1045 -l'historique du projet. Si vous voulez voir toutes les modifications d'une 5.1046 -personne du projet, vous devrez injecter manuellement les descriptions et les 5.1047 -<emphasis remap="it">timestamps</emphasis> des modifications de chacun des fichiers impliqués (si 5.1048 -vous savez au moins quels sont ces fichiers). 5.1049 -</para> 5.1050 + <para id="x_b5">CVS est probablement l'outil de gestion de source le 5.1051 + plus utilisé aujourd'hui dans le monde. À cause de son manque de 5.1052 + clarté interne, il n'est plus maintenu depuis plusieurs années. 5.1053 + </para> 5.1054 + 5.1055 + <para id="x_b6">Il a une architecture client/serveur centralisée. Il ne 5.1056 + regroupe pas les modifications de fichiers dans une opération de 5.1057 + <quote>commit</quote> atomique, ce qui permet à ses utilisateurs de 5.1058 + <quote>casser le <emphasis>build</emphasis></quote> assez facilement 5.1059 + : une personne peut effectuer une opération de <quote>commit</quote> 5.1060 + sans problème puis être bloquée par besoin de fusion, avec comme 5.1061 + conséquence néfaste, que les autres utilisateurs ne récupèreront 5.1062 + qu'une partie de ses modifications. Ce problème affecte aussi la 5.1063 + manière de travailler avec l'historique du projet. Si vous voulez 5.1064 + voir toutes les modifications d'une personne du projet, vous devrez 5.1065 + injecter manuellement les descriptions et les <emphasis 5.1066 + remap="it">timestamps</emphasis> des modifications de chacun des 5.1067 + fichiers impliqués (si vous savez au moins quels sont ces fichiers). 5.1068 + </para> 5.1069 5.1070 <para id="x_b7">CVS a une notion étrange des <emphasis 5.1071 - remap="it">tags</emphasis> et des branches que je n'essayerai 5.1072 -même pas de décrire ici. Il ne supporte pas bien les opérations de renommage d'un 5.1073 -fichier ou d'un répertoire, ce qui facilite la corruption de son dépôt. Il n'a 5.1074 -presque pas pour ainsi dire de contrôle de cohérence interne, il est donc 5.1075 -pratiquement impossible de dire si un dépôt est corrompu ni à quel point. Je 5.1076 -ne recommanderai pas CVS pour un projet existant ou nouveau. 5.1077 -</para> 5.1078 - 5.1079 - <para id="x_b8">Mercurial peut importer l'historique d'un projet CVS. Néanmoins, il y a 5.1080 -quelques principes à respecter; ce qui est vrai aussi pour les autres 5.1081 -outils d'import de projet CVS. À cause de l'absence de <quote>commit</quote> atomique 5.1082 -et gestion de version de l'arborescence, il n'est pas possible de reconstruire 5.1083 -de manière précise l'ensemble de l'historique. Un travail de <quote>devinette</quote> 5.1084 -est donc nécessaire, et les fichiers renommés ne sont pas détectés. Parce 5.1085 -qu'une bonne part de l'administration d'un dépôt CVS est effectuée manuellement, 5.1086 -et est donc, sujette à erreur, il est courant que les imports CVS rencontrent 5.1087 -de nombreux problèmes avec les dépôt corrompus (des <emphasis 5.1088 -remap="it">timestamps</emphasis> de révision complètement buggés et des fichiers 5.1089 -verrouillés depuis des années sont deux des problèmes les moins intéressants dont 5.1090 -je me souvienne). 5.1091 -</para> 5.1092 + remap="it">tags</emphasis> et des branches que je n'essayerai même 5.1093 + pas de décrire ici. Il ne supporte pas bien les opérations de 5.1094 + renommage d'un fichier ou d'un répertoire, ce qui facilite la 5.1095 + corruption de son dépôt. Il n'a presque pas pour ainsi dire de 5.1096 + contrôle de cohérence interne, il est donc pratiquement impossible de 5.1097 + dire si un dépôt est corrompu ni à quel point. Je ne recommanderai 5.1098 + pas CVS pour un projet existant ou nouveau. 5.1099 + </para> 5.1100 + 5.1101 + <para id="x_b8">Mercurial peut importer l'historique d'un projet CVS. 5.1102 + Néanmoins, il y a quelques principes à respecter; ce qui est vrai 5.1103 + aussi pour les autres outils d'import de projet CVS. À cause de 5.1104 + l'absence de <quote>commit</quote> atomique et gestion de version de 5.1105 + l'arborescence, il n'est pas possible de reconstruire de manière 5.1106 + précise l'ensemble de l'historique. Un travail de 5.1107 + <quote>devinette</quote> est donc nécessaire, et les fichiers 5.1108 + renommés ne sont pas détectés. Parce qu'une bonne part de 5.1109 + l'administration d'un dépôt CVS est effectuée manuellement, et est 5.1110 + donc, sujette à erreur, il est courant que les imports CVS 5.1111 + rencontrent de nombreux problèmes avec les dépôt corrompus (des 5.1112 + <emphasis remap="it">timestamps</emphasis> de révision complètement 5.1113 + buggés et des fichiers verrouillés depuis des années sont deux des 5.1114 + problèmes les moins intéressants dont je me souvienne). 5.1115 + </para> 5.1116 5.1117 <para id="x_b9">Mercurial peut importer l'historique depuis un dépôt CVS. 5.1118 -</para> 5.1119 + </para> 5.1120 5.1121 5.1122 </sect2> 5.1123 <sect2> 5.1124 <title>Outils propriétaires</title> 5.1125 5.1126 - <para id="x_ba">Perforce a une architecture client/serveur centralisée, sans aucun 5.1127 -mécanisme de mise en cache de données coté client. Contrairement à la plupart 5.1128 -des outils modernes de gestion de source, Perforce exige de ses 5.1129 -utilisateurs d'exécuter une commande pour informer le serveur 5.1130 -central de tout fichier qu'ils souhaitent modifier. 5.1131 -</para> 5.1132 - 5.1133 - <para id="x_bb">Les performances de Perforce sont plutôt bonnes pour des petites 5.1134 -équipes, mais elles s'effondrent rapidement lorsque le nombre 5.1135 -d'utilisateurs augmente au delà de la douzaine. Des installations 5.1136 -de Perforce assez larges nécessitent le déploiement de proxies pour 5.1137 -supporter la montée en charge associée. 5.1138 -</para> 5.1139 - 5.1140 + <para id="x_ba">Perforce a une architecture client/serveur centralisée, 5.1141 + sans aucun mécanisme de mise en cache de données coté client. 5.1142 + Contrairement à la plupart des outils modernes de gestion de source, 5.1143 + Perforce exige de ses utilisateurs d'exécuter une commande pour 5.1144 + informer le serveur central de tout fichier qu'ils souhaitent 5.1145 + modifier. 5.1146 + </para> 5.1147 + 5.1148 + <para id="x_bb">Les performances de Perforce sont plutôt bonnes pour 5.1149 + des petites équipes, mais elles s'effondrent rapidement lorsque le 5.1150 + nombre d'utilisateurs augmente au delà de la douzaine. Des 5.1151 + installations de Perforce assez larges nécessitent le déploiement de 5.1152 + proxies pour supporter la montée en charge associée. 5.1153 + </para> 5.1154 5.1155 </sect2> 5.1156 <sect2> 5.1157 <title>Choisir un outil de gestion de source</title> 5.1158 5.1159 - <para id="x_bc">A l'exception de CVS, tous les outils listés ci-dessus ont des 5.1160 -forces qui leur sont propres et qui correspondent à certaines 5.1161 -formes de projet. Il n'y a pas un seul meilleur outil de gestion 5.1162 -de source qui correspondrait le mieux à toutes les situations. 5.1163 -</para> 5.1164 - 5.1165 - <para id="x_bd">En guise exemple, Subversion est un très bon choix lorsqu'on travaille 5.1166 -avec beaucoup de fichiers binaires, qui évoluent régulièrement, grâce 5.1167 -à sa nature centralisée et sa capacité à verrouiller des fichiers. 5.1168 -</para> 5.1169 - 5.1170 - <para id="x_be">Personnellement, je préfère Mercurial pour sa simplicité, ses 5.1171 -performances et sa bonne capacité de fusion, et il m'a très bien rendu service 5.1172 -de plusieurs années maintenant. 5.1173 -</para> 5.1174 - 5.1175 + <para id="x_bc">A l'exception de CVS, tous les outils listés ci-dessus 5.1176 + ont des forces qui leur sont propres et qui correspondent à certaines 5.1177 + formes de projet. Il n'y a pas un seul meilleur outil de gestion de 5.1178 + source qui correspondrait le mieux à toutes les situations. 5.1179 + </para> 5.1180 + 5.1181 + <para id="x_bd">En guise exemple, Subversion est un très bon choix 5.1182 + lorsqu'on travaille avec beaucoup de fichiers binaires, qui évoluent 5.1183 + régulièrement, grâce à sa nature centralisée et sa capacité à 5.1184 + verrouiller des fichiers. 5.1185 + </para> 5.1186 + 5.1187 + <para id="x_be">Personnellement, je préfère Mercurial pour sa 5.1188 + simplicité, ses performances et sa bonne capacité de fusion, et il 5.1189 + m'a très bien rendu service de plusieurs années maintenant. 5.1190 + </para> 5.1191 5.1192 </sect2> 5.1193 </sect1> 5.1194 <sect1> 5.1195 <title>Migrer depuis un outil à Mercurial</title> 5.1196 5.1197 - <para id="x_bf">Mercurial est livré avec une extension nommée <literal role="hg-ext">convert</literal>, qui 5.1198 -peut de manière incrémentale importer des révisions depuis différents 5.1199 -autres outils de gestion de source. Par <quote>incrémental</quote>, j'entends que 5.1200 -vous pouvez convertir l'historique entier du projet en une seule fois, 5.1201 -puis relancer l'outil d'import plus tard pour obtenir les modifications 5.1202 -effectuées depuis votre import initial. 5.1203 -</para> 5.1204 - 5.1205 - <para id="x_c0">Les outils de gestion de source supportés par <literal role="hg-ext">convert</literal> sont : 5.1206 -</para> 5.1207 + <para id="x_bf">Mercurial est livré avec une extension nommée <literal 5.1208 + role="hg-ext">convert</literal>, qui peut, de manière incrémentale 5.1209 + importer des révisions depuis différents autres outils de gestion de 5.1210 + source. Par <quote>incrémental</quote>, j'entends que vous pouvez 5.1211 + convertir l'historique entier du projet en une seule fois, puis 5.1212 + relancer l'outil d'import plus tard pour obtenir les modifications 5.1213 + effectuées depuis votre import initial. 5.1214 + </para> 5.1215 + 5.1216 + <para id="x_c0">Les outils de gestion de source supportés par <literal 5.1217 + role="hg-ext">convert</literal> sont : 5.1218 + </para> 5.1219 <itemizedlist> 5.1220 <listitem><para id="x_c1">Subversion</para></listitem> 5.1221 <listitem><para id="x_c2">CVS</para></listitem> 5.1222 <listitem><para id="x_c3">Git</para></listitem> 5.1223 - <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist> 5.1224 - 5.1225 - <para id="x_c5">En outre, <literal role="hg-ext">convert</literal> peut exporter les modifications depuis Mercurial 5.1226 -vers Subversion. Ceci rend possible d'essayer Subversion en parallèle 5.1227 -avant de choisir une solution définitive, sans aucun risque de perte de 5.1228 -données. 5.1229 -</para> 5.1230 - 5.1231 - <para id="x_c6">La commande <command role="hg-ext-conver">convert</command> est très simple à utiliser. Simplement, 5.1232 -indiquez le chemin ou l'URL du dépôt de source, en lui indiquant éventuellement 5.1233 -le nom du chemin de destination, et la conversion se met en route. Après cet 5.1234 -import initial, il suffit de relancer la commande encore une fois pour 5.1235 -importer les modifications effectuées depuis. 5.1236 -</para> 5.1237 + <listitem><para id="x_c4">Darcs</para></listitem> 5.1238 + </itemizedlist> 5.1239 + 5.1240 + <para id="x_c5">En outre, <literal role="hg-ext">convert</literal> peut 5.1241 + exporter les modifications depuis Mercurial vers Subversion. Ceci rend 5.1242 + possible d'essayer Subversion en parallèle avant de choisir une 5.1243 + solution définitive, sans aucun risque de perte de données. 5.1244 + </para> 5.1245 + 5.1246 + <para id="x_c6">La commande <command 5.1247 + role="hg-ext-conver">convert</command> est très simple à utiliser. 5.1248 + Simplement, indiquez le chemin ou l'URL du dépôt de source, en lui 5.1249 + indiquant éventuellement le nom du chemin de destination, et la 5.1250 + conversion se met en route. Après cet import initial, il suffit de 5.1251 + relancer la commande encore une fois pour importer les modifications 5.1252 + effectuées depuis. 5.1253 + </para> 5.1254 </sect1> 5.1255 5.1256 <sect1> 5.1257 <title>Une courte histoire de la gestion de source</title> 5.1258 5.1259 <para id="x_c7">Le plus célèbre des anciens outils de gestion de source 5.1260 - est <emphasis remap="it">SCCS</emphasis> 5.1261 -(Source Code Control System)}, que Marc Rochkind conçu dans les laboratoires de 5.1262 -recherche de Bell (<emphasis remap="it">Bell Labs</emphasis>), dans le début des années 70. 5.1263 -<emphasis remap="it">SCCS</emphasis> ne fonctionnait que sur des fichiers individuels, et obligeait chaque 5.1264 -personne travaillant sur le projet d'avoir un accès à un répertoire de 5.1265 -travail commun, sur le même système. Seulement une seule personne pouvait 5.1266 -modifier un fichier au même moment, ce fonctionnement était assuré par 5.1267 -l'utilisation de verrou (<quote>lock</quote>). Il était courant que des personnes 5.1268 -verrouillent des fichiers, et plus tard, oublient de le déverrouiller; 5.1269 -empêchant n'importe qui d'autre de travailler sur ces fichiers sans l'aide de 5.1270 -l'administrateur... 5.1271 -</para> 5.1272 + est <emphasis remap="it">SCCS</emphasis> (Source Code Control System)}, 5.1273 + que Marc Rochkind conçu dans les laboratoires de recherche de Bell 5.1274 + (<emphasis remap="it">Bell Labs</emphasis>), dans le début des années 5.1275 + 70. <emphasis remap="it">SCCS</emphasis> ne fonctionnait que sur des 5.1276 + fichiers individuels, et obligeait chaque personne travaillant sur le 5.1277 + projet d'avoir un accès à un répertoire de travail commun, sur le même 5.1278 + système. Seulement une seule personne pouvait modifier un fichier au 5.1279 + même moment, ce fonctionnement était assuré par l'utilisation de verrou 5.1280 + (<quote>lock</quote>). Il était courant que des personnes verrouillent 5.1281 + des fichiers, et plus tard, oublient de le déverrouiller ; empêchant 5.1282 + n'importe qui d'autre de travailler sur ces fichiers sans l'aide de 5.1283 + l'administrateur... 5.1284 + </para> 5.1285 5.1286 <para id="x_c8">Walter Tichy a développé une alternative libre à 5.1287 - <emphasis remap="it">SCCS</emphasis> au début des 5.1288 -années 80, qu'il nomma <emphasis remap="it">RCS (Revision Control System)</emphasis>. Comme 5.1289 -<emphasis remap="it">SCCS</emphasis>, <emphasis remap="it">RCS</emphasis> demandait aux développeurs de travailler sur le même 5.1290 -répertoire partagé, et de verrouiller les 5.1291 -fichiers pour se prémunir de tout conflit issu de modifications concurrentes. 5.1292 -</para> 5.1293 - 5.1294 - <para id="x_c9">Un peu plus tard dans les années 1980, Dick Grune utilisa <emphasis remap="it">RCS</emphasis> comme 5.1295 -une brique de base pour un ensemble de scripts <emphasis 5.1296 -remap="it">shell</emphasis> qu'il intitula 5.1297 -cmt, avant de la renommer en <emphasis remap="it">CVS (Concurrent Versions System)</emphasis>. La 5.1298 -grande innovation de CVS était que les développeurs pouvaient travailler 5.1299 -simultanément et indépendamment dans leur propre espace de travail. Ces espaces 5.1300 -de travail privés assuraient que les développeurs ne se marchent pas 5.1301 -mutuellement sur les pieds, comme c'était souvent le cas avec RCS et SCCS. 5.1302 -Chaque développeur disposait donc de sa copie de tous les fichiers du projet, 5.1303 -et ils pouvaient donc librement les modifier. Ils devaient néanmoins effectuer 5.1304 -la <quote>fusion</quote> (<emphasis 5.1305 -remap="it"><quote>merge</quote></emphasis>) de leurs fichiers, avant d'effectuer le 5.1306 -<quote>commit</quote> de leur modifications sur le dépôt central. 5.1307 -</para> 5.1308 - 5.1309 -<para>Brian Berliner reprit les scripts de Grune's et les réécrit en C, qu'il publia 5.1310 -en 1989. Depuis, ce code a été modifié jusqu'à devenir la version moderne de 5.1311 -CVS. CVS a acquis ainsi la capacité de fonctionner en réseau, transformant son 5.1312 -architecture en client/serveur. L'architecture de CVS est centralisée, seul le 5.1313 -serveur a une copie de l'historique du projet. L'espace de travail client ne 5.1314 -contient qu'une copie de la dernière version du projet, et quelques métadonnées 5.1315 -pour indiquer où le serveur se trouve. CVS a été un grand succès, aujourd'hui 5.1316 -il est probablement l'outil de gestion de contrôle le plus utilisé au monde. 5.1317 -</para> 5.1318 - 5.1319 -<para>Au début des années 1990, Sun Microsystmes développa un premier outil de 5.1320 -gestion de source distribué, nommé TeamWare. Un espace de travail TeamWare 5.1321 -contient une copie complète de l'historique du projet. TeamWare n'a pas de 5.1322 -notion de dépôt central. (CVS utilisait RCS pour le stockage de l'historique, 5.1323 -TeamWare utilisait SCCS). 5.1324 -</para> 5.1325 - 5.1326 -<para>Alors que les années 1990 avançaient, les utilisateurs ont pris conscience d'un 5.1327 -certain nombre de problèmes avec CVS. Il enregistrait simultanément des 5.1328 -modifications sur différents fichiers individuellement, au lieu de les 5.1329 -regrouper dans une seule opération cohérente et atomique. Il ne gère pas bien 5.1330 -sa hiérarchie de fichier, il est donc assez aisé de créer le chaos en renommant 5.1331 -les fichiers et les répertoires. Pire encore, son code source est difficile à 5.1332 -lire et à maintenir, ce qui agrandit largement le <quote>niveau de souffrance</quote> 5.1333 -associé à la réparation de ces problèmes d'architecture de manière prohibitive. 5.1334 -</para> 5.1335 - 5.1336 -<para>En 2001, Jim Blandy et Karl Fogel, deux développeurs qui avaient travaillé sur 5.1337 -CVS, initièrent un projet pour le remplacer par un outil qui aurait une 5.1338 -meilleure architecture et un code plus propre. Le résultat, Subversion, ne 5.1339 -quitte pas le modèle centralisé et client/server de CVS, mais ajoute les 5.1340 -opérations de <quote>commit</quote> atomique sur de multiples fichiers, une meilleure 5.1341 -gestion des espaces de noms, et d'autres fonctionnalités qui en font un 5.1342 -meilleur outil que CVS. Depuis sa première publication, il est rapidement 5.1343 -devenu très populaire. 5.1344 -</para> 5.1345 - 5.1346 -<para>Plus ou moins simultanément, Graydon Hoare a commencé sur l'ambitieux 5.1347 -système de gestion distribué Monotone. Bien que Monotone corrige plusieurs 5.1348 -défauts de CVS's tout en offrant une architecture <quote>peer-to-peer</quote>, il va aussi 5.1349 -plus loin que la plupart des outils de révision de manière assez innovante. Il 5.1350 -utilise des <quote>hash</quote> cryptographiques comme identifiants, et il a une notion 5.1351 -complète de <quote>confiance</quote> du code issu des différentes sources. 5.1352 -</para> 5.1353 - 5.1354 -<para>Mercurial est né en 2005. Bien que très influencé par Monotone, Mercurial se 5.1355 -concentre sur la facilité d'utilisation, les performances et la capacité à 5.1356 -monter en charge pour de très gros projets. 5.1357 -</para> 5.1358 - 5.1359 -</sect1> 5.1360 - 5.1361 - 5.1362 + <emphasis remap="it">SCCS</emphasis> au début des années 80, qu'il 5.1363 + nomma <emphasis remap="it">RCS (Revision Control System)</emphasis>. 5.1364 + Comme <emphasis remap="it">SCCS</emphasis>, <emphasis 5.1365 + remap="it">RCS</emphasis> demandait aux développeurs de travailler 5.1366 + sur le même répertoire partagé, et de verrouiller les fichiers pour se 5.1367 + prémunir de tout conflit issu de modifications concurrentes. 5.1368 + </para> 5.1369 + 5.1370 + <para id="x_c9">Un peu plus tard dans les années 1980, Dick Grune utilisa 5.1371 + <emphasis remap="it">RCS</emphasis> comme une brique de base pour un 5.1372 + ensemble de scripts <emphasis remap="it">shell</emphasis> qu'il 5.1373 + intitula cmt, avant de la renommer en <emphasis remap="it">CVS 5.1374 + (Concurrent Versions System)</emphasis>. La grande innovation de CVS 5.1375 + était que les développeurs pouvaient travailler simultanément et 5.1376 + indépendamment dans leur propre espace de travail. Ces espaces de 5.1377 + travail privés assuraient que les développeurs ne se marchent pas 5.1378 + mutuellement sur les pieds, comme c'était souvent le cas avec RCS et 5.1379 + SCCS. Tous les développeurs disposaient donc de leur copie de tous les 5.1380 + fichiers du projet, et ils pouvaient donc librement les modifier. Ils 5.1381 + devaient néanmoins effectuer la <quote>fusion</quote> (<emphasis 5.1382 + remap="it"><quote>merge</quote></emphasis>) de leurs fichiers, avant 5.1383 + d'effectuer le <quote>commit</quote> de leurs modifications sur le dépôt 5.1384 + central. 5.1385 + </para> 5.1386 + 5.1387 + <para>Brian Berliner reprit les scripts de Grune's et les réécrit en C, 5.1388 + qu'il publia en 1989. Depuis, ce code a été modifié jusqu'à devenir la 5.1389 + version moderne de CVS. CVS a acquis ainsi la capacité de fonctionner 5.1390 + en réseau, transformant son architecture en client/serveur. 5.1391 + L'architecture de CVS est centralisée, seul le serveur a une copie de 5.1392 + l'historique du projet. L'espace de travail client ne contient qu'une 5.1393 + copie de la dernière version du projet, et quelques métadonnées pour 5.1394 + indiquer où le serveur se trouve. CVS a été un grand succès, 5.1395 + aujourd'hui il est probablement l'outil de gestion de contrôle le plus 5.1396 + utilisé au monde. 5.1397 + </para> 5.1398 + 5.1399 + <para>Au début des années 1990, Sun Microsystems développa un premier 5.1400 + outil de gestion de source distribué, nommé TeamWare. Un espace de 5.1401 + travail TeamWare contient une copie complète de l'historique du projet. 5.1402 + TeamWare n'a pas de notion de dépôt central. (CVS utilisait RCS pour le 5.1403 + stockage de l'historique, TeamWare utilisait SCCS). 5.1404 + </para> 5.1405 + 5.1406 + <para>Alors que les années 1990 avançaient, les utilisateurs ont pris 5.1407 + conscience d'un certain nombre de problèmes avec CVS. Il enregistrait 5.1408 + simultanément des modifications sur différents fichiers 5.1409 + individuellement, au lieu de les regrouper dans une seule opération 5.1410 + cohérente et atomique. Il ne gère pas bien sa hiérarchie de fichier, il 5.1411 + est donc assez aisé de créer le chaos en renommant les fichiers et les 5.1412 + répertoires. Pire encore, son code source est difficile à lire et à 5.1413 + maintenir, ce qui agrandit largement le <quote>niveau de 5.1414 + souffrance</quote> associé à la réparation de ces problèmes 5.1415 + d'architecture de manière prohibitive. 5.1416 + </para> 5.1417 + 5.1418 + <para>En 2001, Jim Blandy et Karl Fogel, deux développeurs qui avaient 5.1419 + travaillé sur CVS, initièrent un projet pour le remplacer par un outil 5.1420 + qui aurait une meilleure architecture et un code plus propre. Le 5.1421 + résultat, Subversion, ne quitte pas le modèle centralisé et 5.1422 + client/server de CVS, mais ajoute les opérations de 5.1423 + <quote>commit</quote> atomique sur de multiples fichiers, une meilleure 5.1424 + gestion des espaces de noms, et d'autres fonctionnalités qui en font un 5.1425 + meilleur outil que CVS. Depuis sa première publication, il est 5.1426 + rapidement devenu très populaire. 5.1427 + </para> 5.1428 + 5.1429 + <para>Plus ou moins simultanément, Graydon Hoare a commencé sur 5.1430 + l'ambitieux système de gestion distribué Monotone. Bien que Monotone 5.1431 + corrige plusieurs défauts de CVS tout en offrant une architecture 5.1432 + <quote>peer-to-peer</quote>, il va aussi plus loin que la plupart des 5.1433 + outils de révision de manière assez innovante. Il utilise des 5.1434 + <quote>hashs</quote> cryptographiques comme identifiants, et il a une 5.1435 + notion complète de <quote>confiance</quote> du code issu des 5.1436 + différentes sources. 5.1437 + </para> 5.1438 + 5.1439 + <para>Mercurial est né en 2005. Bien que très influencé par Monotone, 5.1440 + Mercurial se concentre sur la facilité d'utilisation, les performances 5.1441 + et la capacité à monter en charge pour de très gros projets. 5.1442 + </para> 5.1443 + 5.1444 + </sect1> 5.1445 5.1446 </chapter> 5.1447
6.1 --- a/fr/ch02-tour-basic.xml Sat Sep 12 17:58:26 2009 +0200 6.2 +++ b/fr/ch02-tour-basic.xml Sat Sep 12 17:58:56 2009 +0200 6.3 @@ -7,92 +7,94 @@ 6.4 <sect1> 6.5 <title>Installer Mercurial sur votre système</title> 6.6 6.7 - <para id="x_1">Des paquetages binaires de Mercurial sont disponibles pour la plupart 6.8 -des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate 6.9 -de Mercurial sur votre ordinateur.</para> 6.10 + <para id="x_1">Des paquetages binaires de Mercurial sont disponibles pour la 6.11 + plupart des systèmes d'exploitation, ce qui rend facile l'utilisation 6.12 + immédiate de Mercurial sur votre ordinateur.</para> 6.13 6.14 <sect2> 6.15 <title>Windows</title> 6.16 6.17 <para id="x_c">La meilleur version de Mercurial pour Windows est 6.18 - TortoiseHg, qui peut être téléchargée ici : <ulink 6.19 - url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink> 6.20 - Ce logiciel n'a aucune dépendance exterieure; il fonctionne 6.21 - <quote>et c'est tout</quote>. Il fournit aussi bien les outils en ligne 6.22 - de commmande qu'un interface graphique.</para> 6.23 - 6.24 - <sect2> 6.25 - 6.26 - <sect2> 6.27 - <title>Mac OS X</title> 6.28 - 6.29 - <para id="x_a">Lee Cantey publie un installeur de Mercurial pour Mac OS X 6.30 - sur <ulink 6.31 - url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> 6.32 - </sect2> 6.33 - 6.34 - <sect2> 6.35 - <title>Linux</title> 6.36 - 6.37 - <para id="x_2">Parce que chaque distribution de Linux a ses propres outils de gestion 6.38 - de paquets, politiques et rythmes de développements, il est difficile de 6.39 - donner un ensemble d'instructions uniques pour installer les binaires de 6.40 - Mercurial. La version de Mercurial avec laquelle vous vous retrouverez 6.41 - dépendra grandement de l'activité de la personne en charge du paquetage 6.42 - pour la distribution.</para> 6.43 - 6.44 - <para id="x_3">Pour rester simple, je me concentrerai sur l'installation de Mercurial 6.45 - en ligne de commande, sous les distributions les plus courantes. La 6.46 - plupart des distributions fournissent des gestionnaires graphiques de 6.47 - paquetage qui vous permettront d'installer Mercurial en quelques clicks. 6.48 - Le paquetage devrait se nommer <literal>mercurial</literal>.</para> 6.49 - 6.50 - <itemizedlist> 6.51 - <listitem><para id="x_4">Ubuntu et Debian:</para> 6.52 - <programlisting>apt-get install mercurial</listitem> 6.53 - <listitem><para id="x_5">Fedora:</para> 6.54 - <programlisting>yum install mercurial</programlisting> 6.55 - <listitem><para id="x_6">Gentoo:</para> 6.56 - <programlisting>emerge mercurial</programlisting></listitem> 6.57 - <listitem><para id="x_715">OpenSUSE:</para> 6.58 - <programlisting>zypper install mercurial</programlisting> 6.59 - </itemizedlist> 6.60 - 6.61 - </sect2> 6.62 - <sect2> 6.63 - <title>Solaris</title> 6.64 - 6.65 - <para id="x_09">SunFreeWare, à <ulink 6.66 - url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 6.67 - fournit des paquet précompilés pour Mercurial.</para> 6.68 - </sect2> 6.69 - <sect1> 6.70 + TortoiseHg, qui peut être téléchargée ici : <ulink 6.71 + url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 6.72 + Ce logiciel n'a aucune dépendance exterieure; il fonctionne <quote>et 6.73 + c'est tout</quote>. Il fournit aussi bien les outils en ligne de 6.74 + commmande qu'une interface graphique.</para> 6.75 + 6.76 + </sect2> 6.77 + 6.78 + <sect2> 6.79 + <title>Mac OS X</title> 6.80 + 6.81 + <para id="x_a">Lee Cantey publie un installeur de Mercurial pour Mac OS 6.82 + X sur <ulink 6.83 + url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> 6.84 + </sect2> 6.85 + 6.86 + <sect2> 6.87 + <title>Linux</title> 6.88 + 6.89 + <para id="x_2">Parce que chaque distribution de Linux a ses propres 6.90 + outils de gestion de paquets, politiques et rythmes de 6.91 + développements, il est difficile de donner un ensemble 6.92 + d'instructions unique pour installer les binaires de Mercurial. La 6.93 + version de Mercurial avec laquelle vous vous retrouverez dépendra 6.94 + grandement de l'activité de la personne en charge du paquetage pour 6.95 + la distribution.</para> 6.96 + 6.97 + <para id="x_3">Pour rester simple, je me concentrerai sur 6.98 + l'installation de Mercurial en ligne de commande, sous les 6.99 + distributions les plus courantes. La plupart des distributions 6.100 + fournissent des gestionnaires graphiques de paquetage qui vous 6.101 + permettront d'installer Mercurial en quelques clicks. Le paquetage 6.102 + devrait se nommer <literal>mercurial</literal>.</para> 6.103 + 6.104 + <itemizedlist> 6.105 + <listitem><para id="x_4">Ubuntu et Debian:</para> 6.106 + <programlisting>apt-get install mercurial</listitem> 6.107 + <listitem><para id="x_5">Fedora:</para> 6.108 + <programlisting>yum install mercurial</programlisting> 6.109 + <listitem><para id="x_6">Gentoo:</para> 6.110 + <programlisting>emerge mercurial</programlisting></listitem> 6.111 + <listitem><para id="x_715">OpenSUSE:</para> 6.112 + <programlisting>zypper install mercurial</programlisting> 6.113 + </itemizedlist> 6.114 + 6.115 + </sect2> 6.116 + <sect2> 6.117 + <title>Solaris</title> 6.118 + 6.119 + <para id="x_09">SunFreeWare, à <ulink 6.120 + url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 6.121 + fournit des paquets précompilés pour Mercurial.</para> 6.122 + </sect2> 6.123 + </sect1> 6.124 6.125 <sect1> 6.126 <title>Commencer à utiliser Mercurial</title> 6.127 6.128 - <para id="x_e">Pour commencer, nous utiliserons la commande <command role="hg-cmd">hg 6.129 - version</command> pour vérifier si Mercurial est installé proprement. Les 6.130 - informations affichées sur la version ne sont pas réellement importantes en 6.131 - soit, c'est surtout de savoir si elles s'affichent qui nous 6.132 - intéresse.</para> 6.133 - 6.134 - &interaction.tour.version; 6.135 - 6.136 - <sect2> 6.137 - <title>L'aide intégrée</title> 6.138 - 6.139 - <para id="x_e">Mercurial fournit un système d'aide intégré, ce qui est 6.140 - inestimable quand vous vous retrouvez coincé à essayer de vous rappeler 6.141 - comment lancer une commande. Si vous êtes bloqué, exécutez simplement 6.142 - <command role="hg-cmd">hg help</command>; elle affichera une brève 6.143 - liste des commandes, avec une description pour chacune. Si vous demandez 6.144 - de l'aide sur une commande spécifique (voir ci-dessous), elle affichera 6.145 - des informations plus détaillées.</para> 6.146 - 6.147 - &interaction.tour.help; 6.148 - 6.149 - <para id="x_10">Pour un niveau d'informations encore plus détaillées 6.150 + <para id="x_e">Pour commencer, nous utiliserons la commande <command 6.151 + role="hg-cmd">hg version</command> pour vérifier si Mercurial est 6.152 + installé proprement. Les informations affichées sur la version ne sont 6.153 + pas réellement importantes en soit, c'est surtout de savoir si elles 6.154 + s'affichent qui nous intéresse.</para> 6.155 + 6.156 + &interaction.tour.version; 6.157 + 6.158 + <sect2> 6.159 + <title>L'aide intégrée</title> 6.160 + 6.161 + <para id="x_e">Mercurial fournit un système d'aide intégré, ce qui est 6.162 + inestimable quand vous vous retrouvez coincé à essayer de vous 6.163 + rappeler comment lancer une commande. Si vous êtes bloqué, exécutez 6.164 + simplement <command role="hg-cmd">hg help</command>; elle affichera 6.165 + une brève liste des commandes, avec une description pour chacune. Si 6.166 + vous demandez de l'aide sur une commande spécifique (voir 6.167 + ci-dessous), elle affichera des informations plus détaillées.</para> 6.168 + 6.169 + &interaction.tour.help; 6.170 + 6.171 + <para id="x_10">Pour un niveau d'informations encore plus détaillé 6.172 (ce dont vous aurez rarement besoin), exécuter <command role="hg-cmd">hg 6.173 help <option role="hg-opt-global">-v</option></command>. L'option 6.174 <option role="hg-opt-global">-v</option> est l'abréviation de 6.175 @@ -110,7 +112,7 @@ 6.176 6.177 <para id="x_12">Il n'y a rien de particulièrement magique au sujet de 6.178 ce dépôt, c'est simplement une arborescence sur votre système de fichiers 6.179 - de Mercurial traite de manière spéciale. Vous pouvez renommer ou effacer 6.180 + que Mercurial traite de manière spéciale. Vous pouvez renommer ou effacer 6.181 ce répertoire à n'impporte quel moment, en utilisant la ligne de commande 6.182 ou votre explorateur de fichiers.</para> 6.183 6.184 @@ -123,32 +125,34 @@ 6.185 Mercurial. Cette commande est appelée <command role="hg-cmd">hg clone</command>, 6.186 car elle crée une copie identique à un dépôt existant.</para> 6.187 6.188 - &interaction.tour.clone; 6.189 - 6.190 - <para id="x_67c">Un avantage de la commande <command 6.191 - role="hg-cmd">hg clone</command> est que, comme nous l'avons vu ci 6.192 - dessus, elle nous permet de faire de cloner les dépôts à travers le 6.193 - réseau. Un autre est qu'elle se rappelle d'où a été cloné un dépôt, ce 6.194 - qui est utile quand on veut mettre à jour le clone.</para> 6.195 - 6.196 - <para id="x_14">Si votre opération de clonage réussit, vous devriez maintenant 6.197 + &interaction.tour.clone; 6.198 + 6.199 + <para id="x_67c">Un avantage de la commande <command role="hg-cmd">hg 6.200 + clone</command> est que, comme nous l'avons vu ci dessus, elle nous 6.201 + permet de faire de cloner les dépôts à travers le réseau. Un autre 6.202 + est qu'elle se rappelle d'où a été cloné un dépôt, ce qui est utile 6.203 + quand on veut mettre à jour le clone.</para> 6.204 + 6.205 + <para id="x_14">Si votre opération de clonage réussit, vous devriez maintenant 6.206 avoir un répertoire local appelé <filename class="directory">hello</filename>. 6.207 Ce répertoire contiendra quelques fichiers.</para> 6.208 6.209 - &interaction.tour.ls; 6.210 - 6.211 - <para id="x_15">Ces fichiers ont le même contenu et historique dans votre dépôt 6.212 - qu'ils ont dans le dépôt que vous avez cloné.</para> 6.213 - 6.214 - <para id="x_16">Chaque dépôt Mercurial est complet, autonome et indépendant. Il 6.215 - contient sa propre copie privée des fichiers du projet et de leur 6.216 - historique. Le clone d'un dépôt se souvient de la localisation du 6.217 - dépôt à partir duquel il a été clôné, mais il ne communique pas avec 6.218 - ce dernier, ou un autre, à moins que vous ne lui demandiez.</para> 6.219 - 6.220 - <para id="x_17">Ce que tout ceci signifie pour le moment est que nous sommes libres 6.221 - d'expérimenter avec ce dépôt, confiants dans le fait qu'il s'agit d'un 6.222 - <quote>bac à sable</quote> qui n'affectera personne d'autre.</para> 6.223 + &interaction.tour.ls; 6.224 + 6.225 + <para id="x_15">Ces fichiers ont le même contenu et historique dans votre dépôt 6.226 + qu'ils ont dans le dépôt que vous avez cloné.</para> 6.227 + 6.228 + <para id="x_16">Chaque dépôt Mercurial est complet, autonome et 6.229 + indépendant. Il contient sa propre copie privée des fichiers du 6.230 + projet et de leur historique. Le clone d'un dépôt se souvient de la 6.231 + localisation du dépôt à partir duquel il a été clôné, mais il ne 6.232 + communique pas avec ce dernier, ou un autre, à moins que vous ne lui 6.233 + demandiez.</para> 6.234 + 6.235 + <para id="x_17">Ce que tout ceci signifie pour le moment est que nous 6.236 + sommes libres d'expérimenter avec ce dépôt, confiants dans le fait 6.237 + qu'il s'agit d'un <quote>bac à sable</quote> qui n'affectera personne 6.238 + d'autre.</para> 6.239 6.240 </sect2> 6.241 <sect2> 6.242 @@ -159,7 +163,7 @@ 6.243 </filename>. C'est ici que Mercurial conserve toutes ses 6.244 métadonnées.</para> 6.245 6.246 - &interaction.tour.ls-a; 6.247 + &interaction.tour.ls-a; 6.248 6.249 <para id="x_19">Le contenu du répertoire <filename class="directory">.hg 6.250 </filename> et ses sous répertoires sont les seuls propres à Mercurial. 6.251 @@ -186,7 +190,7 @@ 6.252 La commande <command role="hg-cmd">hg log</command> vous donne une 6.253 vue de l'historique.</para> 6.254 6.255 - &interaction.tour.log; --> 6.256 + &interaction.tour.log; 6.257 6.258 <para "x_1c">Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque 6.259 révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous 6.260 @@ -194,36 +198,38 @@ 6.261 qu'il contient un ensemble de modifications sur plusieurs fichiers.</para> 6.262 6.263 <para id="x_1d">La commande <command role="hg-cmd">hg log</command> affiche 6.264 - ainsi ces informations:</para> 6.265 + ainsi ces informations :</para> 6.266 6.267 <itemizedlist> 6.268 - <listitem><para id="x_1e"><literal>changeset</literal>: Ce champ contient 6.269 + <listitem><para id="x_1e"><literal>changeset</literal> : Ce champ contient 6.270 un nombre, séparé par deux points (:), d'une chaine hexadécimale. Il 6.271 s'agit en fait d'<emphasis>identifiants</emphasis> d'un changeset. Il y a 6.272 deux identifiants car le numéro de la révision est plus court et plus à 6.273 facile à saisir qu'une séquence hexadécimale.</para> 6.274 </listitem> 6.275 - <listitem><para id="x_1f"><literal>user</literal>: L'identité de la personne 6.276 + <listitem><para id="x_1f"><literal>user</literal> : L'identité de la personne 6.277 qui a créée ce %%% laisser le terme anglais car il sera affiché 6.278 changeset. C'est un champ libre de forme, mais la plupart du 6.279 temps il contient le nom et l'email de la personne.</para> 6.280 </listitem> 6.281 - <listitem><para id="x_20"><literal>date</literal>: La date et l'heure à 6.282 - laquelle le \textit{changeset a été créé, ainsi que le fuseau horaire dans 6.283 - laquelle il a été créé. <!--TODO: Translate 'timezone' properly : FUSEA -->. (La 6.284 - date et l'heure sont locales à ce \textit{fuseau}, elles indiquent donc quelle 6.285 - date et heure il était pour la personne qui a créé ce <!--%%%TODO: je suppose (quelle 6.286 - "heure") OUI --> changeset.</para> 6.287 + <listitem><para id="x_20"><literal>date</literal> : La date et l'heure à 6.288 + laquelle le \textit{changeset} a été créé, ainsi que le fuseau horaire dans 6.289 + lequelle il a été créé. (La date et l'heure sont locales à ce 6.290 + \textit{fuseau}, elles indiquent donc quelle date et heure il était 6.291 + pour la personne qui a créé ce changeset.</para> 6.292 </listitem> 6.293 - <listitem><para id="x_21"><literal>résumé</literal>: La première du 6.294 + <listitem><para id="x_21"><literal>résumé</literal>: La première ligne du 6.295 message que le créateur a associé à son changeset pour le décrire.</para> 6.296 </listitem> 6.297 - <!-- TODO: Missing items here ! --> 6.298 + <listitem><para id="x_67d">Certains changesets, comme le premier de la 6.299 + liste ci-dessus ont un champ <literal>tag</literal>. Le tag est une autre 6.300 + façon d'identifier un changeset en lui donnant un nom simple à retenir. 6.301 + (Le tag nommé <literal>tip</literal> est spécial : il fait toujours 6.302 + référence aux derniers changements dans le dépôt.)</para></listitem> 6.303 </itemizedlist> 6.304 6.305 <para id="x_22">Par défaut, la commande <command role="hg-cmd">hg log</command> 6.306 - n'affiche qu'un résumé, il manque 6.307 - beaucoup de détails.</para> 6.308 + n'affiche qu'un résumé, il manque beaucoup de détails.</para> 6.309 6.310 <para id="x_23">La figure <xref linkend="fig:tour-basic:history"/> fournit une 6.311 représentation graphique de l'historique du dépôt <filename class="directory">hello 6.312 @@ -245,23 +251,22 @@ 6.313 <sect2> 6.314 <title>Changesets, révisions, et collaboration</title> 6.315 6.316 - <para id="x_25">Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique 6.317 - est la source de bien des erreurs de terminologies (pourquoi utiliser un 6.318 - seul terme quand quatre feront l'affaire ?), la gestion de version a une 6.319 - variété de mots et de phrases qui veulent dire la même chose. Si vous 6.320 - discutez d'historique de Mercurial avec d'autres personnes, 6.321 -<!--%%%TODO: ça ne veut rien dire: il faut supprimer une des personnes : soit "quelqu'un", 6.322 -% soit "à d'autres personnes" --> 6.323 - vous constaterez que souvent le mot <quote>changeset</quote> est contracté simplement 6.324 - en <quote>change</quote> ou (à l'écrit) <quote>cset</quote>, et même parfois un 6.325 - changeset simplement <quote>révision</quote>, abrégé en <quote>rev</quote>.</para> 6.326 + <para id="x_25">Comme l'anglais est réputé pour être un langage maladroit, 6.327 + et que l'informatique est la source de bien des erreurs de terminologie 6.328 + (pourquoi utiliser un seul terme quand quatre feront l'affaire ?), la 6.329 + gestion de version a une variété de mots et de phrases qui veulent dire 6.330 + la même chose. Si vous discutez d'historique de Mercurial avec d'autres 6.331 + personnes, vous constaterez que souvent, le mot <quote>changeset</quote> 6.332 + est contracté simplement en <quote>change</quote> ou (à l'écrit) 6.333 + <quote>cset</quote>, et même parfois un changeset 6.334 + <quote>révision</quote>, abrégé en <quote>rev</quote>.</para> 6.335 6.336 <para id="x_26">Bien que le <emphasis>mot</emphasis> que vous utilisez pour 6.337 désigner le concept de changeset importe peu, l'<emphasis>identifiant</emphasis> 6.338 que vous utilisez pour désigner un <emphasis>changeset</emphasis> spécifique 6.339 a une grande importance. Rappelez vous que le champ changeset affiché par la 6.340 - commande <command role="hg-cmd">hg log</command> identifie un changeset à la fois avec 6.341 - un numéro de révision et une séquence hexadécimale.</para> 6.342 + commande <command role="hg-cmd">hg log</command> identifie un changeset à 6.343 + la fois avec un numéro de révision et une séquence hexadécimale.</para> 6.344 6.345 <itemizedlist> 6.346 <listitem><para id="x_27">Le numéro de révision est <emphasis>seulement 6.347 @@ -271,22 +276,21 @@ 6.348 pourra toujours être associé au changeset exact de <emphasis>chaque</emphasis> 6.349 copie de votre dépôt.</para></listitem></itemizedlist> 6.350 6.351 - <para id="x_29">La distinction est importante. Si vous envoyez un email 6.352 - à quelqu'un en parlant de la <quote>révision 33</quote>, il est très 6.353 - probable que sa révision 33 <emphasis>ne sera pas la même</emphasis> 6.354 - que la votre. La raison de ceci est que le numéro de révision dépend 6.355 - de l'ordre dans lequel les modifications sont arrivées dans le dépôt, 6.356 - et il n'y a aucune garantie que les mêmes changements soient arrivés 6.357 - dans le même ordre dans différents dépôts. Trois modifications 6.358 - <literal>a,b,c</literal> peuvent aisément apparaitre dans un dépôt 6.359 - comme <literal>0,1,2</literal>, et dans un autre comme <literal>0,2,1 6.360 - </literal>.</para> 6.361 - 6.362 - <para id="x_2a">Mercurial utilise les numéros de révision uniquement comme des raccourcis 6.363 - pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un, 6.364 - ou identifer un \textit{changeset} pour une quelquonque %%%TODO: our : "pour" ou "ou" 6.365 - raison (par exemple, un rapport de \textit{bug}), utilisez la séquence 6.366 - hexadécimale.</para> 6.367 + <para id="x_29">La distinction est importante. Si vous envoyez un email 6.368 + à quelqu'un en parlant de la <quote>révision 33</quote>, il est très 6.369 + probable que sa révision 33 <emphasis>ne sera pas la même</emphasis> 6.370 + que la votre. La raison de ceci est que le numéro de révision dépend 6.371 + de l'ordre dans lequel les modifications sont arrivées dans le dépôt, 6.372 + et il n'y a aucune garantie que les mêmes changements soient arrivés 6.373 + dans le même ordre dans différents dépôts. Trois modifications 6.374 + <literal>a,b,c</literal> peuvent aisément apparaitre dans un dépôt 6.375 + comme <literal>0,1,2</literal>, et dans un autre comme <literal>0,2,1 6.376 + </literal>.</para> 6.377 + 6.378 + <para id="x_2a">Mercurial utilise les numéros de révision uniquement comme des raccourcis 6.379 + pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un, 6.380 + ou identifer un \textit{changeset} pour une quelconque raison (par exemple, 6.381 + un rapport de \textit{bug}), utilisez la séquence hexadécimale.</para> 6.382 6.383 </sect2> 6.384 <sect2> 6.385 @@ -300,19 +304,17 @@ 6.386 6.387 &interaction.tour.log-r; 6.388 6.389 - <para id="x_2c">Si vous voulez voir l'historique de plusieurs 6.390 - révisions sans avoir à les énumérer, vous pouvez utiliser la 6.391 - <emphasis>intervalle de numérotation</emphasis> qui vous permet 6.392 - d'exprimer l'idée <quote>je veux toutes les révisions entre $a$ 6.393 - et $b$, inclus</quote>. 6.394 - 6.395 - &interaction.tour.log.range; 6.396 - 6.397 - <para id="x_2d">Mercurial respecte aussi l'ordre dans lequel 6.398 - vous spécifiez les révisions, ainsi 6.399 - <command role="hg-cmd">hg log -r 2:4</command> affichera 6.400 - <literal>2,3,4</literal> alors que <command role="hg-cmd">hg log -r 4:2</command> 6.401 - affichera <literal>4,3,2</literal>.</para> 6.402 + <para id="x_2c">Si vous voulez voir l'historique de plusieurs révisions 6.403 + sans avoir à les énumérer, vous pouvez utiliser la <emphasis>intervalle 6.404 + de numérotation</emphasis> qui vous permet d'exprimer l'idée <quote>je 6.405 + veux toutes les révisions entre $a$ et $b$, inclus</quote></para> 6.406 + 6.407 + &interaction.tour.log.range; 6.408 + 6.409 + <para id="x_2d">Mercurial respecte aussi l'ordre dans lequel vous spécifiez 6.410 + les révisions, ainsi <command role="hg-cmd">hg log -r 2:4</command> 6.411 + affichera <literal>2,3,4</literal> alors que <command role="hg-cmd">hg 6.412 + log -r 4:2</command> affichera <literal>4,3,2</literal>.</para> 6.413 6.414 </sect2> 6.415 <sect2> 6.416 @@ -322,15 +324,12 @@ 6.417 est suffisant si vous savez déjà ce que vous cherchez. En 6.418 revanche, vous aurez probablement besoin de voir une description 6.419 complète du changement, ou une liste des fichiers modifiés si vous 6.420 - cherchez à déterminer qu'un changeset est bien celui que vous <!-- 6.421 - %%%TODO: les propositions sont mal construites : après un "si...." il 6.422 - faut une proposition sans "si... donc ici : "si ... recherchez", ben 6.423 - quoi? --> 6.424 + cherchez à déterminer qu'un changeset est bien celui que vous 6.425 recherchez. L'option \hgopt{-v} de la commande <command role="hg-cmd">hg 6.426 log</command> (ou <option role="hp-opt-global">--verbose</option>) vous 6.427 donne ces informations supplémentaires.</para> 6.428 6.429 - &interaction.tour.log-v; --> 6.430 + &interaction.tour.log-v; 6.431 6.432 <para id="x_2f">Si vous voulez voir à la fois la description 6.433 et le contenu d'une modification, ajouter l'option <option 6.434 @@ -344,9 +343,8 @@ 6.435 6.436 &interaction.tour.log-vp; 6.437 6.438 - <para id="x_67e">L'option <option role="hg-opt-log">-p</option> option 6.439 - est incroyablement utile, il est donc important dans s'en 6.440 - rappeller.</para> 6.441 + <para id="x_67e">L'option <option role="hg-opt-log">-p</option> est 6.442 + incroyablement utile, il est donc important dans s'en rappeller.</para> 6.443 6.444 </sect2> 6.445 </sect1> 6.446 @@ -359,9 +357,8 @@ 6.447 utile pour la suite de notre parcours.</para> 6.448 6.449 <para id="x_31">Mercurial utilise une approche directe et cohérente 6.450 - pour interpréter <!--%%%TODO: une manière d'approche ?--> les 6.451 - options que vous passez aux commandes. Il suit une convention commune 6.452 - à la plupart des systèmes Unix et Linux modernes.</para> 6.453 + pour interpréter les options que vous passez aux commandes. Il suit une 6.454 + convention commune à la plupart des systèmes Unix et Linux modernes.</para> 6.455 6.456 <itemizedlist> 6.457 <listitem><para id="x_32">Chaque option a un nom complet. Par exemple, 6.458 @@ -401,13 +398,12 @@ 6.459 <note> 6.460 <title>Option naming consistency</title> 6.461 6.462 - <para id="x_680">Presque toujours, les commandes de Mercurial utilise 6.463 + <para id="x_680">Presque toujours, les commandes de Mercurial utilisent 6.464 des noms d'options cohérentes pour référer à des concepts identiques. 6.465 Par exemple, si une commande concerne les changesets, vous les 6.466 - identifierais toujours avec l'option <option 6.467 - role="hg-opt-log">-r</option>. Cette utilisation cohérente des noms 6.468 - d'options permet de mémoriser plus facilement quelles options accepte 6.469 - une commande.</para> 6.470 + identifierez toujours avec l'option <option role="hg-opt-log">-r</option>. 6.471 + Cette utilisation cohérente des noms d'options permet de mémoriser plus 6.472 + facilement quelles options accepte une commande.</para> 6.473 </note> 6.474 6.475 6.476 @@ -419,226 +415,229 @@ 6.477 commandes pour consulter l'historique de Mercurial, regardons 6.478 comment faire des modifications et les examiner.</para> 6.479 6.480 - <para id="x_39">La première chose que nous allons faire 6.481 - c'est isoler notre expérience dans un dépôt à part. Nous 6.482 - allons utiliser la commande <command role="hg-cmd">hg 6.483 - clone</command>, mais nous n'avons pas besoin de faire une 6.484 - copie de dépôt distant. Comme nous avons déjà une copie locale, 6.485 - nous pouvons juste faire un clone de celle-ci à la place. C'est 6.486 - beaucoup plus rapide que de faire une copie à travers le réseau, 6.487 - et un dépôt cloné localement prend également moins d'espace 6.488 - disque.<footnote></footnote> 6.489 - <para id="x_681">L'économie d'espace disque apparait clairement 6.490 - quand les dépôts source et destination sont sur le même système 6.491 - de fichier, où dans ce cas, Mercurial utilisera des liens physiques 6.492 - pour effectuer des partages copie-lors-des-écritures de ses 6.493 - métadonnées internes. Si cette explication ne signifie rien pour 6.494 - vous, ne vous inquietez pas: tout ceci se passe de manière 6.495 - transparente et automatiquement, et vous n'avez pas du tout 6.496 - besoin de comprendre ceci.</para> 6.497 - </footnote>.</para> 6.498 - 6.499 - &interaction.tour.reclone; 6.500 - 6.501 - <para id="x_3a">On notera au passage qu'il est souvent considéré 6.502 - comme une bonne pratique de conserver une copie <quote>immaculée</quote> 6.503 - du dépôt distant, à partir de laquelle vous pourrez faire des 6.504 - copies locales temporaires pour créer des <quote>bacs à sable</quote> 6.505 - pour chaque tâche sur laquelle vous souhaitez travailler. Ceci 6.506 - vous permet de travailler sur plusieurs choses en parallèle, 6.507 - chacune isolée les unes des autres en attendant que ces tâches 6.508 - soient finies et que vous soyez prêt à les réintégrer. Parce 6.509 - que les copies locales sont peu coûteuses, il est très rapide 6.510 - de créer ou détruire des dépôts dès que vous en avez besoin. 6.511 - </para> 6.512 - 6.513 - <para id="x_3b">Dans notre <filename class="directory">my-hello 6.514 - </filename> dépôts, nous avons un fichier <filename>hello.c 6.515 - </filename> qui contient le classique <quote>hello, world</quote>. 6.516 - </para> 6.517 - 6.518 - &interaction.tour.cat1; 6.519 - 6.520 - <para id="x_682">Editons ce fichier pour qu'il affiche une autre 6.521 - ligne sur la sortie standard.</para> 6.522 - 6.523 - &interaction.tour.cat2; 6.524 - 6.525 - <para id="x_3c">La commande Mercurial <command role="hg-cmd">hg status 6.526 - </command> nous dira ce que Mercurial sait des fichiers du dépôts. 6.527 - </para> 6.528 - 6.529 - &interaction.tour.status; 6.530 - 6.531 - <para id="x_3d">La commande <command role="hg-cmd">hg status</command> 6.532 - n'affichera pas le contenu des fichiers, mais une ligne commençant 6.533 - par <quote><literal>M</literal></quote> pour <filename>hello.c 6.534 - </filename>. A moins que vous lui demandiez, la commande <command 6.535 - role="hg-cmd">hg status</command> n'affichera aucune informations 6.536 - sur les fichiers que vous n'avez pas modifié.</para> 6.537 - 6.538 - <para id="x_3d">Le <quote><literal>M</literal></quote> indique que 6.539 - Mercurial a remarqué que nous avons modifié le fichier 6.540 - <filename>hello.c</filename>. Nous n'avons pas besoin 6.541 - <emphasis>d'informer</emphasis> Mercurial que nous allons modifier le 6.542 - fichier avant de commencer à le faire, ou que nous avions modifier le 6.543 - fichier avant de le faire, il est capable de découvrir ça tout seul. 6.544 - </para> 6.545 - 6.546 - <para id="x_3f">C'est déjà pratique de savoir que nous avons modifié le 6.547 - fichier <filename>hello.c</filename>, mais nous préférerions savoir 6.548 - exactement <emphasis>ce que</emphasis> nous avons changé. Pour ceci, nous 6.549 - utilisons la commande <command role="hg-cmd">hg diff</command>.</para> 6.550 - 6.551 - &interaction.tour.diff; 6.552 - 6.553 - <tip> 6.554 - <title>Comprendre les patches</title> 6.555 - 6.556 - <para id="x_683">Penser à jeter un oeil au site <xref 6.557 - linkend="sec:mq:patch"/> si vous n'arrivez pas à lire la sortie 6.558 - ci-dessus.</para> 6.559 - </tip> 6.560 - </sect1> 6.561 - <sect1> 6.562 - <title>Enregister vos modifications dans une nouvelle révision</title> 6.563 - 6.564 - <para id="x_40">Nous pouvons modifier des fichiers, compiler et 6.565 - tester nos modifications, et utiliser les commandes 6.566 - <command role="hg-cmd">hg status</command> et <command role="hg-cmd">hg 6.567 - diff</command> pour voir les modifications effectuées, jusqu'au 6.568 - moment où nous serons assez satisfaits 6.569 - pour décider d'enregistrer notre travail dans un \textit{changeset}. 6.570 - </para> 6.571 - 6.572 - <para id="x_41">La commande <command role="hg-cmd">hg commit</command> 6.573 - vous laisse créer une nouvelle révision, nous désignerons généralement 6.574 - cette opération par <quote>faire un commit</quote> ou <quote>committer 6.575 - </quote>.</para> 6.576 - 6.577 - <sect2> 6.578 - <title>Définir le nom d'utilisateur</title> 6.579 - 6.580 - <para id="x_42">Quand vous exécutez la commande <command role="hg-cmd"> 6.581 - hg commit</command> pour la première fois, il n'est pas garanti 6.582 - qu'elle réussisse du premier coup. En effet, Mercurial enregistre 6.583 - votre nom et votre adresse avec chaque modification que vous effectuez, 6.584 - de manière à ce que vous soyez capable (ou d'autres le soient) de 6.585 - savoir qui a fait quelle modification. Mercurial essaye automatiquement 6.586 - de découvrir un nom d'utilisateur qui ait un minimum de sens 6.587 - pour effectuer l'opération de commit avec. Il va essayer chacune 6.588 - des méthodes suivantes, dans l'ordre:</para> 6.589 - <orderedlist> 6.590 - <listitem><para id="x_43">Si vous spécifiez l'option <option 6.591 - role="hg-opt-commit">-u</option> avec la commande 6.592 - <command role="hg-cmd">hg commit</command>, suivi d'un nom 6.593 - d'utilisateur, ceci aura toujours la priorité sur les autres 6.594 - méthodes ci dessous.</para></listitem> 6.595 - <listitem><para id="x_44">Si vous avez défini une variable d'environnement 6.596 - <envar>HGUSER</envar>, c'est cette valeur qui est alors utilisée.</para></listitem> 6.597 - <listitem><para id="x_45">Si vous créez un fichier nommé 6.598 - <filename role="special">.hgrc</filename> dans votre 6.599 - répertoire \textit{home}, avec une entrée <envar 6.600 - role="rc-item-ui">username</envar>, c'est la valeur associée 6.601 - qui sera utilisée. Pour voir à quoi ressemble le contenu de ce fichier 6.602 - regardez la section <xref linkend="sec:tour-basic:username"/> 6.603 - ci-dessous.</para></listitem> 6.604 - <listitem><para id="x_46">Si vous avez défini une variable 6.605 - d'environnement <envar>EMAIL</envar> celle ci sera utilisée ensuite.</para></listitem> 6.606 - <listitem><para id="x_47">Enfin, Mercurial interrogera votre système pour 6.607 - trouver votre nom d'utilisateur local ainsi que le nom de la machine hôte, 6.608 - et il fabriquera un nom d'utilisateur à partir de ces données. Comme 6.609 - il arrive souvent que ce genre de noms soit totalement inutile, il vous 6.610 - préviendra en affichant un message d'avertissement.</para></listitem> 6.611 - </orderedlist> 6.612 - 6.613 - <para id="x_48">Si tous ces mécanismes échouent, Mercurial n'exécutera pas 6.614 - la commande, affichant un message d'erreur. Dans ce cas, il ne vous 6.615 - laissera pas effectuer de commit tant que vous n'aurez pas défini un nom 6.616 - d'utilisateur.</para> 6.617 - 6.618 - <para id="x_49">Vous devriez penser à utiliser la variable d'environement 6.619 - <envar>HGUSER</envar> et l'option <option role="hg-opt-commit">-u 6.620 - </option> comme moyen pour <emphasis>changer</emphasis> le nom d' 6.621 - utilisateur} par défaut. Pour une utilisation normale, la manière la 6.622 - plus simple et robuste d'opérer est de créer un fichier 6.623 - <filename role="special">.hgrc</filename>, voir ci-dessous pour 6.624 - les détails à ce sujet.</para> 6.625 - 6.626 - <sect3 id="sec:tour-basic:username"> 6.627 - <title>Créer un fichier de configuration pour Mercurial</title> 6.628 - 6.629 - <para id="x_4a">Pour définir un nom d'utilisateur, utilisez votre 6.630 - éditeur de texte favori pour créer un fichier <filename 6.631 - role="special">.hgrc</filename> dans votre répertoire home. 6.632 - Mercurial va utiliser ce fichier pour retrouver votre 6.633 - configuration personnelle. Le contenu initial devrait 6.634 - ressembler à ceci:</para> 6.635 - 6.636 - <tip> 6.637 - <title><quote>Home directory</quote> on Windows</title> 6.638 + <para id="x_39">La première chose que nous allons faire c'est isoler notre 6.639 + expérience dans un dépôt à part. Nous allons utiliser la commande <command 6.640 + role="hg-cmd">hg clone</command>, mais nous n'avons pas besoin de faire 6.641 + une copie de dépôt distant. Comme nous avons déjà une copie locale, nous 6.642 + pouvons juste faire un clone de celle-ci à la place. C'est beaucoup plus 6.643 + rapide que de faire une copie à travers le réseau, et un dépôt cloné 6.644 + localement prend également moins d'espace disque<footnote> 6.645 + <para id="x_681">L'économie d'espace disque apparait clairement quand les 6.646 + dépôts source et destination sont sur le même système de fichier, où, dans 6.647 + ce cas, Mercurial utilisera des liens physiques pour effectuer des partages 6.648 + copie-lors-des-écritures de ses métadonnées internes. Si cette explication 6.649 + ne signifie rien pour vous, ne vous inquietez pas : tout ceci se passe de 6.650 + manière transparente et automatiquement. Vous n'avez pas du tout besoin de 6.651 + comprendre ceci.</para></footnote>.</para> 6.652 + 6.653 + &interaction.tour.reclone; 6.654 + 6.655 + <para id="x_3a">On notera au passage qu'il est souvent considéré comme 6.656 + une bonne pratique de conserver une copie <quote>immaculée</quote> 6.657 + du dépôt distant, à partir de laquelle vous pourrez faire des 6.658 + copies locales temporaires pour créer des <quote>bacs à sable</quote> 6.659 + pour chaque tâche sur laquelle vous souhaitez travailler. Ceci 6.660 + vous permet de travailler sur plusieurs choses en parallèle, 6.661 + chacune isolée les unes des autres en attendant que ces tâches 6.662 + soient finies et que vous soyez prêt à les réintégrer. Parce 6.663 + que les copies locales sont peu coûteuses, il est très rapide 6.664 + de créer ou détruire des dépôts dès que vous n'en avez plus 6.665 + besoin.</para> 6.666 + 6.667 + <para id="x_3b">Dans notre dépôt <filename 6.668 + class="directory">my-hello</filename>, nous avons un fichier 6.669 + <filename>hello.c</filename> qui contient le classique <quote>hello, 6.670 + world</quote>.</para> 6.671 + 6.672 + &interaction.tour.cat1; 6.673 + 6.674 + <para id="x_682">Editons ce fichier pour qu'il affiche une autre ligne 6.675 + sur la sortie standard.</para> 6.676 + 6.677 + &interaction.tour.cat2; 6.678 + 6.679 + <para id="x_3c">La commande Mercurial <command role="hg-cmd">hg 6.680 + status</command> nous dira ce que Mercurial sait des fichiers du 6.681 + dépôts.</para> 6.682 + 6.683 + &interaction.tour.status; 6.684 + 6.685 + <para id="x_3d">La commande <command role="hg-cmd">hg status</command> 6.686 + n'affichera pas le contenu des fichiers, mais une ligne commençant par 6.687 + <quote><literal>M</literal></quote> pour <filename>hello.c</filename>. 6.688 + A moins que vous lui demandiez, la commande <command role="hg-cmd">hg 6.689 + status</command> n'affichera aucune information sur les fichiers que 6.690 + vous n'avez pas modifiés.</para> 6.691 + 6.692 + <para id="x_3d">Le <quote><literal>M</literal></quote> indique que 6.693 + Mercurial a remarqué que nous avons modifié le fichier 6.694 + <filename>hello.c</filename>. Nous n'avons pas besoin 6.695 + <emphasis>d'informer</emphasis> Mercurial que nous allons modifier un 6.696 + fichier avant de commencer à le faire, ou que nous avons modifié un 6.697 + fichier après avoir commencé à le faire, il est capable de découvrir ça 6.698 + tout seul. </para> 6.699 + 6.700 + <para id="x_3f">C'est déjà pratique de savoir que nous avons modifié le 6.701 + fichier <filename>hello.c</filename>, mais nous préférerions savoir 6.702 + exactement <emphasis>ce que</emphasis> nous avons changé. Pour ceci, nous 6.703 + utilisons la commande <command role="hg-cmd">hg diff</command>.</para> 6.704 + 6.705 + &interaction.tour.diff; 6.706 + 6.707 + <tip> 6.708 + <title>Comprendre les patches</title> 6.709 + 6.710 + <para id="x_683">Penser à jeter un oeil à <xref 6.711 + linkend="sec:mq:patch"/> si vous n'arrivez pas à lire la sortie 6.712 + ci-dessus.</para> 6.713 + </tip> 6.714 + </sect1> 6.715 + <sect1> 6.716 + <title>Enregister vos modifications dans une nouvelle révision</title> 6.717 + 6.718 + <para id="x_40">Nous pouvons modifier des fichiers, compiler et tester 6.719 + nos modifications, et utiliser les commandes <command role="hg-cmd">hg 6.720 + status</command> et <command role="hg-cmd">hg diff</command> pour 6.721 + voir les modifications effectuées, jusqu'à ce que nous soyons assez 6.722 + satisfaits pour décider d'enregistrer notre travail dans un 6.723 + \textit{changeset}.</para> 6.724 + 6.725 + <para id="x_41">La commande <command role="hg-cmd">hg commit</command> 6.726 + vous laisse créer une nouvelle révision, nous désignerons généralement 6.727 + cette opération par <quote>faire un commit</quote> ou 6.728 + <quote>committer</quote>.</para> 6.729 + 6.730 + <sect2> 6.731 + <title>Définir le nom d'utilisateur</title> 6.732 + 6.733 + <para id="x_42">Quand vous exécutez la commande <command 6.734 + role="hg-cmd">hg commit</command> pour la première fois, il n'est 6.735 + pas garanti qu'elle réussisse du premier coup. En effet, Mercurial 6.736 + enregistre votre nom et votre adresse avec chaque modification que 6.737 + vous effectuez, de manière à ce que vous soyez capable (ou d'autres 6.738 + le soient) de savoir qui a fait quelle modification. Mercurial essaye 6.739 + automatiquement de découvrir un nom d'utilisateur qui ait un minimum 6.740 + de sens pour effectuer l'opération de commit avec. Il va essayer 6.741 + chacune des méthodes suivantes, dans l'ordre :</para> 6.742 + 6.743 + <orderedlist> 6.744 + <listitem><para id="x_43">Si vous spécifiez l'option <option 6.745 + role="hg-opt-commit">-u</option> avec la commande <command 6.746 + role="hg-cmd">hg commit</command>, suivi d'un nom 6.747 + d'utilisateur, ceci aura toujours la priorité sur les autres 6.748 + méthodes ci dessous.</para></listitem> 6.749 + <listitem><para id="x_44">Si vous avez défini une variable 6.750 + d'environnement <envar>HGUSER</envar>, c'est cette valeur qui est 6.751 + alors utilisée.</para></listitem> 6.752 + <listitem><para id="x_45">Si vous créez un fichier nommé <filename 6.753 + role="special">.hgrc</filename> dans votre répertoire 6.754 + \textit{home}, avec une entrée <envar 6.755 + role="rc-item-ui">username</envar>, c'est la valeur associée 6.756 + qui sera utilisée. Pour voir à quoi ressemble le contenu de ce 6.757 + fichier regardez la section <xref 6.758 + linkend="sec:tour-basic:username"/> 6.759 + ci-dessous.</para></listitem> 6.760 + <listitem><para id="x_46">Si vous avez défini une variable 6.761 + d'environnement <envar>EMAIL</envar> celle ci sera utilisée 6.762 + ensuite.</para></listitem> 6.763 + <listitem><para id="x_47">Enfin, Mercurial interrogera votre système 6.764 + pour trouver votre nom d'utilisateur local ainsi que le nom de la 6.765 + machine hôte, et il fabriquera un nom d'utilisateur à partir de 6.766 + ces données. Comme il arrive souvent que ce genre de noms soit 6.767 + totalement inutile, il vous préviendra en affichant un message 6.768 + d'avertissement.</para></listitem> 6.769 + </orderedlist> 6.770 + 6.771 + <para id="x_48">Si tous ces mécanismes échouent, Mercurial n'exécutera 6.772 + pas la commande, affichant un message d'erreur. Dans ce cas, il ne 6.773 + vous laissera pas effectuer de commit tant que vous n'aurez pas 6.774 + défini un nom d'utilisateur.</para> 6.775 + 6.776 + <para id="x_49">Vous devriez penser à utiliser la variable 6.777 + d'environement <envar>HGUSER</envar> et l'option <option 6.778 + role="hg-opt-commit">-u</option> comme moyen pour 6.779 + <emphasis>changer</emphasis> le nom d'utilisateur par défaut. Pour 6.780 + une utilisation normale, la manière la plus simple et robuste 6.781 + d'opérer est de créer un fichier <filename 6.782 + role="special">.hgrc</filename>, voir ci-dessous pour les détails 6.783 + à ce sujet.</para> 6.784 + 6.785 + <sect3 id="sec:tour-basic:username"> 6.786 + <title>Créer un fichier de configuration pour Mercurial</title> 6.787 + 6.788 + <para id="x_4a">Pour définir un nom d'utilisateur, utilisez votre 6.789 + éditeur de texte favori pour créer un fichier <filename 6.790 + role="special">.hgrc</filename> dans votre répertoire home. 6.791 + Mercurial va utiliser ce fichier pour retrouver votre 6.792 + configuration personnelle. Le contenu initial devrait 6.793 + ressembler à ceci :</para> 6.794 + 6.795 + <tip> 6.796 + <title><quote>Home directory</quote> sous Windows</title> 6.797 + 6.798 + <para id="x_716">Quand on parle de répertoire home, sur une version 6.799 + anglaise d'une installation de Windows, il s'agira habituellement 6.800 + d'un répertoire nommée comme votre nom dans <filename>C:\Documents 6.801 + and Settings</filename>. Vous pouvez trouver de quelle répertoire 6.802 + il s'agit en lançant une fenêtre d'interpréteur de commande et en 6.803 + exécutant la commande suivante :</para> 6.804 6.805 - <para id="x_716">Quand on parle de répertoire home, sur une version 6.806 - anglaise d'une installation de Windows, il s'agira habituellement 6.807 - d'un répertoire nommée comme votre nom dans <filename>C:\Documents 6.808 - and Settings</filename>. Vous pouvez trouver de quelle répertoire 6.809 - il s'agit en lançant une fenêtre d'interpréteur de commande et en 6.810 - exécutant la commande suivante:</para> 6.811 - <screen><prompt>C:\</prompt> <userinput>echo %UserProfile</userinput></screen> 6.812 - </tip> 6.813 - 6.814 - <programlisting># This is a Mercurial configuration file. 6.815 + <screen><prompt>C:\</prompt> <userinput>echo 6.816 + %UserProfile</userinput></screen> 6.817 + </tip> 6.818 + 6.819 + <programlisting># This is a Mercurial configuration file. 6.820 [ui] 6.821 username = Firstname Lastname <email.address@domain.net></programlisting> 6.822 6.823 - <para id="x_4b">La ligne avec <literal>[ui]</literal> commence une 6.824 - <emphasis>section</emphasis> du fichier de configuration, ainsi la ligne 6.825 - <quote><literal>username = ...</literal></quote> signifie <quote> 6.826 - définir la valeur de l'élément <literal>username</literal> dans la 6.827 - section <literal>ui</literal></quote>. Une section continue jusqu'à ce 6.828 - qu'une nouvelle commence, ou que la fin du fichier soit atteinte. 6.829 - Mercurial ignore les lignes vides et traite tout texte situé à la suite 6.830 - d'un <quote><literal>#</literal></quote> jusqu'à la fin de la ligne 6.831 - comme un commentaire.</para> 6.832 + <para id="x_4b">La ligne avec <literal>[ui]</literal> commence une 6.833 + <emphasis>section</emphasis> du fichier de configuration, ainsi la ligne 6.834 + <quote><literal>username = ...</literal></quote> signifie <quote> 6.835 + définir la valeur de l'élément <literal>username</literal> dans la 6.836 + section <literal>ui</literal></quote>. Une section continue jusqu'à ce 6.837 + qu'une nouvelle commence, ou que la fin du fichier soit atteinte. 6.838 + Mercurial ignore les lignes vides et traite tout texte situé à la suite 6.839 + d'un <quote><literal>#</literal></quote> jusqu'à la fin de la ligne 6.840 + comme un commentaire.</para> 6.841 6.842 </sect3> 6.843 <sect3> 6.844 <title>Choisir un nom d'utilisateur</title> 6.845 - 6.846 - <para id="x_4c">Vous pouvez utiliser n'importe quelle valeur 6.847 - pour votre <literal>username</literal>, car cette information 6.848 - est destinée à d'autres personnes et non à être interprétée 6.849 - par Mercurial. La convention que la plupart des personnes 6.850 - suivent est d'utiliser leurs noms suivies de leurs adresses emails, 6.851 - comme montrée ci-dessus:</para> 6.852 - <note> 6.853 - <para id="x_4d">Le mécanisme interne du serveur web intégré à Mercurial, 6.854 - masque les adresses emails, pour rendre plus difficile leurs 6.855 - récupérations par les outils utilisés par les spammmers. 6.856 - Ceci réduit la probabilité que de recevoir encore plus de 6.857 - spam si vous vous publiez un dépôt sur internet.</para> 6.858 - </note> 6.859 - </sect3> 6.860 - </sect2> 6.861 - <sect2> 6.862 - <title>Rédiger un message de \textit{commit}</title> 6.863 - 6.864 - <para id="x_4e">Lorsqu'on effectue une opération de commit, Mercurial 6.865 - lance automatiquement un éditeur de texte pour permettre de saisir 6.866 - un message qui décrira les modifications effectuées dans cette 6.867 - révision. Ce message est nommé le <emphasis>message de commit</emphasis>. 6.868 - Ce sera un enregistrement pour tout lecteur expliquant le pourquoi 6.869 - et le comment de vos modifications, et il sera affiché par la 6.870 - commande <command role="hg-cmd">hg log</command>.</para> 6.871 - 6.872 - &interaction.tour.commit; 6.873 - 6.874 - <para id="x_4f">L'éditeur que la commande <command role="hg-cmd">hg 6.875 - commit</command> déclenche ne contiendra qu'une ligne vide suivi 6.876 - d'un certain nombre de lignes commençant par <quote><literal>HG: 6.877 - </literal></quote>.</para> 6.878 - 6.879 - <programlisting> 6.880 + 6.881 + <para id="x_4c">Vous pouvez utiliser n'importe quelle valeur 6.882 + pour votre <literal>username</literal>, car cette information 6.883 + est destinée à d'autres personnes et non à être interprétée 6.884 + par Mercurial. La convention que la plupart des personnes 6.885 + suivent est d'utiliser leurs noms suivies de leurs adresses emails, 6.886 + comme montré ci-dessus :</para> 6.887 + <note> 6.888 + <para id="x_4d">Le mécanisme interne du serveur web intégré à Mercurial, 6.889 + masque les adresses emails, pour rendre plus difficile leurs 6.890 + récupérations par les outils utilisés par les spammmers. 6.891 + Ceci réduit la probabilité que de recevoir encore plus de 6.892 + spam si vous vous publiez un dépôt sur internet.</para> 6.893 + </note> 6.894 + </sect3> 6.895 + </sect2> 6.896 + <sect2> 6.897 + <title>Rédiger un message de \textit{commit}</title> 6.898 + 6.899 + <para id="x_4e">Lorsqu'on effectue une opération de commit, Mercurial 6.900 + lance automatiquement un éditeur de texte pour permettre de saisir 6.901 + un message qui décrira les modifications effectuées dans cette 6.902 + révision. Ce message est nommé le <emphasis>message de commit</emphasis>. 6.903 + Ce sera un enregistrement pour tout lecteur expliquant le pourquoi 6.904 + et le comment de vos modifications, et il sera affiché par la 6.905 + commande <command role="hg-cmd">hg log</command>.</para> 6.906 + 6.907 + &interaction.tour.commit; 6.908 + 6.909 + <para id="x_4f">L'éditeur que la commande <command role="hg-cmd">hg 6.910 + commit</command> déclenche ne contiendra qu'une ligne vide suivi 6.911 + d'un certain nombre de lignes commençant par <quote><literal>HG: 6.912 + </literal></quote>.</para> 6.913 + 6.914 + <programlisting> 6.915 This is where I type my commit comment. 6.916 6.917 HG: Enter commit message. Lines beginning with 'HG:' are removed. 6.918 @@ -648,87 +647,90 @@ 6.919 HG: changed hello.c</programlisting> 6.920 6.921 6.922 - <para id="x_50">Mercurial ignore les lignes qui commencent 6.923 - avec <quote><literal>HG:</literal></quote>, il ne les 6.924 - utilise que pour nous indiquer quels fichiers modifiés il se 6.925 - prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a 6.926 - aucune conséquence sur l'opération de commit. 6.927 - </para> 6.928 - 6.929 - </sect2> 6.930 - <sect2> 6.931 - <title>Rédiger un message \textit{approprié}</title> 6.932 - 6.933 - <para id="x_51">Comme <command role="hg-cmd">hg log</command> n'affiche 6.934 - que la première ligne du message de commit par défaut, il est souvent 6.935 - considéré comme une bonne pratique de rédiger des messages de commit 6.936 - qui tiennent sur une seule ligne. Voilà un exemple concret de message 6.937 - de commit qui <emphasis>ne suit pas</emphasis> cette directive, et qui a donc 6.938 - un résumé peu lisible.</para> 6.939 - 6.940 - <programlisting> 6.941 + <para id="x_50">Mercurial ignore les lignes qui commencent 6.942 + avec <quote><literal>HG:</literal></quote>, il ne les 6.943 + utilise que pour nous indiquer quels fichiers modifiés il se 6.944 + prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a 6.945 + aucune conséquence sur l'opération de commit. 6.946 + </para> 6.947 + 6.948 + </sect2> 6.949 + <sect2> 6.950 + <title>Rédiger un message \textit{approprié}</title> 6.951 + 6.952 + <para id="x_51">Comme <command role="hg-cmd">hg log</command> n'affiche 6.953 + que la première ligne du message de commit par défaut, il est souvent 6.954 + considéré comme une bonne pratique de rédiger des messages de commit 6.955 + qui tiennent sur une seule ligne. Voilà un exemple concret de message 6.956 + de commit qui <emphasis>ne suit pas</emphasis> cette directive, et 6.957 + qui a donc un résumé peu lisible.</para> 6.958 + 6.959 + <programlisting> 6.960 changeset: 73:584af0e231be 6.961 user: Censored Person <censored.person@example.org> 6.962 date: Tue Sep 26 21:37:07 2006 -0700 6.963 summary: include buildmeister/commondefs. Add an exports and install 6.964 - </programlisting> 6.965 - 6.966 - <para id="x_52">A ce sujet, il faut noter qu'il n'existe pas de règle 6.967 - absolue dans ce domaine. Mercurial lui-même n'interprète pas les 6.968 - contenus des messages de commit, ainsi votre projet est libre de 6.969 - concevoir différentes politiques de mise en page des messages.</para> 6.970 - <para id="x_53">Ma préférence personnelle va au message court, mais 6.971 - informatif, qui offre des précisions supplémentaires par rapport à ce 6.972 - que pourrait m'apprendre une commande <command role="hg-cmd">hg log 6.973 - --patch</command>.</para> 6.974 - <para id="x_55">Si vous exécutez la commande <command role="hg-cmd">hg 6.975 - commit</command> sans aucun argument, elle enregistre tout les 6.976 - changements qui ont été fait, et qui sont indiqué par les commandes 6.977 - <command role="hg-cmd">hg status</command> et <command 6.978 - role="hg-cmd">hg diff</command>.</para> 6.979 - <note> 6.980 - <title>Une surprise pour les utilisateurs habitués à Subversion</title> 6.981 - 6.982 - <para id="x_717">Comme n'importe quel autre commande de Mercurial, si 6.983 - vous soumettez pas de manière explicite les noms des fichiers à 6.984 - committer à la commande <command role="hg-cmd">hg commit</command>, elle 6.985 - va travailler sur l'ensemble du répertoire de travail. Soyez conscient 6.986 - de ceci si vous venez du monde Subversion ou CVS, car vous pourriez 6.987 - attendre qu'elle opère uniquement le répertoire courant et ses sous 6.988 - répertoires.</para> 6.989 - </note> 6.990 - </sect2> 6.991 - <sect2> 6.992 - <title>Annuler un \textit{commit}</title> 6.993 + </programlisting> 6.994 + 6.995 + <para id="x_52">A ce sujet, il faut noter qu'il n'existe pas de règle 6.996 + absolue dans ce domaine. Mercurial lui-même n'interprète pas les 6.997 + contenus des messages de commit, ainsi votre projet est libre de 6.998 + concevoir différentes politiques de mise en page des messages.</para> 6.999 + 6.1000 + <para id="x_53">Ma préférence personnelle va au message court, mais 6.1001 + informatif, qui offre des précisions supplémentaires par rapport à ce 6.1002 + que pourrait m'apprendre une commande <command role="hg-cmd">hg log 6.1003 + --patch</command>.</para> 6.1004 + 6.1005 + <para id="x_55">Si vous exécutez la commande <command role="hg-cmd">hg 6.1006 + commit</command> sans aucun argument, elle enregistre tous les 6.1007 + changements qui ont été fait, et qui sont indiqué par les commandes 6.1008 + <command role="hg-cmd">hg status</command> et <command 6.1009 + role="hg-cmd">hg diff</command>.</para> 6.1010 + 6.1011 + <note> 6.1012 + <title>Une surprise pour les utilisateurs habitués à Subversion</title> 6.1013 + 6.1014 + <para id="x_717">Comme n'importe quel autre commande de Mercurial, si 6.1015 + vous soumettez pas de manière explicite les noms des fichiers à 6.1016 + committer à la commande <command role="hg-cmd">hg commit</command>, elle 6.1017 + va travailler sur l'ensemble du répertoire de travail. Soyez conscient 6.1018 + de ceci si vous venez du monde Subversion ou CVS, car vous pourriez 6.1019 + attendre qu'elle opère uniquement le répertoire courant et ses sous 6.1020 + répertoires.</para> 6.1021 + </note> 6.1022 + </sect2> 6.1023 + <sect2> 6.1024 + <title>Annuler un \textit{commit}</title> 6.1025 6.1026 <para id="x_54">Si, en rédigeant le message, vous décidez que 6.1027 finalement vous ne voulez pas effectuer ce commit, il suffit 6.1028 de quitter simplement l'éditeur sans sauver. Ceci n'aura aucune 6.1029 conséquence sur le dépôt ou les fichiers du répertoire de 6.1030 travail.</para> 6.1031 - </sect2> 6.1032 - 6.1033 - <sect2> 6.1034 - <sect2> 6.1035 - <title>Admirer votre travail</title> 6.1036 - 6.1037 - <para id="x_56">Une fois que votre \textit{commit} est terminé, vous pouvez utiliser 6.1038 - la commande <command role="hg-cmd">hg tip</command> pour afficher le \textit{changeset} que nous 6.1039 - venons de créer. Cette commande produit une sortie à l'écran qui est 6.1040 - identique à celle du <command role="hg-cmd">hg log</command>, mais qui n'affiche que la dernière 6.1041 - révision du dépôt.</para> 6.1042 - 6.1043 - &interaction.tour.tip; 6.1044 - 6.1045 - <para id="x_57">On fait couramment référence à la dernière révision 6.1046 - du dépôt comme étant la <emphasis>révision tip</emphasis>, ou plus 6.1047 - simplement le <emphasis>tip</emphasis>.</para> 6.1048 - 6.1049 - <para id="x_684">Au passage, la commande <command role="hg-cmd">hg 6.1050 - tip</command> accepte la plupart des mêmes options que 6.1051 - <command role="hg-cmd">hg log</command>, ainsi <option 6.1052 - role="hg-opt-global">-v</option> ci dessus inplique <quote>soit 6.1053 - verbeux</quote>, <option role="hg-opt-tip">-p</option> 6.1054 + </sect2> 6.1055 + 6.1056 + <sect2> 6.1057 + <title>Admirer votre travail</title> 6.1058 + 6.1059 + <para id="x_56">Une fois que votre \textit{commit} est terminé, vous 6.1060 + pouvez utiliser la commande <command role="hg-cmd">hg tip</command> 6.1061 + pour afficher le \textit{changeset} que vous venez de créer. Cette 6.1062 + commande produit une sortie à l'écran qui est identique à celle du 6.1063 + <command role="hg-cmd">hg log</command>, mais qui n'affiche que la 6.1064 + dernière révision du dépôt.</para> 6.1065 + 6.1066 + &interaction.tour.tip; 6.1067 + 6.1068 + <para id="x_57">On fait couramment référence à la dernière révision 6.1069 + du dépôt comme étant la <emphasis>révision tip</emphasis>, ou plus 6.1070 + simplement le <emphasis>tip</emphasis>.</para> 6.1071 + 6.1072 + <para id="x_684">Au passage, la commande <command role="hg-cmd">hg 6.1073 + tip</command> accepte la plupart des options qu'accepte 6.1074 + <command role="hg-cmd">hg log</command>. Ainsi <option 6.1075 + role="hg-opt-global">-v</option> ci dessus implique <quote>soit 6.1076 + verbeux</quote>, <option role="hg-opt-tip">-p</option> 6.1077 veux dire <quote>affiche le patch</quote>. L'utilisation de l'option 6.1078 <option role="hg-opt-tip">-p</option> pour afficher un patch est un 6.1079 autre exemple de la cohérence des commandes évoquée plus tôt.</para> 6.1080 @@ -739,267 +741,272 @@ 6.1081 <title>Partager ses modifications</title> 6.1082 6.1083 <para id="x_58">Nous avons mentionné plus haut que les dépôts 6.1084 - de Mercurial sont autosuffisants. Ce qui signifie que la nouvelle 6.1085 - révision que vous venez de créer n'existe seulement dans votre 6.1086 - répertoire <filename class="directory">my-hello</filename>. Étudions 6.1087 - comment propager cette modification dans d'autres dépôts.</para> 6.1088 + de Mercurial sont autosuffisants. Ce qui signifie que la nouvelle 6.1089 + révision que vous venez de créer existe seulement dans votre 6.1090 + répertoire <filename class="directory">my-hello</filename>. Étudions 6.1091 + comment propager cette modification dans d'autres dépôts.</para> 6.1092 6.1093 <sect2 id="sec:tour:pull"> 6.1094 <title>Récupérer les modifications d'autres dépôts</title> 6.1095 6.1096 <para id="x_5a">Pour commencer, construisons un clone de notre dépôt 6.1097 - <filename class="directory">hello</filename> qui ne contiendra pas 6.1098 - le changement que nous venons d'effectuer. Nous l'appellerons notre 6.1099 - dépôt temporaire <filename class="directory">hello-pull</filename>.</para> 6.1100 - 6.1101 - &interaction.tour.clone-pull; 6.1102 - 6.1103 - <para id="x_5a">Nous allons utiliser la commande <command 6.1104 - role="hg-cmd">hg pull</command> pour envoyer les modifications depuis 6.1105 - <filename class="directory">my-hello</filename> dans <filename 6.1106 - class="directory">hello-pull</filename>. Néanmoins, récupérer 6.1107 - aveuglement des modifications depuis un dépôt a quelque chose d'un peu 6.1108 - effrayant. Mercurial propose donc une commande <command 6.1109 - role="hg-cmd">hg incoming</command> qui permet de savoir quelles modifications 6.1110 - la commande <command role="hg-cmd">hg pull</command> <emphasis>pourrait</emphasis> 6.1111 - entraîner dans notre dépôt, et ceci sans effectuer réellement de modification 6.1112 - dessus.</para> 6.1113 + <filename class="directory">hello</filename> qui ne contiendra pas 6.1114 + le changement que nous venons d'effectuer. Nous l'appellerons notre 6.1115 + dépôt temporaire <filename 6.1116 + class="directory">hello-pull</filename>.</para> 6.1117 + 6.1118 + &interaction.tour.clone-pull; 6.1119 + 6.1120 + <para id="x_5a">Nous allons utiliser la commande <command 6.1121 + role="hg-cmd">hg pull</command> pour envoyer les modifications 6.1122 + depuis <filename class="directory">my-hello</filename> dans <filename 6.1123 + class="directory">hello-pull</filename>. Néanmoins, récupérer 6.1124 + aveuglement des modifications depuis un dépôt a quelque chose d'un 6.1125 + peu effrayant. Mercurial propose donc une commande <command 6.1126 + role="hg-cmd">hg incoming</command> qui permet de savoir quelles 6.1127 + modifications la commande <command role="hg-cmd">hg pull</command> 6.1128 + <emphasis>pourrait</emphasis> entraîner dans notre dépôt, et ceci 6.1129 + sans effectuer réellement de modification dessus.</para> 6.1130 6.1131 &interaction.tour.incoming; 6.1132 - 6.1133 - <para id="x_5c">Apporter les modifications rapatriées dans 6.1134 - un dépôt se résume donc à exécuter la commande <command 6.1135 - role="hg-cmd">hg pull</command>, et préciser depuis quel dépôt 6.1136 - effectuer le <command role="hg-cmd">hg pull</command>.</para> 6.1137 - 6.1138 - &interaction.tour.pull; 6.1139 - 6.1140 - <para id="x_5d">Comme vous le voyez avec une sortie avant et après de la 6.1141 - commande <command role="hg-cmd">hg tip</command>, nous avons réussi à 6.1142 - récupérer aisément les modifications dans notre dépôt. Il reste néanmoins 6.1143 - quelque chose à faire avant de placer ces modifications dans l'espace de 6.1144 - travail.</para> 6.1145 - 6.1146 - <tip> 6.1147 - <title>Récupérer des changements précis</title> 6.1148 - 6.1149 - <para id="x_5b">Il est possible à cause du délai entre l'exécution de la 6.1150 - commande <command role="hg-cmd">hg incoming</command> et l'exécution de 6.1151 - la commande <command role="hg-cmd">hg pull</command>, que vous ne 6.1152 - puissiez pas voir toutes les modifications que vous rapporterez d'un 6.1153 - autre dépôt. Suppossons que vous récupériez les modifications d'un dépôt 6.1154 - situé quelque part sur le réeau. Alors que vous regardez le résultat de 6.1155 - la commande <command role="hg-cmd">hg incoming</command>, et avant que 6.1156 - vous ne décidiez de récupérer ces modifications, quelqu'un peut ajouter 6.1157 - de nouvelles révisions dans le dépôt distant. Ce qui signigie que vous 6.1158 - récupérer plus de révision que ce que vous aviez regarder en utilisant 6.1159 - la commande <command role="hg-cmd">hg incoming</command>.</para> 6.1160 - <para id="x_718">Si vous voulez seulement récupérer ce que vous aviez 6.1161 - vérifier à l'aide de la commande <command role="hg-cmd">hg 6.1162 - incoming</command>, ou que pour d'autres raisons vous souhaitiez ne 6.1163 - récupérer qu'un sous ensemble des révisions supplémentaires 6.1164 - disponibles, indiquant simplement les modifications que vous souhaitez 6.1165 - récupérer par leurs ID de révision, soit <command>hg pull 6.1166 - -r7e95bb</command>. </para> 6.1167 - </tip> 6.1168 - </sect2> 6.1169 - <sect2> 6.1170 - <title>Mise à jour de l'espace de travail</title> 6.1171 - 6.1172 - <para id="x_5e">Nous a:vons jusqu'à maintenant grossièrement définie la 6.1173 - relation entre un dépôt et un espace de travail. La commande <command 6.1174 - role="hg-cmd">hg pull</command> que nous avons exécutée dans la section 6.1175 - <xref linkend="sec:tour:pull"/> a apporté des modifications, que nous 6.1176 - avons vérifiées, dans notre dépôt, mais il n'y a aucune trace de ces 6.1177 - modifications dans notre espace de travail. En effet, <command 6.1178 - role="hg-cmd">hg pull</command> ne touche pas (par défaut) à l'espace 6.1179 - de travail. C'est la commande <command role="hg-cmd">hg update</command> 6.1180 - qui s'en charge.</para> 6.1181 - 6.1182 - &interaction.tour.update; 6.1183 - 6.1184 - <para id="x_5f">Il peut sembler un peu étrange que la commande <command 6.1185 - role="hg-cmd">hg pull</command> ne mette pas à jour l'espace de travail 6.1186 - automatiquement. Il y a en fait une très bonne raison à cela : vous 6.1187 - pouvez utilisez la commande <command role="hg-cmd">hg update</command> 6.1188 - pour mettre à jour votre espace de travail à l'état dans lequel il était 6.1189 - à <emphasis>n'importe quelle révision</emphasis> de l'historique du dépôt. 6.1190 - Si vous aviez un espace de travail contenant une ancienne 6.1191 - révision&emdash;pour chercher l'origine d'un bug, par exemple&emdash;et 6.1192 - que vous effectuiez un <command role="hg-cmd">hg pull</command> qui 6.1193 - mettrait à jour automatiquement votre espace de travail, vous ne seriez 6.1194 - probablement pas très satisfait. 6.1195 - </para> 6.1196 - 6.1197 - <para id="x_60">Néanmoins, comme les opérations de pull sont très souvent 6.1198 - suivies d'un update, Mercurial vous permet de combiner les 6.1199 - deux aisément en passant l'option <option role="hg-opt-pull">-u</option> 6.1200 - à la commande <command role="hg-cmd">hg pull</command>.</para> 6.1201 - 6.1202 - <para id="x_61">Si vous étudiez de nouveau la sortie de la commande <command 6.1203 - role="hg-cmd">hg pull</command> dans la section <xref 6.1204 - linkend="sec:tour:pull"/> quand nous l'avons exécutée sans l'option 6.1205 - <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a 6.1206 - affiché un rappel assez utile : vous devez encore effectuer une 6.1207 - opération pour mettre à jour votre espace de travail.</para> 6.1208 - 6.1209 - <para id="x_62">Pour découvrir sur quelle révision de l'espace de 6.1210 - travail on se trouve, utilisez la commande <command role="hg-cmd">hg 6.1211 - parents</command>.</para> 6.1212 - 6.1213 - &interaction.tour.parents; 6.1214 - 6.1215 - <para id="x_63">Si vous regardez de nouveau le dessin <xref 6.1216 - linkend="fig:tour-basic:history"/>, vous verrez les flèches reliant 6.1217 - entre eux les révisions. Le nœud d'où la flèche 6.1218 - <emphasis>part</emphasis> est dans chaque cas un parent, 6.1219 - et le nœud où la flèche <emphasis>arrive</emphasis> est un enfant.</para> 6.1220 - 6.1221 - <para id="x_64">Pour mettre à jour l'espace de travail d'une révision particulière, 6.1222 - indiquez un numéro de révision ou un \textit{changeset ID} à la commande 6.1223 - <command role="hg-cmd">hg update</command>.</para> 6.1224 - 6.1225 - &interaction.tour.older; 6.1226 - 6.1227 - <para id="x_65">Si vous ne précisez pas de manière explicite de numéro 6.1228 - de révision la commande <command role="hg-cmd">hg update</command> 6.1229 - mettra à jour votre espace de travail avec 6.1230 - le contenu de la révsion \textit{tip}, comme montré dans l'exemple ci 6.1231 - dessus lors du second appel à <command role="hg-cmd">hg update</command>.</para> 6.1232 - </sect2> 6.1233 - 6.1234 - <sect2> 6.1235 - <title>Transférer les modifications à un autre dépôt</title> 6.1236 - 6.1237 - <para id="x_66">Mercurial vous laisse transférer les modifications 6.1238 - à un autre dépôt, depuis votre dépôt actuel. Comme dans l'exemple 6.1239 - du <command role="hg-cmd">hg pull</command> ci-dessus, nous allons 6.1240 - créer un dépôt temporaire vers lequel transférer nos modifications. 6.1241 - 6.1242 - &interaction.tour.clone-push; 6.1243 - 6.1244 - <para id="x_67">La commande <command role="hg-cmd">hg outgoing</command> 6.1245 - nous indique quels changements nous allons transférer vers l'autre 6.1246 - serveur ?</para> 6.1247 - 6.1248 - &interaction.tour.outgoing; 6.1249 - 6.1250 - <para id="x_68">Et la commande <command role="hg-cmd">hg push</command> 6.1251 - effectue réellement le transfert.</para> 6.1252 - 6.1253 - &interaction.tour.push; 6.1254 - 6.1255 - <para id="x_69">Comme avec <command role="hg-cmd">hg pull</command>, la 6.1256 - commande <command role="hg-cmd">hg push</command> ne met pas à jour 6.1257 - le répertoire de travail du dépôt dans lequel il transfère les 6.1258 - modifications. À l'inverse de <command role="hg-cmd">hg pull</command>, 6.1259 - <command role="hg-cmd">hg push</command> ne fournit pas d'option 6.1260 - <literal>-u</literal> pour forcer la mise à jour de l'espace de 6.1261 - travail cible. Cette asymétrie est délibéré : le dépot vers lequel nous 6.1262 - transférons peut très bien être un serveur distant et partagé par 6.1263 - plusieurs personnes. Si nous devions mettre à jour son répertoire de 6.1264 - travail alors que quelqu'un d'autre travail dessus, nous risquerions 6.1265 - de perturber son travail.</para> 6.1266 - 6.1267 - <para id="x_6a">Qu'est ce qui se passe lorsque vous essayez de récupérer 6.1268 - ou de transférer vos modifications et que le dépôt cible a déjà reçu 6.1269 - ces modifications ? Rien de bien excitant.</para> 6.1270 - 6.1271 - &interaction.tour.push.nothing; 6.1272 - 6.1273 - </sect2> 6.1274 - 6.1275 - <sect2> 6.1276 - <title>Emplacements par défaut</title> 6.1277 - 6.1278 - <para id="x_719">Quand nous faisons un clone d'un dépôt, Mercurial 6.1279 - enregistre l'emplacement du dépôt d'origine dans le fichier 6.1280 - <filename>.hg/hgrc</filename> de notre nouveau dépôt. Si nous ne 6.1281 - fournissons pas d'emplacement à la commande <command>hg pull</command> 6.1282 - ou à la commande <command>hg push</command>, ces commandes utiliseront 6.1283 - alors ces emplacements comme valeur par défaut. Les commandes 6.1284 - <command>hg incoming</command> et <command>hg outgoing</command> feront 6.1285 - de même.</para> 6.1286 - 6.1287 - <para id="x_71a">Si vous regardez le fichier 6.1288 - <filename>.hg/hgrc</filename>, vous constaterez que son contenu ressemble 6.1289 - à ce qui suit.</para> 6.1290 - 6.1291 - <programlisting>[paths] 6.1292 + 6.1293 + <para id="x_5c">Apporter les modifications rapatriées dans un dépôt se 6.1294 + résume donc à exécuter la commande <command role="hg-cmd">hg 6.1295 + pull</command>, et préciser depuis quel dépôt effectuer le <command 6.1296 + role="hg-cmd">hg pull</command>.</para> 6.1297 + 6.1298 + &interaction.tour.pull; 6.1299 + 6.1300 + <para id="x_5d">Comme vous le voyez avec une sortie avant et après de la 6.1301 + commande <command role="hg-cmd">hg tip</command>, nous avons réussi à 6.1302 + récupérer aisément les modifications dans notre dépôt. Il reste néanmoins 6.1303 + quelque chose à faire avant de placer ces modifications dans l'espace de 6.1304 + travail.</para> 6.1305 + 6.1306 + <tip> 6.1307 + <title>Récupérer des changements précis</title> 6.1308 + 6.1309 + <para id="x_5b">Il est possible à cause du délai entre l'exécution de la 6.1310 + commande <command role="hg-cmd">hg incoming</command> et l'exécution de 6.1311 + la commande <command role="hg-cmd">hg pull</command>, que vous ne 6.1312 + puissiez pas voir toutes les modifications que vous rapporterez d'un 6.1313 + autre dépôt. Supposons que vous récupériez les modifications d'un dépôt 6.1314 + situé quelque part sur le réseau. Alors que vous regardez le résultat de 6.1315 + la commande <command role="hg-cmd">hg incoming</command>, et avant que 6.1316 + vous ne décidiez de récupérer ces modifications, quelqu'un peut ajouter 6.1317 + de nouvelles révisions dans le dépôt distant. Ce qui signifie que vous 6.1318 + récupérez plus de révision que ce que vous aviez regardées en utilisant 6.1319 + la commande <command role="hg-cmd">hg incoming</command>.</para> 6.1320 + 6.1321 + <para id="x_718">Si vous voulez seulement récupérer ce que vous aviez 6.1322 + vérifier à l'aide de la commande <command role="hg-cmd">hg 6.1323 + incoming</command>, ou que pour d'autres raisons vous souhaitiez ne 6.1324 + récupérer qu'un sous ensemble des révisions supplémentaires 6.1325 + disponibles, indiquant simplement les modifications que vous souhaitez 6.1326 + récupérer par leurs ID de révision, soit <command>hg pull 6.1327 + -r7e95bb</command>. </para> 6.1328 + </tip> 6.1329 + 6.1330 + </sect2> 6.1331 + <sect2> 6.1332 + <title>Mise à jour de l'espace de travail</title> 6.1333 + 6.1334 + <para id="x_5e">Nous avons jusqu'à maintenant grossièrement défini la 6.1335 + relation entre un dépôt et un espace de travail. La commande <command 6.1336 + role="hg-cmd">hg pull</command> que nous avons exécutée dans la section 6.1337 + <xref linkend="sec:tour:pull"/> a apporté des modifications, que nous 6.1338 + avons vérifiées, dans notre dépôt, mais il n'y a aucune trace de ces 6.1339 + modifications dans notre espace de travail. En effet, <command 6.1340 + role="hg-cmd">hg pull</command> ne touche pas (par défaut) à l'espace 6.1341 + de travail. C'est la commande <command role="hg-cmd">hg update</command> 6.1342 + qui s'en charge.</para> 6.1343 + 6.1344 + &interaction.tour.update; 6.1345 + 6.1346 + <para id="x_5f">Il peut sembler un peu étrange que la commande <command 6.1347 + role="hg-cmd">hg pull</command> ne mette pas à jour l'espace de travail 6.1348 + automatiquement. Il y a en fait une très bonne raison à cela : vous 6.1349 + pouvez utilisez la commande <command role="hg-cmd">hg update</command> 6.1350 + pour mettre à jour votre espace de travail à l'état dans lequel il était 6.1351 + à <emphasis>n'importe quelle révision</emphasis> de l'historique du dépôt. 6.1352 + Si vous aviez un espace de travail contenant une ancienne 6.1353 + révision&emdash;pour chercher l'origine d'un bug, par exemple&emdash;et 6.1354 + que vous effectuiez un <command role="hg-cmd">hg pull</command> qui 6.1355 + mettrait à jour automatiquement votre espace de travail, vous ne seriez 6.1356 + probablement pas très satisfait.</para> 6.1357 + 6.1358 + <para id="x_60">Néanmoins, comme les opérations de pull sont très souvent 6.1359 + suivies d'un update, Mercurial vous permet de combiner les 6.1360 + deux aisément en passant l'option <option role="hg-opt-pull">-u</option> 6.1361 + à la commande <command role="hg-cmd">hg pull</command>.</para> 6.1362 + 6.1363 + <para id="x_61">Si vous étudiez de nouveau la sortie de la commande <command 6.1364 + role="hg-cmd">hg pull</command> dans la section <xref 6.1365 + linkend="sec:tour:pull"/> quand nous l'avons exécutée sans l'option 6.1366 + <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a 6.1367 + affiché un rappel assez utile : vous devez encore effectuer une 6.1368 + opération pour mettre à jour votre espace de travail.</para> 6.1369 + 6.1370 + <para id="x_62">Pour découvrir sur quelle révision de l'espace de 6.1371 + travail on se trouve, utilisez la commande <command role="hg-cmd">hg 6.1372 + parents</command>.</para> 6.1373 + 6.1374 + &interaction.tour.parents; 6.1375 + 6.1376 + <para id="x_63">Si vous regardez de nouveau le dessin <xref 6.1377 + linkend="fig:tour-basic:history"/>, vous verrez les flèches reliant 6.1378 + entre elles les révisions. Le nœud d'où la flèche 6.1379 + <emphasis>part</emphasis> est dans chaque cas un parent, 6.1380 + et le nœud où la flèche <emphasis>arrive</emphasis> est un 6.1381 + enfant.</para> 6.1382 + 6.1383 + <para id="x_64">Pour mettre à jour l'espace de travail d'une révision 6.1384 + particulière, indiquez un numéro de révision ou un \textit{changeset 6.1385 + ID} à la commande <command role="hg-cmd">hg update</command>.</para> 6.1386 + 6.1387 + &interaction.tour.older; 6.1388 + 6.1389 + <para id="x_65">Si vous ne précisez pas de manière explicite de numéro 6.1390 + de révision la commande <command role="hg-cmd">hg update</command> 6.1391 + mettra à jour votre espace de travail avec le contenu de la révison 6.1392 + \textit{tip}, comme montré dans l'exemple ci dessus lors du second 6.1393 + appel à <command role="hg-cmd">hg update</command>.</para> 6.1394 + 6.1395 + </sect2> 6.1396 + <sect2> 6.1397 + <title>Transférer les modifications vers un autre dépôt</title> 6.1398 + 6.1399 + <para id="x_66">Mercurial vous laisse transférer les modifications vers 6.1400 + un autre dépôt, depuis votre dépôt actuel. Comme dans l'exemple du 6.1401 + <command role="hg-cmd">hg pull</command> ci-dessus, nous allons créer 6.1402 + un dépôt temporaire vers lequel transférer nos modifications.</para> 6.1403 + 6.1404 + &interaction.tour.clone-push; 6.1405 + 6.1406 + <para id="x_67">La commande <command role="hg-cmd">hg outgoing</command> 6.1407 + nous indique quels changements nous allons transférer vers l'autre 6.1408 + serveur.</para> 6.1409 + 6.1410 + &interaction.tour.outgoing; 6.1411 + 6.1412 + <para id="x_68">Et la commande <command role="hg-cmd">hg push</command> 6.1413 + effectue réellement le transfert.</para> 6.1414 + 6.1415 + &interaction.tour.push; 6.1416 + 6.1417 + <para id="x_69">Comme avec <command role="hg-cmd">hg pull</command>, la 6.1418 + commande <command role="hg-cmd">hg push</command> ne met pas à jour 6.1419 + le répertoire de travail du dépôt dans lequel il transfère les 6.1420 + modifications. À l'inverse de <command role="hg-cmd">hg 6.1421 + pull</command>, <command role="hg-cmd">hg push</command> ne fournit 6.1422 + pas d'option <literal>-u</literal> pour forcer la mise à jour de 6.1423 + l'espace de travail cible. Cette asymétrie est délibéré : le dépot 6.1424 + vers lequel nous transférons peut très bien être un serveur distant 6.1425 + et partagé par plusieurs personnes. Si nous devions mettre à jour son 6.1426 + répertoire de travail alors que quelqu'un d'autre travaille dessus, 6.1427 + nous risquerions de perturber son travail.</para> 6.1428 + 6.1429 + <para id="x_6a">Qu'est ce qui se passe lorsque vous essayez de récupérer 6.1430 + ou de transférer vos modifications et que le dépôt cible a déjà reçu 6.1431 + ces modifications ? Rien de bien excitant.</para> 6.1432 + 6.1433 + &interaction.tour.push.nothing; 6.1434 + 6.1435 + </sect2> 6.1436 + 6.1437 + <sect2> 6.1438 + <title>Emplacements par défaut</title> 6.1439 + 6.1440 + <para id="x_719">Quand nous faisons un clone d'un dépôt, Mercurial 6.1441 + enregistre l'emplacement du dépôt d'origine dans le fichier 6.1442 + <filename>.hg/hgrc</filename> de notre nouveau dépôt. Si nous ne 6.1443 + fournissons pas d'emplacement à la commande <command>hg 6.1444 + pull</command> ou à la commande <command>hg push</command>, ces 6.1445 + commandes utiliseront alors cet emplacement comme valeur par défaut. 6.1446 + Les commandes <command>hg incoming</command> et <command>hg 6.1447 + outgoing</command> feront de même.</para> 6.1448 + 6.1449 + <para id="x_71a">Si vous regardez le fichier 6.1450 + <filename>.hg/hgrc</filename>, vous constaterez que son contenu 6.1451 + ressemble à ce qui suit.</para> 6.1452 + 6.1453 + <programlisting>[paths] 6.1454 default = http://www.selenic.com/repo/hg</programlisting> 6.1455 6.1456 - <para id="x_71b">Il est possible&emdash;et souvent 6.1457 - pratique&emdash;d'avoir un emplacement par défaut pour la commande 6.1458 - <command>hg push</command> et la commande <command>hg outgoing</command> 6.1459 - différent de celui des commandes <command>hg pull</command> et des 6.1460 - <command>hg incoming</command>. C'est faisable en ajoutant une entrée 6.1461 - <literal>default-push</literal> à la section <literal>[paths]</literal> 6.1462 - du <filename>.hg/hgrc</filename>, comme suit.</para> 6.1463 - 6.1464 - <programlisting>[paths] 6.1465 + <para id="x_71b">Il est possible&emdash;et souvent 6.1466 + pratique&emdash;d'avoir un emplacement par défaut pour les commandes 6.1467 + <command>hg push</command> et <command>hg outgoing</command> 6.1468 + différent de celui des commandes <command>hg pull</command> et 6.1469 + <command>hg incoming</command>. C'est faisable en ajoutant une entrée 6.1470 + <literal>default-push</literal> à la section 6.1471 + <literal>[paths]</literal> du <filename>.hg/hgrc</filename>, comme 6.1472 + suit.</para> 6.1473 + 6.1474 + <programlisting>[paths] 6.1475 default = http://www.selenic.com/repo/hg 6.1476 default-push = http://hg.example.com/hg</programlisting> 6.1477 - </sect2> 6.1478 - 6.1479 - <sect2> 6.1480 - <title>Partager ses modifications à travers le réseau</title> 6.1481 - 6.1482 - <para id="x_6b">Les commandes que nous avons étudiées dans les sections 6.1483 - précédentes ne sont pas limitées aux dépôt locaux. Chacune fonctionne 6.1484 - de la même manière à travers une connexion réseau, il suffit de lui 6.1485 - passer une URL à la place d'un chemin de fichier local.</para> 6.1486 - 6.1487 - &interaction.tour.outgoing.net; 6.1488 - 6.1489 - <para id="x_6c">Dans cet exemple, nous allons voir quels changements 6.1490 - nous pourrions transférer vers le dépôt distant, mais le dépôt est, 6.1491 - de manière tout à fait compréhensible, pas configuré pour accepter 6.1492 - des modifications d'utilisateurs anonymes.</para> 6.1493 - 6.1494 - &interaction.tour.push.net; 6.1495 - </sect2> 6.1496 + 6.1497 + </sect2> 6.1498 + <sect2> 6.1499 + <title>Partager ses modifications à travers le réseau</title> 6.1500 + 6.1501 + <para id="x_6b">Les commandes que nous avons étudiées dans les sections 6.1502 + précédentes ne sont pas limitées aux dépôts locaux. Chacune fonctionne 6.1503 + de la même manière à travers une connexion réseau, il suffit de lui 6.1504 + passer une URL à la place d'un chemin de fichier local.</para> 6.1505 + 6.1506 + &interaction.tour.outgoing.net; 6.1507 + 6.1508 + <para id="x_6c">Dans cet exemple, nous allons voir quels changements 6.1509 + nous pourrions transférer vers le dépôt distant, mais le dépôt est, 6.1510 + de manière tout à fait compréhensible, pas configuré pour accepter 6.1511 + des modifications d'utilisateurs anonymes.</para> 6.1512 + 6.1513 + &interaction.tour.push.net; 6.1514 + 6.1515 + </sect2> 6.1516 + 6.1517 </sect1> 6.1518 6.1519 <sect1> 6.1520 - <title>Commencer un nouveau projet</title>w 6.1521 - 6.1522 - <para id="x_71c">Il est tout aussi aisé de commencer un nouveau projet 6.1523 - que de travailler sur un qui existe déjà. La commande 6.1524 - <command>hg init</command> créer un nouveau dépôt Mercurial, 6.1525 - vide.</para> 6.1526 - 6.1527 - &interaction.ch01-new.init; 6.1528 - 6.1529 - <para id="x_71d">Ceci créer simplement un répertoire nommée 6.1530 - <filename>myproject</filename> dans le répertoire courant.</para> 6.1531 - 6.1532 - &interaction.ch01-new.ls; 6.1533 - 6.1534 - <para id="x_71e">Nous pouvons dire que <filename>myproject</filename> 6.1535 - est un dépôt Mercurial car il contient un répertoire 6.1536 - <filename>.hg</filename>.</para> 6.1537 - 6.1538 - &interaction.ch01-new.ls2; 6.1539 - 6.1540 - <para id="x_71f">Si vous voulons ajouter quelques fichiers préexistants 6.1541 - dans ce dépôt, il suffit de les recopier dans le répertoire de travail, 6.1542 - et demander à Mercurial de commencer les suivre en utilisant la 6.1543 - commande <command>hg add</command>.</para> 6.1544 - 6.1545 - &interaction.ch01-new.add; 6.1546 - 6.1547 - <para id="x_720">Une fois que nous sommes satisfait de notre projet, 6.1548 - nous pouvons commencer à ajouter nos révisions.</para> 6.1549 - 6.1550 - &interaction.ch01-new.commit; 6.1551 - 6.1552 - <para id="x_721">Il ne prend que quelques instants pour commencer à 6.1553 + <title>Commencer un nouveau projet</title> 6.1554 + 6.1555 + <para id="x_71c">Il est tout aussi aisé de commencer un nouveau projet 6.1556 + que de travailler sur un qui existe déjà. La commande <command>hg 6.1557 + init</command> crée un nouveau dépôt Mercurial vide.</para> 6.1558 + 6.1559 + &interaction.ch01-new.init; 6.1560 + 6.1561 + <para id="x_71d">Ceci crée simplement un répertoire nommé 6.1562 + <filename>myproject</filename> dans le répertoire courant.</para> 6.1563 + 6.1564 + &interaction.ch01-new.ls; 6.1565 + 6.1566 + <para id="x_71e">Nous pouvons dire que <filename>myproject</filename> est 6.1567 + un dépôt Mercurial car il contient un répertoire 6.1568 + <filename>.hg</filename>.</para> 6.1569 + 6.1570 + &interaction.ch01-new.ls2; 6.1571 + 6.1572 + <para id="x_71f">Si vous voulons ajouter quelques fichiers préexistants 6.1573 + dans ce dépôt, il suffit de les recopier dans le répertoire de travail, 6.1574 + et demander à Mercurial de commencer à les suivre en utilisant la 6.1575 + commande <command>hg add</command>.</para> 6.1576 + 6.1577 + &interaction.ch01-new.add; 6.1578 + 6.1579 + <para id="x_720">Une fois que nous sommes satisfaits de notre projet, 6.1580 + nous pouvons commencer à ajouter nos révisions.</para> 6.1581 + 6.1582 + &interaction.ch01-new.commit; 6.1583 + 6.1584 + <para id="x_721">Il ne prend que quelques instants pour commencer à 6.1585 utiliser Mercurial sur un nouveau projet, ce qui fait aussi de ses 6.1586 points forts. Travailler avec une gestion de révision devient très 6.1587 facile, nous pouvons même l'utiliser pour les plus petits projets où 6.1588 nous aurions probablement jamais penser utiliser un outils aussi 6.1589 complexe.</para> 6.1590 - </sect1> 6.1591 + </sect1> 6.1592 </chapter> 6.1593 6.1594 <!--
7.1 --- a/fr/ch04-concepts.xml Sat Sep 12 17:58:26 2009 +0200 7.2 +++ b/fr/ch04-concepts.xml Sat Sep 12 17:58:56 2009 +0200 7.3 @@ -1,710 +1,771 @@ 7.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 7.5 7.6 -<chapter> 7.7 -<title>Behind the scenes</title> 7.8 -<para>\label{chap:concepts}</para> 7.9 - 7.10 -<para>Unlike many revision control systems, the concepts upon which 7.11 -Mercurial is built are simple enough that it's easy to understand how 7.12 -the software really works. Knowing this certainly isn't necessary, 7.13 -but I find it useful to have a <quote>mental model</quote> of what's going on.</para> 7.14 - 7.15 -<para>This understanding gives me confidence that Mercurial has been 7.16 -carefully designed to be both <emphasis>safe</emphasis> and <emphasis>efficient</emphasis>. And 7.17 -just as importantly, if it's easy for me to retain a good idea of what 7.18 -the software is doing when I perform a revision control task, I'm less 7.19 -likely to be surprised by its behaviour.</para> 7.20 - 7.21 -<para>In this chapter, we'll initially cover the core concepts behind 7.22 -Mercurial's design, then continue to discuss some of the interesting 7.23 -details of its implementation.</para> 7.24 - 7.25 -<sect1> 7.26 -<title>Mercurial's historical record</title> 7.27 - 7.28 -<sect2> 7.29 -<title>Tracking the history of a single file</title> 7.30 - 7.31 -<para>When Mercurial tracks modifications to a file, it stores the history 7.32 -of that file in a metadata object called a <emphasis>filelog</emphasis>. Each entry 7.33 -in the filelog contains enough information to reconstruct one revision 7.34 -of the file that is being tracked. Filelogs are stored as files in 7.35 -the <filename role="special" class="directory">.hg/store/data</filename> directory. A filelog contains two kinds 7.36 -of information: revision data, and an index to help Mercurial to find 7.37 -a revision efficiently.</para> 7.38 - 7.39 -<para>A file that is large, or has a lot of history, has its filelog stored 7.40 -in separate data (<quote><literal>.d</literal></quote> suffix) and index (<quote><literal>.i</literal></quote> 7.41 -suffix) files. For small files without much history, the revision 7.42 -data and index are combined in a single <quote><literal>.i</literal></quote> file. The 7.43 -correspondence between a file in the working directory and the filelog 7.44 -that tracks its history in the repository is illustrated in 7.45 -figure <xref linkend="fig:concepts:filelog"/>.</para> 7.46 - 7.47 -<informalfigure> 7.48 - 7.49 -<para> <mediaobject><imageobject><imagedata fileref="filelog"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.50 - \caption{Relationships between files in working directory and 7.51 - filelogs in repository} 7.52 - \label{fig:concepts:filelog}</para> 7.53 -</informalfigure> 7.54 - 7.55 -</sect2> 7.56 -<sect2> 7.57 -<title>Managing tracked files</title> 7.58 - 7.59 -<para>Mercurial uses a structure called a <emphasis>manifest</emphasis> to collect 7.60 -together information about the files that it tracks. Each entry in 7.61 -the manifest contains information about the files present in a single 7.62 -changeset. An entry records which files are present in the changeset, 7.63 -the revision of each file, and a few other pieces of file metadata.</para> 7.64 - 7.65 -</sect2> 7.66 -<sect2> 7.67 -<title>Recording changeset information</title> 7.68 - 7.69 -<para>The <emphasis>changelog</emphasis> contains information about each changeset. Each 7.70 -revision records who committed a change, the changeset comment, other 7.71 -pieces of changeset-related information, and the revision of the 7.72 -manifest to use. 7.73 -</para> 7.74 - 7.75 -</sect2> 7.76 -<sect2> 7.77 -<title>Relationships between revisions</title> 7.78 - 7.79 -<para>Within a changelog, a manifest, or a filelog, each revision stores a 7.80 -pointer to its immediate parent (or to its two parents, if it's a 7.81 -merge revision). As I mentioned above, there are also relationships 7.82 -between revisions <emphasis>across</emphasis> these structures, and they are 7.83 -hierarchical in nature. 7.84 -</para> 7.85 - 7.86 -<para>For every changeset in a repository, there is exactly one revision 7.87 -stored in the changelog. Each revision of the changelog contains a 7.88 -pointer to a single revision of the manifest. A revision of the 7.89 -manifest stores a pointer to a single revision of each filelog tracked 7.90 -when that changeset was created. These relationships are illustrated 7.91 -in figure <xref linkend="fig:concepts:metadata"/>. 7.92 -</para> 7.93 - 7.94 -<informalfigure> 7.95 - 7.96 -<para> <mediaobject><imageobject><imagedata fileref="metadata"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.97 - <caption><para>Metadata relationships</para></caption> 7.98 - \label{fig:concepts:metadata} 7.99 -</para> 7.100 -</informalfigure> 7.101 - 7.102 -<para>As the illustration shows, there is <emphasis>not</emphasis> a <quote>one to one</quote> 7.103 -relationship between revisions in the changelog, manifest, or filelog. 7.104 -If the manifest hasn't changed between two changesets, the changelog 7.105 -entries for those changesets will point to the same revision of the 7.106 -manifest. If a file that Mercurial tracks hasn't changed between two 7.107 -changesets, the entry for that file in the two revisions of the 7.108 -manifest will point to the same revision of its filelog. 7.109 -</para> 7.110 - 7.111 -</sect2> 7.112 -</sect1> 7.113 -<sect1> 7.114 -<title>Safe, efficient storage</title> 7.115 - 7.116 -<para>The underpinnings of changelogs, manifests, and filelogs are provided 7.117 -by a single structure called the <emphasis>revlog</emphasis>. 7.118 -</para> 7.119 - 7.120 -<sect2> 7.121 -<title>Efficient storage</title> 7.122 - 7.123 -<para>The revlog provides efficient storage of revisions using a 7.124 -<emphasis>delta</emphasis> mechanism. Instead of storing a complete copy of a file 7.125 -for each revision, it stores the changes needed to transform an older 7.126 -revision into the new revision. For many kinds of file data, these 7.127 -deltas are typically a fraction of a percent of the size of a full 7.128 -copy of a file. 7.129 -</para> 7.130 - 7.131 -<para>Some obsolete revision control systems can only work with deltas of 7.132 -text files. They must either store binary files as complete snapshots 7.133 -or encoded into a text representation, both of which are wasteful 7.134 -approaches. Mercurial can efficiently handle deltas of files with 7.135 -arbitrary binary contents; it doesn't need to treat text as special. 7.136 -</para> 7.137 - 7.138 -</sect2> 7.139 -<sect2> 7.140 -<title>Safe operation</title> 7.141 -<para>\label{sec:concepts:txn} 7.142 -</para> 7.143 - 7.144 -<para>Mercurial only ever <emphasis>appends</emphasis> data to the end of a revlog file. 7.145 -It never modifies a section of a file after it has written it. This 7.146 -is both more robust and efficient than schemes that need to modify or 7.147 -rewrite data. 7.148 -</para> 7.149 - 7.150 -<para>In addition, Mercurial treats every write as part of a 7.151 -<emphasis>transaction</emphasis> that can span a number of files. A transaction is 7.152 -<emphasis>atomic</emphasis>: either the entire transaction succeeds and its effects 7.153 -are all visible to readers in one go, or the whole thing is undone. 7.154 -This guarantee of atomicity means that if you're running two copies of 7.155 -Mercurial, where one is reading data and one is writing it, the reader 7.156 -will never see a partially written result that might confuse it. 7.157 -</para> 7.158 - 7.159 -<para>The fact that Mercurial only appends to files makes it easier to 7.160 -provide this transactional guarantee. The easier it is to do stuff 7.161 -like this, the more confident you should be that it's done correctly. 7.162 -</para> 7.163 - 7.164 -</sect2> 7.165 -<sect2> 7.166 -<title>Fast retrieval</title> 7.167 - 7.168 -<para>Mercurial cleverly avoids a pitfall common to all earlier 7.169 -revision control systems: the problem of <emphasis>inefficient retrieval</emphasis>. 7.170 -Most revision control systems store the contents of a revision as an 7.171 -incremental series of modifications against a <quote>snapshot</quote>. To 7.172 -reconstruct a specific revision, you must first read the snapshot, and 7.173 -then every one of the revisions between the snapshot and your target 7.174 -revision. The more history that a file accumulates, the more 7.175 -revisions you must read, hence the longer it takes to reconstruct a 7.176 -particular revision. 7.177 -</para> 7.178 - 7.179 -<informalfigure> 7.180 - 7.181 -<para> <mediaobject><imageobject><imagedata fileref="snapshot"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.182 - <caption><para>Snapshot of a revlog, with incremental deltas</para></caption> 7.183 - \label{fig:concepts:snapshot} 7.184 -</para> 7.185 -</informalfigure> 7.186 - 7.187 -<para>The innovation that Mercurial applies to this problem is simple but 7.188 -effective. Once the cumulative amount of delta information stored 7.189 -since the last snapshot exceeds a fixed threshold, it stores a new 7.190 -snapshot (compressed, of course), instead of another delta. This 7.191 -makes it possible to reconstruct <emphasis>any</emphasis> revision of a file 7.192 -quickly. This approach works so well that it has since been copied by 7.193 -several other revision control systems. 7.194 -</para> 7.195 - 7.196 -<para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates the idea. In an entry 7.197 -in a revlog's index file, Mercurial stores the range of entries from 7.198 -the data file that it must read to reconstruct a particular revision. 7.199 -</para> 7.200 - 7.201 -<sect3> 7.202 -<title>Aside: the influence of video compression</title> 7.203 - 7.204 -<para>If you're familiar with video compression or have ever watched a TV 7.205 -feed through a digital cable or satellite service, you may know that 7.206 -most video compression schemes store each frame of video as a delta 7.207 -against its predecessor frame. In addition, these schemes use 7.208 -<quote>lossy</quote> compression techniques to increase the compression ratio, so 7.209 -visual errors accumulate over the course of a number of inter-frame 7.210 -deltas. 7.211 -</para> 7.212 - 7.213 -<para>Because it's possible for a video stream to <quote>drop out</quote> occasionally 7.214 -due to signal glitches, and to limit the accumulation of artefacts 7.215 -introduced by the lossy compression process, video encoders 7.216 -periodically insert a complete frame (called a <quote>key frame</quote>) into the 7.217 -video stream; the next delta is generated against that frame. This 7.218 -means that if the video signal gets interrupted, it will resume once 7.219 -the next key frame is received. Also, the accumulation of encoding 7.220 -errors restarts anew with each key frame. 7.221 -</para> 7.222 - 7.223 -</sect3> 7.224 -</sect2> 7.225 -<sect2> 7.226 -<title>Identification and strong integrity</title> 7.227 - 7.228 -<para>Along with delta or snapshot information, a revlog entry contains a 7.229 -cryptographic hash of the data that it represents. This makes it 7.230 -difficult to forge the contents of a revision, and easy to detect 7.231 -accidental corruption. 7.232 -</para> 7.233 - 7.234 -<para>Hashes provide more than a mere check against corruption; they are 7.235 -used as the identifiers for revisions. The changeset identification 7.236 -hashes that you see as an end user are from revisions of the 7.237 -changelog. Although filelogs and the manifest also use hashes, 7.238 -Mercurial only uses these behind the scenes. 7.239 -</para> 7.240 - 7.241 -<para>Mercurial verifies that hashes are correct when it retrieves file 7.242 -revisions and when it pulls changes from another repository. If it 7.243 -encounters an integrity problem, it will complain and stop whatever 7.244 -it's doing. 7.245 -</para> 7.246 - 7.247 -<para>In addition to the effect it has on retrieval efficiency, Mercurial's 7.248 -use of periodic snapshots makes it more robust against partial data 7.249 -corruption. If a revlog becomes partly corrupted due to a hardware 7.250 -error or system bug, it's often possible to reconstruct some or most 7.251 -revisions from the uncorrupted sections of the revlog, both before and 7.252 -after the corrupted section. This would not be possible with a 7.253 -delta-only storage model. 7.254 -</para> 7.255 - 7.256 -<para>\section{Revision history, branching, 7.257 - and merging} 7.258 -</para> 7.259 - 7.260 -<para>Every entry in a Mercurial revlog knows the identity of its immediate 7.261 -ancestor revision, usually referred to as its <emphasis>parent</emphasis>. In fact, 7.262 -a revision contains room for not one parent, but two. Mercurial uses 7.263 -a special hash, called the <quote>null ID</quote>, to represent the idea <quote>there 7.264 -is no parent here</quote>. This hash is simply a string of zeroes. 7.265 -</para> 7.266 - 7.267 -<para>In figure <xref linkend="fig:concepts:revlog"/>, you can see an example of the 7.268 -conceptual structure of a revlog. Filelogs, manifests, and changelogs 7.269 -all have this same structure; they differ only in the kind of data 7.270 -stored in each delta or snapshot. 7.271 -</para> 7.272 - 7.273 -<para>The first revision in a revlog (at the bottom of the image) has the 7.274 -null ID in both of its parent slots. For a <quote>normal</quote> revision, its 7.275 -first parent slot contains the ID of its parent revision, and its 7.276 -second contains the null ID, indicating that the revision has only one 7.277 -real parent. Any two revisions that have the same parent ID are 7.278 -branches. A revision that represents a merge between branches has two 7.279 -normal revision IDs in its parent slots. 7.280 -</para> 7.281 - 7.282 -<informalfigure> 7.283 - 7.284 -<para> <mediaobject><imageobject><imagedata fileref="revlog"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.285 - \caption{} 7.286 - \label{fig:concepts:revlog} 7.287 -</para> 7.288 -</informalfigure> 7.289 - 7.290 -</sect2> 7.291 -</sect1> 7.292 -<sect1> 7.293 -<title>The working directory</title> 7.294 - 7.295 -<para>In the working directory, Mercurial stores a snapshot of the files 7.296 -from the repository as of a particular changeset. 7.297 -</para> 7.298 - 7.299 -<para>The working directory <quote>knows</quote> which changeset it contains. When you 7.300 -update the working directory to contain a particular changeset, 7.301 -Mercurial looks up the appropriate revision of the manifest to find 7.302 -out which files it was tracking at the time that changeset was 7.303 -committed, and which revision of each file was then current. It then 7.304 -recreates a copy of each of those files, with the same contents it had 7.305 -when the changeset was committed. 7.306 -</para> 7.307 - 7.308 -<para>The <emphasis>dirstate</emphasis> contains Mercurial's knowledge of the working 7.309 -directory. This details which changeset the working directory is 7.310 -updated to, and all of the files that Mercurial is tracking in the 7.311 -working directory. 7.312 -</para> 7.313 - 7.314 -<para>Just as a revision of a revlog has room for two parents, so that it 7.315 -can represent either a normal revision (with one parent) or a merge of 7.316 -two earlier revisions, the dirstate has slots for two parents. When 7.317 -you use the <command role="hg-cmd">hg update</command> command, the changeset that you update to 7.318 -is stored in the <quote>first parent</quote> slot, and the null ID in the second. 7.319 -When you <command role="hg-cmd">hg merge</command> with another changeset, the first parent 7.320 -remains unchanged, and the second parent is filled in with the 7.321 -changeset you're merging with. The <command role="hg-cmd">hg parents</command> command tells you 7.322 -what the parents of the dirstate are. 7.323 -</para> 7.324 - 7.325 -<sect2> 7.326 -<title>What happens when you commit</title> 7.327 - 7.328 -<para>The dirstate stores parent information for more than just book-keeping 7.329 -purposes. Mercurial uses the parents of the dirstate as \emph{the 7.330 - parents of a new changeset} when you perform a commit. 7.331 -</para> 7.332 - 7.333 -<informalfigure> 7.334 - 7.335 -<para> <mediaobject><imageobject><imagedata fileref="wdir"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.336 - <caption><para>The working directory can have two parents</para></caption> 7.337 - \label{fig:concepts:wdir} 7.338 -</para> 7.339 -</informalfigure> 7.340 - 7.341 -<para>Figure <xref linkend="fig:concepts:wdir"/> shows the normal state of the working 7.342 -directory, where it has a single changeset as parent. That changeset 7.343 -is the <emphasis>tip</emphasis>, the newest changeset in the repository that has no 7.344 -children. 7.345 -</para> 7.346 - 7.347 -<informalfigure> 7.348 - 7.349 -<para> <mediaobject><imageobject><imagedata fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.350 - <caption><para>The working directory gains new parents after a commit</para></caption> 7.351 - \label{fig:concepts:wdir-after-commit} 7.352 -</para> 7.353 -</informalfigure> 7.354 - 7.355 -<para>It's useful to think of the working directory as <quote>the changeset I'm 7.356 -about to commit</quote>. Any files that you tell Mercurial that you've 7.357 -added, removed, renamed, or copied will be reflected in that 7.358 -changeset, as will modifications to any files that Mercurial is 7.359 -already tracking; the new changeset will have the parents of the 7.360 -working directory as its parents. 7.361 -</para> 7.362 - 7.363 -<para>After a commit, Mercurial will update the parents of the working 7.364 -directory, so that the first parent is the ID of the new changeset, 7.365 -and the second is the null ID. This is shown in 7.366 -figure <xref linkend="fig:concepts:wdir-after-commit"/>. Mercurial doesn't touch 7.367 -any of the files in the working directory when you commit; it just 7.368 -modifies the dirstate to note its new parents. 7.369 -</para> 7.370 - 7.371 -</sect2> 7.372 -<sect2> 7.373 -<title>Creating a new head</title> 7.374 - 7.375 -<para>It's perfectly normal to update the working directory to a changeset 7.376 -other than the current tip. For example, you might want to know what 7.377 -your project looked like last Tuesday, or you could be looking through 7.378 -changesets to see which one introduced a bug. In cases like this, the 7.379 -natural thing to do is update the working directory to the changeset 7.380 -you're interested in, and then examine the files in the working 7.381 -directory directly to see their contents as they were when you 7.382 -committed that changeset. The effect of this is shown in 7.383 -figure <xref linkend="fig:concepts:wdir-pre-branch"/>. 7.384 -</para> 7.385 - 7.386 -<informalfigure> 7.387 - 7.388 -<para> <mediaobject><imageobject><imagedata fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.389 - <caption><para>The working directory, updated to an older changeset</para></caption> 7.390 - \label{fig:concepts:wdir-pre-branch} 7.391 -</para> 7.392 -</informalfigure> 7.393 - 7.394 -<para>Having updated the working directory to an older changeset, what 7.395 -happens if you make some changes, and then commit? Mercurial behaves 7.396 -in the same way as I outlined above. The parents of the working 7.397 -directory become the parents of the new changeset. This new changeset 7.398 -has no children, so it becomes the new tip. And the repository now 7.399 -contains two changesets that have no children; we call these 7.400 -<emphasis>heads</emphasis>. You can see the structure that this creates in 7.401 -figure <xref linkend="fig:concepts:wdir-branch"/>. 7.402 -</para> 7.403 - 7.404 -<informalfigure> 7.405 - 7.406 -<para> <mediaobject><imageobject><imagedata fileref="wdir-branch"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.407 - <caption><para>After a commit made while synced to an older changeset</para></caption> 7.408 - \label{fig:concepts:wdir-branch} 7.409 -</para> 7.410 -</informalfigure> 7.411 - 7.412 -<note> 7.413 -<para> If you're new to Mercurial, you should keep in mind a common 7.414 - <quote>error</quote>, which is to use the <command role="hg-cmd">hg pull</command> command without any 7.415 - options. By default, the <command role="hg-cmd">hg pull</command> command <emphasis>does not</emphasis> 7.416 - update the working directory, so you'll bring new changesets into 7.417 - your repository, but the working directory will stay synced at the 7.418 - same changeset as before the pull. If you make some changes and 7.419 - commit afterwards, you'll thus create a new head, because your 7.420 - working directory isn't synced to whatever the current tip is. 7.421 -</para> 7.422 - 7.423 -<para> I put the word <quote>error</quote> in quotes because all that you need to do 7.424 - to rectify this situation is <command role="hg-cmd">hg merge</command>, then <command role="hg-cmd">hg commit</command>. In 7.425 - other words, this almost never has negative consequences; it just 7.426 - surprises people. I'll discuss other ways to avoid this behaviour, 7.427 - and why Mercurial behaves in this initially surprising way, later 7.428 - on. 7.429 -</para> 7.430 -</note> 7.431 - 7.432 -</sect2> 7.433 -<sect2> 7.434 -<title>Merging heads</title> 7.435 - 7.436 -<para>When you run the <command role="hg-cmd">hg merge</command> command, Mercurial leaves the first 7.437 -parent of the working directory unchanged, and sets the second parent 7.438 -to the changeset you're merging with, as shown in 7.439 -figure <xref linkend="fig:concepts:wdir-merge"/>. 7.440 -</para> 7.441 - 7.442 -<informalfigure> 7.443 - 7.444 -<para> <mediaobject><imageobject><imagedata fileref="wdir-merge"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 7.445 - <caption><para>Merging two heads</para></caption> 7.446 - \label{fig:concepts:wdir-merge} 7.447 -</para> 7.448 -</informalfigure> 7.449 - 7.450 -<para>Mercurial also has to modify the working directory, to merge the files 7.451 -managed in the two changesets. Simplified a little, the merging 7.452 -process goes like this, for every file in the manifests of both 7.453 -changesets. 7.454 -</para> 7.455 -<itemizedlist> 7.456 -<listitem><para>If neither changeset has modified a file, do nothing with that 7.457 - file. 7.458 -</para> 7.459 -</listitem> 7.460 -<listitem><para>If one changeset has modified a file, and the other hasn't, 7.461 - create the modified copy of the file in the working directory. 7.462 -</para> 7.463 -</listitem> 7.464 -<listitem><para>If one changeset has removed a file, and the other hasn't (or 7.465 - has also deleted it), delete the file from the working directory. 7.466 -</para> 7.467 -</listitem> 7.468 -<listitem><para>If one changeset has removed a file, but the other has modified 7.469 - the file, ask the user what to do: keep the modified file, or remove 7.470 - it? 7.471 -</para> 7.472 -</listitem> 7.473 -<listitem><para>If both changesets have modified a file, invoke an external 7.474 - merge program to choose the new contents for the merged file. This 7.475 - may require input from the user. 7.476 -</para> 7.477 -</listitem> 7.478 -<listitem><para>If one changeset has modified a file, and the other has renamed 7.479 - or copied the file, make sure that the changes follow the new name 7.480 - of the file. 7.481 -</para> 7.482 -</listitem></itemizedlist> 7.483 -<para>There are more details&emdash;merging has plenty of corner cases&emdash;but 7.484 -these are the most common choices that are involved in a merge. As 7.485 -you can see, most cases are completely automatic, and indeed most 7.486 -merges finish automatically, without requiring your input to resolve 7.487 -any conflicts. 7.488 -</para> 7.489 - 7.490 -<para>When you're thinking about what happens when you commit after a merge, 7.491 -once again the working directory is <quote>the changeset I'm about to 7.492 -commit</quote>. After the <command role="hg-cmd">hg merge</command> command completes, the working 7.493 -directory has two parents; these will become the parents of the new 7.494 -changeset. 7.495 -</para> 7.496 - 7.497 -<para>Mercurial lets you perform multiple merges, but you must commit the 7.498 -results of each individual merge as you go. This is necessary because 7.499 -Mercurial only tracks two parents for both revisions and the working 7.500 -directory. While it would be technically possible to merge multiple 7.501 -changesets at once, the prospect of user confusion and making a 7.502 -terrible mess of a merge immediately becomes overwhelming. 7.503 -</para> 7.504 - 7.505 -</sect2> 7.506 -</sect1> 7.507 -<sect1> 7.508 -<title>Other interesting design features</title> 7.509 - 7.510 -<para>In the sections above, I've tried to highlight some of the most 7.511 -important aspects of Mercurial's design, to illustrate that it pays 7.512 -careful attention to reliability and performance. However, the 7.513 -attention to detail doesn't stop there. There are a number of other 7.514 -aspects of Mercurial's construction that I personally find 7.515 -interesting. I'll detail a few of them here, separate from the <quote>big 7.516 -ticket</quote> items above, so that if you're interested, you can gain a 7.517 -better idea of the amount of thinking that goes into a well-designed 7.518 -system. 7.519 -</para> 7.520 - 7.521 -<sect2> 7.522 -<title>Clever compression</title> 7.523 - 7.524 -<para>When appropriate, Mercurial will store both snapshots and deltas in 7.525 -compressed form. It does this by always <emphasis>trying to</emphasis> compress a 7.526 -snapshot or delta, but only storing the compressed version if it's 7.527 -smaller than the uncompressed version. 7.528 -</para> 7.529 - 7.530 -<para>This means that Mercurial does <quote>the right thing</quote> when storing a file 7.531 -whose native form is compressed, such as a <literal>zip</literal> archive or a 7.532 -JPEG image. When these types of files are compressed a second time, 7.533 -the resulting file is usually bigger than the once-compressed form, 7.534 -and so Mercurial will store the plain <literal>zip</literal> or JPEG. 7.535 -</para> 7.536 - 7.537 -<para>Deltas between revisions of a compressed file are usually larger than 7.538 -snapshots of the file, and Mercurial again does <quote>the right thing</quote> in 7.539 -these cases. It finds that such a delta exceeds the threshold at 7.540 -which it should store a complete snapshot of the file, so it stores 7.541 -the snapshot, again saving space compared to a naive delta-only 7.542 -approach. 7.543 -</para> 7.544 - 7.545 -<sect3> 7.546 -<title>Network recompression</title> 7.547 - 7.548 -<para>When storing revisions on disk, Mercurial uses the <quote>deflate</quote> 7.549 -compression algorithm (the same one used by the popular <literal>zip</literal> 7.550 -archive format), which balances good speed with a respectable 7.551 -compression ratio. However, when transmitting revision data over a 7.552 -network connection, Mercurial uncompresses the compressed revision 7.553 -data. 7.554 -</para> 7.555 - 7.556 -<para>If the connection is over HTTP, Mercurial recompresses the entire 7.557 -stream of data using a compression algorithm that gives a better 7.558 -compression ratio (the Burrows-Wheeler algorithm from the widely used 7.559 -<literal>bzip2</literal> compression package). This combination of algorithm 7.560 -and compression of the entire stream (instead of a revision at a time) 7.561 -substantially reduces the number of bytes to be transferred, yielding 7.562 -better network performance over almost all kinds of network. 7.563 -</para> 7.564 - 7.565 -<para>(If the connection is over <command>ssh</command>, Mercurial <emphasis>doesn't</emphasis> 7.566 -recompress the stream, because <command>ssh</command> can already do this 7.567 -itself.) 7.568 -</para> 7.569 - 7.570 -</sect3> 7.571 -</sect2> 7.572 -<sect2> 7.573 -<title>Read/write ordering and atomicity</title> 7.574 - 7.575 -<para>Appending to files isn't the whole story when it comes to guaranteeing 7.576 -that a reader won't see a partial write. If you recall 7.577 -figure <xref linkend="fig:concepts:metadata"/>, revisions in the changelog point to 7.578 -revisions in the manifest, and revisions in the manifest point to 7.579 -revisions in filelogs. This hierarchy is deliberate. 7.580 -</para> 7.581 - 7.582 -<para>A writer starts a transaction by writing filelog and manifest data, 7.583 -and doesn't write any changelog data until those are finished. A 7.584 -reader starts by reading changelog data, then manifest data, followed 7.585 -by filelog data. 7.586 -</para> 7.587 - 7.588 -<para>Since the writer has always finished writing filelog and manifest data 7.589 -before it writes to the changelog, a reader will never read a pointer 7.590 -to a partially written manifest revision from the changelog, and it will 7.591 -never read a pointer to a partially written filelog revision from the 7.592 -manifest. 7.593 -</para> 7.594 - 7.595 -</sect2> 7.596 -<sect2> 7.597 -<title>Concurrent access</title> 7.598 - 7.599 -<para>The read/write ordering and atomicity guarantees mean that Mercurial 7.600 -never needs to <emphasis>lock</emphasis> a repository when it's reading data, even 7.601 -if the repository is being written to while the read is occurring. 7.602 -This has a big effect on scalability; you can have an arbitrary number 7.603 -of Mercurial processes safely reading data from a repository safely 7.604 -all at once, no matter whether it's being written to or not. 7.605 -</para> 7.606 - 7.607 -<para>The lockless nature of reading means that if you're sharing a 7.608 -repository on a multi-user system, you don't need to grant other local 7.609 -users permission to <emphasis>write</emphasis> to your repository in order for them 7.610 -to be able to clone it or pull changes from it; they only need 7.611 -<emphasis>read</emphasis> permission. (This is <emphasis>not</emphasis> a common feature among 7.612 -revision control systems, so don't take it for granted! Most require 7.613 -readers to be able to lock a repository to access it safely, and this 7.614 -requires write permission on at least one directory, which of course 7.615 -makes for all kinds of nasty and annoying security and administrative 7.616 -problems.) 7.617 -</para> 7.618 - 7.619 -<para>Mercurial uses locks to ensure that only one process can write to a 7.620 -repository at a time (the locking mechanism is safe even over 7.621 -filesystems that are notoriously hostile to locking, such as NFS). If 7.622 -a repository is locked, a writer will wait for a while to retry if the 7.623 -repository becomes unlocked, but if the repository remains locked for 7.624 -too long, the process attempting to write will time out after a while. 7.625 -This means that your daily automated scripts won't get stuck forever 7.626 -and pile up if a system crashes unnoticed, for example. (Yes, the 7.627 -timeout is configurable, from zero to infinity.) 7.628 -</para> 7.629 - 7.630 -<sect3> 7.631 -<title>Safe dirstate access</title> 7.632 - 7.633 -<para>As with revision data, Mercurial doesn't take a lock to read the 7.634 -dirstate file; it does acquire a lock to write it. To avoid the 7.635 -possibility of reading a partially written copy of the dirstate file, 7.636 -Mercurial writes to a file with a unique name in the same directory as 7.637 -the dirstate file, then renames the temporary file atomically to 7.638 -<filename>dirstate</filename>. The file named <filename>dirstate</filename> is thus 7.639 -guaranteed to be complete, not partially written. 7.640 -</para> 7.641 - 7.642 -</sect3> 7.643 -</sect2> 7.644 -<sect2> 7.645 -<title>Avoiding seeks</title> 7.646 - 7.647 -<para>Critical to Mercurial's performance is the avoidance of seeks of the 7.648 -disk head, since any seek is far more expensive than even a 7.649 -comparatively large read operation. 7.650 -</para> 7.651 - 7.652 -<para>This is why, for example, the dirstate is stored in a single file. If 7.653 -there were a dirstate file per directory that Mercurial tracked, the 7.654 -disk would seek once per directory. Instead, Mercurial reads the 7.655 -entire single dirstate file in one step. 7.656 -</para> 7.657 - 7.658 -<para>Mercurial also uses a <quote>copy on write</quote> scheme when cloning a 7.659 -repository on local storage. Instead of copying every revlog file 7.660 -from the old repository into the new repository, it makes a <quote>hard 7.661 -link</quote>, which is a shorthand way to say <quote>these two names point to the 7.662 -same file</quote>. When Mercurial is about to write to one of a revlog's 7.663 -files, it checks to see if the number of names pointing at the file is 7.664 -greater than one. If it is, more than one repository is using the 7.665 -file, so Mercurial makes a new copy of the file that is private to 7.666 -this repository. 7.667 -</para> 7.668 - 7.669 -<para>A few revision control developers have pointed out that this idea of 7.670 -making a complete private copy of a file is not very efficient in its 7.671 -use of storage. While this is true, storage is cheap, and this method 7.672 -gives the highest performance while deferring most book-keeping to the 7.673 -operating system. An alternative scheme would most likely reduce 7.674 -performance and increase the complexity of the software, each of which 7.675 -is much more important to the <quote>feel</quote> of day-to-day use. 7.676 -</para> 7.677 - 7.678 -</sect2> 7.679 -<sect2> 7.680 -<title>Other contents of the dirstate</title> 7.681 - 7.682 -<para>Because Mercurial doesn't force you to tell it when you're modifying a 7.683 -file, it uses the dirstate to store some extra information so it can 7.684 -determine efficiently whether you have modified a file. For each file 7.685 -in the working directory, it stores the time that it last modified the 7.686 -file itself, and the size of the file at that time. 7.687 -</para> 7.688 - 7.689 -<para>When you explicitly <command role="hg-cmd">hg add</command>, <command role="hg-cmd">hg remove</command>, <command role="hg-cmd">hg rename</command> or 7.690 -<command role="hg-cmd">hg copy</command> files, Mercurial updates the dirstate so that it knows 7.691 -what to do with those files when you commit. 7.692 -</para> 7.693 - 7.694 -<para>When Mercurial is checking the states of files in the working 7.695 -directory, it first checks a file's modification time. If that has 7.696 -not changed, the file must not have been modified. If the file's size 7.697 -has changed, the file must have been modified. If the modification 7.698 -time has changed, but the size has not, only then does Mercurial need 7.699 -to read the actual contents of the file to see if they've changed. 7.700 -Storing these few extra pieces of information dramatically reduces the 7.701 -amount of data that Mercurial needs to read, which yields large 7.702 -performance improvements compared to other revision control systems. 7.703 -</para> 7.704 - 7.705 -</sect2> 7.706 -</sect1> 7.707 +<chapter id="chap:concepts"> 7.708 + <?dbhtml filename="behind-the-scenes.html"?> 7.709 + <title>Derrière le décor</title> 7.710 + 7.711 + <para id="x_2e8">À la différence de beaucoup d'outils de gestion de versions, 7.712 + les concepts sur lesquels se base Mercurial sont assez simples pour 7.713 + qu'il soit facile de comprendre comment le logiciel fonctionne. 7.714 + Bien que leur connaissance ne soit pas nécéssaire, je trouve utile 7.715 + d'avoir un <quote>modèle mental</quote> de ce qui se passe.</para> 7.716 + 7.717 + <para id="x_2e9">En effet, cette compréhension m'apporte la confiance que 7.718 + Mercurial a été développé avec soin pour être à la fois 7.719 + <emphasis>sûr</emphasis> et <emphasis>efficace</emphasis>. De surcroît, 7.720 + si il m'est facile de garder en tête ce que le logiciel fait lorsque 7.721 + j'accompli des tâches de révision, j'aurai moins de risques d'être 7.722 + surpris par son comportement.</para> 7.723 + 7.724 + <para id="x_2ea">Dans ce chapitre, nous décrirons tout d'abord les concepts 7.725 + essentiels de l'architecture de Mercurial, pour ensuite discuter quelques 7.726 + uns des détails intéressants de son implémentation.</para> 7.727 + 7.728 + <sect1> 7.729 + <title>Conservation de l'historique sous Mercurial</title> 7.730 + <sect2> 7.731 + <title>Suivi de l'historique pour un seul fichier</title> 7.732 + 7.733 + <para id="x_2eb">Lorsque Mercurial effectue un suivi des modifications 7.734 + faites à un fichier, il conserve l'historique pour ce fichier dans un 7.735 + <emphasis>filelog</emphasis> sous forme de métadonnées. Chaque entrée 7.736 + dans le filelog contient assez d'informations pour reconstituer une 7.737 + révision du fichier correspondant. Les filelogs sont des fichiers 7.738 + stockés dans le répertoire <filename role="special" 7.739 + class="directory">.hg/store/data</filename>. Un filelog contient 7.740 + des informations de deux types: les données de révision, et un index 7.741 + pour permettre à Mercurial une recherche efficace d'une révision 7.742 + donnée.</para> 7.743 + 7.744 + <para id="x_2ec">Lorsqu'un fichier devient trop gros ou a un long 7.745 + historique, son filelog se voit stocker dans un fichier de données 7.746 + (avec un suffixe <quote><literal>.d</literal></quote>) et un fichier 7.747 + index (avec un suffixe<quote><literal>.i</literal></quote>) 7.748 + distincts. La relation entre un fichier dans le répertoire de travail 7.749 + et le filelog couvrant le suivi de son historique dans le dépôt est 7.750 + illustré à la figure <xref linkend="fig:concepts:filelog"/>.</para> 7.751 + 7.752 + <figure id="fig:concepts:filelog"> 7.753 + <title>Relations entre les fichiers dans le répertoire de travail et 7.754 + leurs filelogs dans le dépôt</title> 7.755 + <mediaobject> <imageobject><imagedata 7.756 + fileref="figs/filelog.png"/></imageobject> 7.757 + <textobject><phrase>XXX add text</phrase></textobject> 7.758 + </mediaobject> </figure> 7.759 + 7.760 + </sect2> 7.761 + <sect2> 7.762 + <title>Gestion des fichiers suivis</title> 7.763 + 7.764 + <para id="x_2ee">Mercurial a recours à une structure nommée 7.765 + <emphasis>manifest</emphasis> pour rassembler les informations sur 7.766 + les fichiers dont il gère le suivi. Chaque entrée dans ce manifest 7.767 + contient des informations sur les fichiers présents dans une révision 7.768 + donnée. Une entrée store la liste des fichiers faisant partie de la 7.769 + révision, la version de chaque fichier, et quelques autres 7.770 + métadonnées sur ces fichiers.</para> 7.771 + 7.772 + </sect2> 7.773 + <sect2> 7.774 + <title>Recording changeset information</title> 7.775 + 7.776 + <para id="x_2ef">The <emphasis>changelog</emphasis> contains 7.777 + information about each changeset. Each revision records who 7.778 + committed a change, the changeset comment, other pieces of 7.779 + changeset-related information, and the revision of the manifest to 7.780 + use.</para> 7.781 + 7.782 + </sect2> 7.783 + <sect2> 7.784 + <title>Relationships between revisions</title> 7.785 + 7.786 + <para id="x_2f0">Within a changelog, a manifest, or a filelog, each 7.787 + revision stores a pointer to its immediate parent (or to its 7.788 + two parents, if it's a merge revision). As I mentioned above, 7.789 + there are also relationships between revisions 7.790 + <emphasis>across</emphasis> these structures, and they are 7.791 + hierarchical in nature.</para> 7.792 + 7.793 + <para id="x_2f1">For every changeset in a repository, there is exactly one 7.794 + revision stored in the changelog. Each revision of the 7.795 + changelog contains a pointer to a single revision of the 7.796 + manifest. A revision of the manifest stores a pointer to a 7.797 + single revision of each filelog tracked when that changeset 7.798 + was created. These relationships are illustrated in 7.799 + <xref linkend="fig:concepts:metadata"/>.</para> 7.800 + 7.801 + <figure id="fig:concepts:metadata"> 7.802 + <title>Metadata relationships</title> 7.803 + <mediaobject> 7.804 + <imageobject><imagedata fileref="figs/metadata.png"/></imageobject> 7.805 + <textobject><phrase>XXX add text</phrase></textobject> 7.806 + </mediaobject> 7.807 + </figure> 7.808 + 7.809 + <para id="x_2f3">As the illustration shows, there is 7.810 + <emphasis>not</emphasis> a <quote>one to one</quote> 7.811 + relationship between revisions in the changelog, manifest, or 7.812 + filelog. If a file that 7.813 + Mercurial tracks hasn't changed between two changesets, the 7.814 + entry for that file in the two revisions of the manifest will 7.815 + point to the same revision of its filelog<footnote> 7.816 + <para id="x_725">It is possible (though unusual) for the manifest to 7.817 + remain the same between two changesets, in which case the 7.818 + changelog entries for those changesets will point to the 7.819 + same revision of the manifest.</para> 7.820 + </footnote>.</para> 7.821 + 7.822 + </sect2> 7.823 + </sect1> 7.824 + <sect1> 7.825 + <title>Safe, efficient storage</title> 7.826 + 7.827 + <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are 7.828 + provided by a single structure called the 7.829 + <emphasis>revlog</emphasis>.</para> 7.830 + 7.831 + <sect2> 7.832 + <title>Efficient storage</title> 7.833 + 7.834 + <para id="x_2f5">The revlog provides efficient storage of revisions using a 7.835 + <emphasis>delta</emphasis> mechanism. Instead of storing a 7.836 + complete copy of a file for each revision, it stores the 7.837 + changes needed to transform an older revision into the new 7.838 + revision. For many kinds of file data, these deltas are 7.839 + typically a fraction of a percent of the size of a full copy 7.840 + of a file.</para> 7.841 + 7.842 + <para id="x_2f6">Some obsolete revision control systems can only work with 7.843 + deltas of text files. They must either store binary files as 7.844 + complete snapshots or encoded into a text representation, both 7.845 + of which are wasteful approaches. Mercurial can efficiently 7.846 + handle deltas of files with arbitrary binary contents; it 7.847 + doesn't need to treat text as special.</para> 7.848 + 7.849 + </sect2> 7.850 + <sect2 id="sec:concepts:txn"> 7.851 + <title>Safe operation</title> 7.852 + 7.853 + <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to 7.854 + the end of a revlog file. It never modifies a section of a 7.855 + file after it has written it. This is both more robust and 7.856 + efficient than schemes that need to modify or rewrite 7.857 + data.</para> 7.858 + 7.859 + <para id="x_2f8">In addition, Mercurial treats every write as part of a 7.860 + <emphasis>transaction</emphasis> that can span a number of 7.861 + files. A transaction is <emphasis>atomic</emphasis>: either 7.862 + the entire transaction succeeds and its effects are all 7.863 + visible to readers in one go, or the whole thing is undone. 7.864 + This guarantee of atomicity means that if you're running two 7.865 + copies of Mercurial, where one is reading data and one is 7.866 + writing it, the reader will never see a partially written 7.867 + result that might confuse it.</para> 7.868 + 7.869 + <para id="x_2f9">The fact that Mercurial only appends to files makes it 7.870 + easier to provide this transactional guarantee. The easier it 7.871 + is to do stuff like this, the more confident you should be 7.872 + that it's done correctly.</para> 7.873 + 7.874 + </sect2> 7.875 + <sect2> 7.876 + <title>Fast retrieval</title> 7.877 + 7.878 + <para id="x_2fa">Mercurial cleverly avoids a pitfall common to 7.879 + all earlier revision control systems: the problem of 7.880 + <emphasis>inefficient retrieval</emphasis>. Most revision 7.881 + control systems store the contents of a revision as an 7.882 + incremental series of modifications against a 7.883 + <quote>snapshot</quote>. (Some base the snapshot on the 7.884 + oldest revision, others on the newest.) To reconstruct a 7.885 + specific revision, you must first read the snapshot, and then 7.886 + every one of the revisions between the snapshot and your 7.887 + target revision. The more history that a file accumulates, 7.888 + the more revisions you must read, hence the longer it takes to 7.889 + reconstruct a particular revision.</para> 7.890 + 7.891 + <figure id="fig:concepts:snapshot"> 7.892 + <title>Snapshot of a revlog, with incremental deltas</title> 7.893 + <mediaobject> 7.894 + <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject> 7.895 + <textobject><phrase>XXX add text</phrase></textobject> 7.896 + </mediaobject> 7.897 + </figure> 7.898 + 7.899 + <para id="x_2fc">The innovation that Mercurial applies to this problem is 7.900 + simple but effective. Once the cumulative amount of delta 7.901 + information stored since the last snapshot exceeds a fixed 7.902 + threshold, it stores a new snapshot (compressed, of course), 7.903 + instead of another delta. This makes it possible to 7.904 + reconstruct <emphasis>any</emphasis> revision of a file 7.905 + quickly. This approach works so well that it has since been 7.906 + copied by several other revision control systems.</para> 7.907 + 7.908 + <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates 7.909 + the idea. In an entry in a revlog's index file, Mercurial 7.910 + stores the range of entries from the data file that it must 7.911 + read to reconstruct a particular revision.</para> 7.912 + 7.913 + <sect3> 7.914 + <title>Aside: the influence of video compression</title> 7.915 + 7.916 + <para id="x_2fe">If you're familiar with video compression or 7.917 + have ever watched a TV feed through a digital cable or 7.918 + satellite service, you may know that most video compression 7.919 + schemes store each frame of video as a delta against its 7.920 + predecessor frame.</para> 7.921 + 7.922 + <para id="x_2ff">Mercurial borrows this idea to make it 7.923 + possible to reconstruct a revision from a snapshot and a 7.924 + small number of deltas.</para> 7.925 + 7.926 + </sect3> 7.927 + </sect2> 7.928 + <sect2> 7.929 + <title>Identification and strong integrity</title> 7.930 + 7.931 + <para id="x_300">Along with delta or snapshot information, a revlog entry 7.932 + contains a cryptographic hash of the data that it represents. 7.933 + This makes it difficult to forge the contents of a revision, 7.934 + and easy to detect accidental corruption.</para> 7.935 + 7.936 + <para id="x_301">Hashes provide more than a mere check against corruption; 7.937 + they are used as the identifiers for revisions. The changeset 7.938 + identification hashes that you see as an end user are from 7.939 + revisions of the changelog. Although filelogs and the 7.940 + manifest also use hashes, Mercurial only uses these behind the 7.941 + scenes.</para> 7.942 + 7.943 + <para id="x_302">Mercurial verifies that hashes are correct when it 7.944 + retrieves file revisions and when it pulls changes from 7.945 + another repository. If it encounters an integrity problem, it 7.946 + will complain and stop whatever it's doing.</para> 7.947 + 7.948 + <para id="x_303">In addition to the effect it has on retrieval efficiency, 7.949 + Mercurial's use of periodic snapshots makes it more robust 7.950 + against partial data corruption. If a revlog becomes partly 7.951 + corrupted due to a hardware error or system bug, it's often 7.952 + possible to reconstruct some or most revisions from the 7.953 + uncorrupted sections of the revlog, both before and after the 7.954 + corrupted section. This would not be possible with a 7.955 + delta-only storage model.</para> 7.956 + </sect2> 7.957 + </sect1> 7.958 + 7.959 + <sect1> 7.960 + <title>Revision history, branching, and merging</title> 7.961 + 7.962 + <para id="x_304">Every entry in a Mercurial revlog knows the identity of its 7.963 + immediate ancestor revision, usually referred to as its 7.964 + <emphasis>parent</emphasis>. In fact, a revision contains room 7.965 + for not one parent, but two. Mercurial uses a special hash, 7.966 + called the <quote>null ID</quote>, to represent the idea 7.967 + <quote>there is no parent here</quote>. This hash is simply a 7.968 + string of zeroes.</para> 7.969 + 7.970 + <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see 7.971 + an example of the conceptual structure of a revlog. Filelogs, 7.972 + manifests, and changelogs all have this same structure; they 7.973 + differ only in the kind of data stored in each delta or 7.974 + snapshot.</para> 7.975 + 7.976 + <para id="x_306">The first revision in a revlog (at the bottom of the image) 7.977 + has the null ID in both of its parent slots. For a 7.978 + <quote>normal</quote> revision, its first parent slot contains 7.979 + the ID of its parent revision, and its second contains the null 7.980 + ID, indicating that the revision has only one real parent. Any 7.981 + two revisions that have the same parent ID are branches. A 7.982 + revision that represents a merge between branches has two normal 7.983 + revision IDs in its parent slots.</para> 7.984 + 7.985 + <figure id="fig:concepts:revlog"> 7.986 + <title>The conceptual structure of a revlog</title> 7.987 + <mediaobject> 7.988 + <imageobject><imagedata fileref="figs/revlog.png"/></imageobject> 7.989 + <textobject><phrase>XXX add text</phrase></textobject> 7.990 + </mediaobject> 7.991 + </figure> 7.992 + 7.993 + </sect1> 7.994 + <sect1> 7.995 + <title>The working directory</title> 7.996 + 7.997 + <para id="x_307">In the working directory, Mercurial stores a snapshot of the 7.998 + files from the repository as of a particular changeset.</para> 7.999 + 7.1000 + <para id="x_308">The working directory <quote>knows</quote> which changeset 7.1001 + it contains. When you update the working directory to contain a 7.1002 + particular changeset, Mercurial looks up the appropriate 7.1003 + revision of the manifest to find out which files it was tracking 7.1004 + at the time that changeset was committed, and which revision of 7.1005 + each file was then current. It then recreates a copy of each of 7.1006 + those files, with the same contents it had when the changeset 7.1007 + was committed.</para> 7.1008 + 7.1009 + <para id="x_309">The <emphasis>dirstate</emphasis> is a special 7.1010 + structure that contains Mercurial's knowledge of the working 7.1011 + directory. It is maintained as a file named 7.1012 + <filename>.hg/dirstate</filename> inside a repository. The 7.1013 + dirstate details which changeset the working directory is 7.1014 + updated to, and all of the files that Mercurial is tracking in 7.1015 + the working directory. It also lets Mercurial quickly notice 7.1016 + changed files, by recording their checkout times and 7.1017 + sizes.</para> 7.1018 + 7.1019 + <para id="x_30a">Just as a revision of a revlog has room for two parents, so 7.1020 + that it can represent either a normal revision (with one parent) 7.1021 + or a merge of two earlier revisions, the dirstate has slots for 7.1022 + two parents. When you use the <command role="hg-cmd">hg 7.1023 + update</command> command, the changeset that you update to is 7.1024 + stored in the <quote>first parent</quote> slot, and the null ID 7.1025 + in the second. When you <command role="hg-cmd">hg 7.1026 + merge</command> with another changeset, the first parent 7.1027 + remains unchanged, and the second parent is filled in with the 7.1028 + changeset you're merging with. The <command role="hg-cmd">hg 7.1029 + parents</command> command tells you what the parents of the 7.1030 + dirstate are.</para> 7.1031 + 7.1032 + <sect2> 7.1033 + <title>What happens when you commit</title> 7.1034 + 7.1035 + <para id="x_30b">The dirstate stores parent information for more than just 7.1036 + book-keeping purposes. Mercurial uses the parents of the 7.1037 + dirstate as <emphasis>the parents of a new 7.1038 + changeset</emphasis> when you perform a commit.</para> 7.1039 + 7.1040 + <figure id="fig:concepts:wdir"> 7.1041 + <title>The working directory can have two parents</title> 7.1042 + <mediaobject> 7.1043 + <imageobject><imagedata fileref="figs/wdir.png"/></imageobject> 7.1044 + <textobject><phrase>XXX add text</phrase></textobject> 7.1045 + </mediaobject> 7.1046 + </figure> 7.1047 + 7.1048 + <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the 7.1049 + normal state of the working directory, where it has a single 7.1050 + changeset as parent. That changeset is the 7.1051 + <emphasis>tip</emphasis>, the newest changeset in the 7.1052 + repository that has no children.</para> 7.1053 + 7.1054 + <figure id="fig:concepts:wdir-after-commit"> 7.1055 + <title>The working directory gains new parents after a 7.1056 + commit</title> 7.1057 + <mediaobject> 7.1058 + <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject> 7.1059 + <textobject><phrase>XXX add text</phrase></textobject> 7.1060 + </mediaobject> 7.1061 + </figure> 7.1062 + 7.1063 + <para id="x_30f">It's useful to think of the working directory as 7.1064 + <quote>the changeset I'm about to commit</quote>. Any files 7.1065 + that you tell Mercurial that you've added, removed, renamed, 7.1066 + or copied will be reflected in that changeset, as will 7.1067 + modifications to any files that Mercurial is already tracking; 7.1068 + the new changeset will have the parents of the working 7.1069 + directory as its parents.</para> 7.1070 + 7.1071 + <para id="x_310">After a commit, Mercurial will update the 7.1072 + parents of the working directory, so that the first parent is 7.1073 + the ID of the new changeset, and the second is the null ID. 7.1074 + This is shown in <xref 7.1075 + linkend="fig:concepts:wdir-after-commit"/>. Mercurial 7.1076 + doesn't touch any of the files in the working directory when 7.1077 + you commit; it just modifies the dirstate to note its new 7.1078 + parents.</para> 7.1079 + 7.1080 + </sect2> 7.1081 + <sect2> 7.1082 + <title>Creating a new head</title> 7.1083 + 7.1084 + <para id="x_311">It's perfectly normal to update the working directory to a 7.1085 + changeset other than the current tip. For example, you might 7.1086 + want to know what your project looked like last Tuesday, or 7.1087 + you could be looking through changesets to see which one 7.1088 + introduced a bug. In cases like this, the natural thing to do 7.1089 + is update the working directory to the changeset you're 7.1090 + interested in, and then examine the files in the working 7.1091 + directory directly to see their contents as they were when you 7.1092 + committed that changeset. The effect of this is shown in 7.1093 + <xref linkend="fig:concepts:wdir-pre-branch"/>.</para> 7.1094 + 7.1095 + <figure id="fig:concepts:wdir-pre-branch"> 7.1096 + <title>The working directory, updated to an older 7.1097 + changeset</title> 7.1098 + <mediaobject> 7.1099 + <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject> 7.1100 + <textobject><phrase>XXX add text</phrase></textobject> 7.1101 + </mediaobject> 7.1102 + </figure> 7.1103 + 7.1104 + <para id="x_313">Having updated the working directory to an 7.1105 + older changeset, what happens if you make some changes, and 7.1106 + then commit? Mercurial behaves in the same way as I outlined 7.1107 + above. The parents of the working directory become the 7.1108 + parents of the new changeset. This new changeset has no 7.1109 + children, so it becomes the new tip. And the repository now 7.1110 + contains two changesets that have no children; we call these 7.1111 + <emphasis>heads</emphasis>. You can see the structure that 7.1112 + this creates in <xref 7.1113 + linkend="fig:concepts:wdir-branch"/>.</para> 7.1114 + 7.1115 + <figure id="fig:concepts:wdir-branch"> 7.1116 + <title>After a commit made while synced to an older 7.1117 + changeset</title> 7.1118 + <mediaobject> 7.1119 + <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject> 7.1120 + <textobject><phrase>XXX add text</phrase></textobject> 7.1121 + </mediaobject> 7.1122 + </figure> 7.1123 + 7.1124 + <note> 7.1125 + <para id="x_315">If you're new to Mercurial, you should keep 7.1126 + in mind a common <quote>error</quote>, which is to use the 7.1127 + <command role="hg-cmd">hg pull</command> command without any 7.1128 + options. By default, the <command role="hg-cmd">hg 7.1129 + pull</command> command <emphasis>does not</emphasis> 7.1130 + update the working directory, so you'll bring new changesets 7.1131 + into your repository, but the working directory will stay 7.1132 + synced at the same changeset as before the pull. If you 7.1133 + make some changes and commit afterwards, you'll thus create 7.1134 + a new head, because your working directory isn't synced to 7.1135 + whatever the current tip is. To combine the operation of a 7.1136 + pull, followed by an update, run <command>hg pull 7.1137 + -u</command>.</para> 7.1138 + 7.1139 + <para id="x_316">I put the word <quote>error</quote> in quotes 7.1140 + because all that you need to do to rectify the situation 7.1141 + where you created a new head by accident is 7.1142 + <command role="hg-cmd">hg merge</command>, then <command 7.1143 + role="hg-cmd">hg commit</command>. In other words, this 7.1144 + almost never has negative consequences; it's just something 7.1145 + of a surprise for newcomers. I'll discuss other ways to 7.1146 + avoid this behavior, and why Mercurial behaves in this 7.1147 + initially surprising way, later on.</para> 7.1148 + </note> 7.1149 + 7.1150 + </sect2> 7.1151 + <sect2> 7.1152 + <title>Merging changes</title> 7.1153 + 7.1154 + <para id="x_317">When you run the <command role="hg-cmd">hg 7.1155 + merge</command> command, Mercurial leaves the first parent 7.1156 + of the working directory unchanged, and sets the second parent 7.1157 + to the changeset you're merging with, as shown in <xref 7.1158 + linkend="fig:concepts:wdir-merge"/>.</para> 7.1159 + 7.1160 + <figure id="fig:concepts:wdir-merge"> 7.1161 + <title>Merging two heads</title> 7.1162 + <mediaobject> 7.1163 + <imageobject> 7.1164 + <imagedata fileref="figs/wdir-merge.png"/> 7.1165 + </imageobject> 7.1166 + <textobject><phrase>XXX add text</phrase></textobject> 7.1167 + </mediaobject> 7.1168 + </figure> 7.1169 + 7.1170 + <para id="x_319">Mercurial also has to modify the working directory, to 7.1171 + merge the files managed in the two changesets. Simplified a 7.1172 + little, the merging process goes like this, for every file in 7.1173 + the manifests of both changesets.</para> 7.1174 + <itemizedlist> 7.1175 + <listitem><para id="x_31a">If neither changeset has modified a file, do 7.1176 + nothing with that file.</para> 7.1177 + </listitem> 7.1178 + <listitem><para id="x_31b">If one changeset has modified a file, and the 7.1179 + other hasn't, create the modified copy of the file in the 7.1180 + working directory.</para> 7.1181 + </listitem> 7.1182 + <listitem><para id="x_31c">If one changeset has removed a file, and the 7.1183 + other hasn't (or has also deleted it), delete the file 7.1184 + from the working directory.</para> 7.1185 + </listitem> 7.1186 + <listitem><para id="x_31d">If one changeset has removed a file, but the 7.1187 + other has modified the file, ask the user what to do: keep 7.1188 + the modified file, or remove it?</para> 7.1189 + </listitem> 7.1190 + <listitem><para id="x_31e">If both changesets have modified a file, 7.1191 + invoke an external merge program to choose the new 7.1192 + contents for the merged file. This may require input from 7.1193 + the user.</para> 7.1194 + </listitem> 7.1195 + <listitem><para id="x_31f">If one changeset has modified a file, and the 7.1196 + other has renamed or copied the file, make sure that the 7.1197 + changes follow the new name of the file.</para> 7.1198 + </listitem></itemizedlist> 7.1199 + <para id="x_320">There are more details&emdash;merging has plenty of corner 7.1200 + cases&emdash;but these are the most common choices that are 7.1201 + involved in a merge. As you can see, most cases are 7.1202 + completely automatic, and indeed most merges finish 7.1203 + automatically, without requiring your input to resolve any 7.1204 + conflicts.</para> 7.1205 + 7.1206 + <para id="x_321">When you're thinking about what happens when you commit 7.1207 + after a merge, once again the working directory is <quote>the 7.1208 + changeset I'm about to commit</quote>. After the <command 7.1209 + role="hg-cmd">hg merge</command> command completes, the 7.1210 + working directory has two parents; these will become the 7.1211 + parents of the new changeset.</para> 7.1212 + 7.1213 + <para id="x_322">Mercurial lets you perform multiple merges, but 7.1214 + you must commit the results of each individual merge as you 7.1215 + go. This is necessary because Mercurial only tracks two 7.1216 + parents for both revisions and the working directory. While 7.1217 + it would be technically feasible to merge multiple changesets 7.1218 + at once, Mercurial avoids this for simplicity. With multi-way 7.1219 + merges, the risks of user confusion, nasty conflict 7.1220 + resolution, and making a terrible mess of a merge would grow 7.1221 + intolerable.</para> 7.1222 + 7.1223 + </sect2> 7.1224 + 7.1225 + <sect2> 7.1226 + <title>Merging and renames</title> 7.1227 + 7.1228 + <para id="x_69a">A surprising number of revision control systems pay little 7.1229 + or no attention to a file's <emphasis>name</emphasis> over 7.1230 + time. For instance, it used to be common that if a file got 7.1231 + renamed on one side of a merge, the changes from the other 7.1232 + side would be silently dropped.</para> 7.1233 + 7.1234 + <para id="x_69b">Mercurial records metadata when you tell it to perform a 7.1235 + rename or copy. It uses this metadata during a merge to do the 7.1236 + right thing in the case of a merge. For instance, if I rename 7.1237 + a file, and you edit it without renaming it, when we merge our 7.1238 + work the file will be renamed and have your edits 7.1239 + applied.</para> 7.1240 + </sect2> 7.1241 + </sect1> 7.1242 + 7.1243 + <sect1> 7.1244 + <title>Other interesting design features</title> 7.1245 + 7.1246 + <para id="x_323">In the sections above, I've tried to highlight some of the 7.1247 + most important aspects of Mercurial's design, to illustrate that 7.1248 + it pays careful attention to reliability and performance. 7.1249 + However, the attention to detail doesn't stop there. There are 7.1250 + a number of other aspects of Mercurial's construction that I 7.1251 + personally find interesting. I'll detail a few of them here, 7.1252 + separate from the <quote>big ticket</quote> items above, so that 7.1253 + if you're interested, you can gain a better idea of the amount 7.1254 + of thinking that goes into a well-designed system.</para> 7.1255 + 7.1256 + <sect2> 7.1257 + <title>Clever compression</title> 7.1258 + 7.1259 + <para id="x_324">When appropriate, Mercurial will store both snapshots and 7.1260 + deltas in compressed form. It does this by always 7.1261 + <emphasis>trying to</emphasis> compress a snapshot or delta, 7.1262 + but only storing the compressed version if it's smaller than 7.1263 + the uncompressed version.</para> 7.1264 + 7.1265 + <para id="x_325">This means that Mercurial does <quote>the right 7.1266 + thing</quote> when storing a file whose native form is 7.1267 + compressed, such as a <literal>zip</literal> archive or a JPEG 7.1268 + image. When these types of files are compressed a second 7.1269 + time, the resulting file is usually bigger than the 7.1270 + once-compressed form, and so Mercurial will store the plain 7.1271 + <literal>zip</literal> or JPEG.</para> 7.1272 + 7.1273 + <para id="x_326">Deltas between revisions of a compressed file are usually 7.1274 + larger than snapshots of the file, and Mercurial again does 7.1275 + <quote>the right thing</quote> in these cases. It finds that 7.1276 + such a delta exceeds the threshold at which it should store a 7.1277 + complete snapshot of the file, so it stores the snapshot, 7.1278 + again saving space compared to a naive delta-only 7.1279 + approach.</para> 7.1280 + 7.1281 + <sect3> 7.1282 + <title>Network recompression</title> 7.1283 + 7.1284 + <para id="x_327">When storing revisions on disk, Mercurial uses the 7.1285 + <quote>deflate</quote> compression algorithm (the same one 7.1286 + used by the popular <literal>zip</literal> archive format), 7.1287 + which balances good speed with a respectable compression 7.1288 + ratio. However, when transmitting revision data over a 7.1289 + network connection, Mercurial uncompresses the compressed 7.1290 + revision data.</para> 7.1291 + 7.1292 + <para id="x_328">If the connection is over HTTP, Mercurial recompresses 7.1293 + the entire stream of data using a compression algorithm that 7.1294 + gives a better compression ratio (the Burrows-Wheeler 7.1295 + algorithm from the widely used <literal>bzip2</literal> 7.1296 + compression package). This combination of algorithm and 7.1297 + compression of the entire stream (instead of a revision at a 7.1298 + time) substantially reduces the number of bytes to be 7.1299 + transferred, yielding better network performance over most 7.1300 + kinds of network.</para> 7.1301 + 7.1302 + <para id="x_329">If the connection is over 7.1303 + <command>ssh</command>, Mercurial 7.1304 + <emphasis>doesn't</emphasis> recompress the stream, because 7.1305 + <command>ssh</command> can already do this itself. You can 7.1306 + tell Mercurial to always use <command>ssh</command>'s 7.1307 + compression feature by editing the 7.1308 + <filename>.hgrc</filename> file in your home directory as 7.1309 + follows.</para> 7.1310 + 7.1311 + <programlisting>[ui] 7.1312 +ssh = ssh -C</programlisting> 7.1313 + 7.1314 + </sect3> 7.1315 + </sect2> 7.1316 + <sect2> 7.1317 + <title>Read/write ordering and atomicity</title> 7.1318 + 7.1319 + <para id="x_32a">Appending to files isn't the whole story when 7.1320 + it comes to guaranteeing that a reader won't see a partial 7.1321 + write. If you recall <xref linkend="fig:concepts:metadata"/>, 7.1322 + revisions in the changelog point to revisions in the manifest, 7.1323 + and revisions in the manifest point to revisions in filelogs. 7.1324 + This hierarchy is deliberate.</para> 7.1325 + 7.1326 + <para id="x_32b">A writer starts a transaction by writing filelog and 7.1327 + manifest data, and doesn't write any changelog data until 7.1328 + those are finished. A reader starts by reading changelog 7.1329 + data, then manifest data, followed by filelog data.</para> 7.1330 + 7.1331 + <para id="x_32c">Since the writer has always finished writing filelog and 7.1332 + manifest data before it writes to the changelog, a reader will 7.1333 + never read a pointer to a partially written manifest revision 7.1334 + from the changelog, and it will never read a pointer to a 7.1335 + partially written filelog revision from the manifest.</para> 7.1336 + 7.1337 + </sect2> 7.1338 + <sect2> 7.1339 + <title>Concurrent access</title> 7.1340 + 7.1341 + <para id="x_32d">The read/write ordering and atomicity guarantees mean that 7.1342 + Mercurial never needs to <emphasis>lock</emphasis> a 7.1343 + repository when it's reading data, even if the repository is 7.1344 + being written to while the read is occurring. This has a big 7.1345 + effect on scalability; you can have an arbitrary number of 7.1346 + Mercurial processes safely reading data from a repository 7.1347 + all at once, no matter whether it's being written to or 7.1348 + not.</para> 7.1349 + 7.1350 + <para id="x_32e">The lockless nature of reading means that if you're 7.1351 + sharing a repository on a multi-user system, you don't need to 7.1352 + grant other local users permission to 7.1353 + <emphasis>write</emphasis> to your repository in order for 7.1354 + them to be able to clone it or pull changes from it; they only 7.1355 + need <emphasis>read</emphasis> permission. (This is 7.1356 + <emphasis>not</emphasis> a common feature among revision 7.1357 + control systems, so don't take it for granted! Most require 7.1358 + readers to be able to lock a repository to access it safely, 7.1359 + and this requires write permission on at least one directory, 7.1360 + which of course makes for all kinds of nasty and annoying 7.1361 + security and administrative problems.)</para> 7.1362 + 7.1363 + <para id="x_32f">Mercurial uses locks to ensure that only one process can 7.1364 + write to a repository at a time (the locking mechanism is safe 7.1365 + even over filesystems that are notoriously hostile to locking, 7.1366 + such as NFS). If a repository is locked, a writer will wait 7.1367 + for a while to retry if the repository becomes unlocked, but 7.1368 + if the repository remains locked for too long, the process 7.1369 + attempting to write will time out after a while. This means 7.1370 + that your daily automated scripts won't get stuck forever and 7.1371 + pile up if a system crashes unnoticed, for example. (Yes, the 7.1372 + timeout is configurable, from zero to infinity.)</para> 7.1373 + 7.1374 + <sect3> 7.1375 + <title>Safe dirstate access</title> 7.1376 + 7.1377 + <para id="x_330">As with revision data, Mercurial doesn't take a lock to 7.1378 + read the dirstate file; it does acquire a lock to write it. 7.1379 + To avoid the possibility of reading a partially written copy 7.1380 + of the dirstate file, Mercurial writes to a file with a 7.1381 + unique name in the same directory as the dirstate file, then 7.1382 + renames the temporary file atomically to 7.1383 + <filename>dirstate</filename>. The file named 7.1384 + <filename>dirstate</filename> is thus guaranteed to be 7.1385 + complete, not partially written.</para> 7.1386 + 7.1387 + </sect3> 7.1388 + </sect2> 7.1389 + <sect2> 7.1390 + <title>Avoiding seeks</title> 7.1391 + 7.1392 + <para id="x_331">Critical to Mercurial's performance is the avoidance of 7.1393 + seeks of the disk head, since any seek is far more expensive 7.1394 + than even a comparatively large read operation.</para> 7.1395 + 7.1396 + <para id="x_332">This is why, for example, the dirstate is stored in a 7.1397 + single file. If there were a dirstate file per directory that 7.1398 + Mercurial tracked, the disk would seek once per directory. 7.1399 + Instead, Mercurial reads the entire single dirstate file in 7.1400 + one step.</para> 7.1401 + 7.1402 + <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme 7.1403 + when cloning a repository on local storage. Instead of 7.1404 + copying every revlog file from the old repository into the new 7.1405 + repository, it makes a <quote>hard link</quote>, which is a 7.1406 + shorthand way to say <quote>these two names point to the same 7.1407 + file</quote>. When Mercurial is about to write to one of a 7.1408 + revlog's files, it checks to see if the number of names 7.1409 + pointing at the file is greater than one. If it is, more than 7.1410 + one repository is using the file, so Mercurial makes a new 7.1411 + copy of the file that is private to this repository.</para> 7.1412 + 7.1413 + <para id="x_334">A few revision control developers have pointed out that 7.1414 + this idea of making a complete private copy of a file is not 7.1415 + very efficient in its use of storage. While this is true, 7.1416 + storage is cheap, and this method gives the highest 7.1417 + performance while deferring most book-keeping to the operating 7.1418 + system. An alternative scheme would most likely reduce 7.1419 + performance and increase the complexity of the software, but 7.1420 + speed and simplicity are key to the <quote>feel</quote> of 7.1421 + day-to-day use.</para> 7.1422 + 7.1423 + </sect2> 7.1424 + <sect2> 7.1425 + <title>Other contents of the dirstate</title> 7.1426 + 7.1427 + <para id="x_335">Because Mercurial doesn't force you to tell it when you're 7.1428 + modifying a file, it uses the dirstate to store some extra 7.1429 + information so it can determine efficiently whether you have 7.1430 + modified a file. For each file in the working directory, it 7.1431 + stores the time that it last modified the file itself, and the 7.1432 + size of the file at that time.</para> 7.1433 + 7.1434 + <para id="x_336">When you explicitly <command role="hg-cmd">hg 7.1435 + add</command>, <command role="hg-cmd">hg remove</command>, 7.1436 + <command role="hg-cmd">hg rename</command> or <command 7.1437 + role="hg-cmd">hg copy</command> files, Mercurial updates the 7.1438 + dirstate so that it knows what to do with those files when you 7.1439 + commit.</para> 7.1440 + 7.1441 + <para id="x_337">The dirstate helps Mercurial to efficiently 7.1442 + check the status of files in a repository.</para> 7.1443 + 7.1444 + <itemizedlist> 7.1445 + <listitem> 7.1446 + <para id="x_726">When Mercurial checks the state of a file in the 7.1447 + working directory, it first checks a file's modification 7.1448 + time against the time in the dirstate that records when 7.1449 + Mercurial last wrote the file. If the last modified time 7.1450 + is the same as the time when Mercurial wrote the file, the 7.1451 + file must not have been modified, so Mercurial does not 7.1452 + need to check any further.</para> 7.1453 + </listitem> 7.1454 + <listitem> 7.1455 + <para id="x_727">If the file's size has changed, the file must have 7.1456 + been modified. If the modification time has changed, but 7.1457 + the size has not, only then does Mercurial need to 7.1458 + actually read the contents of the file to see if it has 7.1459 + changed.</para> 7.1460 + </listitem> 7.1461 + </itemizedlist> 7.1462 + 7.1463 + <para id="x_728">Storing the modification time and size dramatically 7.1464 + reduces the number of read operations that Mercurial needs to 7.1465 + perform when we run commands like <command>hg status</command>. 7.1466 + This results in large performance improvements.</para> 7.1467 + </sect2> 7.1468 + </sect1> 7.1469 </chapter> 7.1470 7.1471 <!-- 7.1472 local variables: 7.1473 sgml-parent-document: ("00book.xml" "book" "chapter") 7.1474 end: 7.1475 ---> 7.1476 \ No newline at end of file 7.1477 +-->
8.1 --- a/fr/ch05-daily.xml Sat Sep 12 17:58:26 2009 +0200 8.2 +++ b/fr/ch05-daily.xml Sat Sep 12 17:58:56 2009 +0200 8.3 @@ -1,474 +1,871 @@ 8.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 8.5 8.6 -<chapter> 8.7 -<title>Mercurial in daily use</title> 8.8 -<para>\label{chap:daily}</para> 8.9 - 8.10 -<sect1> 8.11 -<title>Telling Mercurial which files to track</title> 8.12 - 8.13 -<para>Mercurial does not work with files in your repository unless you tell 8.14 -it to manage them. The <command role="hg-cmd">hg status</command> command will tell you which 8.15 -files Mercurial doesn't know about; it uses a <quote><literal>?</literal></quote> to 8.16 -display such files.</para> 8.17 - 8.18 -<para>To tell Mercurial to track a file, use the <command role="hg-cmd">hg add</command> command. Once 8.19 -you have added a file, the entry in the output of <command role="hg-cmd">hg status</command> for 8.20 -that file changes from <quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>. 8.21 -<!-- &interaction.daily.files.add; --></para> 8.22 - 8.23 -<para>After you run a <command role="hg-cmd">hg commit</command>, the files that you added before the 8.24 -commit will no longer be listed in the output of <command role="hg-cmd">hg status</command>. The 8.25 -reason for this is that <command role="hg-cmd">hg status</command> only tells you about 8.26 -<quote>interesting</quote> files&emdash;those that you have modified or told Mercurial 8.27 -to do something with&emdash;by default. If you have a repository that 8.28 -contains thousands of files, you will rarely want to know about files 8.29 -that Mercurial is tracking, but that have not changed. (You can still 8.30 -get this information; we'll return to this later.)</para> 8.31 - 8.32 -<para>Once you add a file, Mercurial doesn't do anything with it 8.33 -immediately. Instead, it will take a snapshot of the file's state the 8.34 -next time you perform a commit. It will then continue to track the 8.35 -changes you make to the file every time you commit, until you remove 8.36 -the file.</para> 8.37 - 8.38 -<sect2> 8.39 -<title>Explicit versus implicit file naming</title> 8.40 - 8.41 -<para>A useful behaviour that Mercurial has is that if you pass the name of 8.42 -a directory to a command, every Mercurial command will treat this as 8.43 -<quote>I want to operate on every file in this directory and its 8.44 -subdirectories</quote>. 8.45 -<!-- &interaction.daily.files.add-dir; --> 8.46 -Notice in this example that Mercurial printed the names of the files 8.47 -it added, whereas it didn't do so when we added the file named 8.48 -<filename>a</filename> in the earlier example.</para> 8.49 - 8.50 -<para>What's going on is that in the former case, we explicitly named the 8.51 -file to add on the command line, so the assumption that Mercurial 8.52 -makes in such cases is that you know what you were doing, and it 8.53 -doesn't print any output.</para> 8.54 - 8.55 -<para>However, when we <emphasis>imply</emphasis> the names of files by giving the name of 8.56 -a directory, Mercurial takes the extra step of printing the name of 8.57 -each file that it does something with. This makes it more clear what 8.58 -is happening, and reduces the likelihood of a silent and nasty 8.59 -surprise. This behaviour is common to most Mercurial commands.</para> 8.60 - 8.61 -</sect2> 8.62 -<sect2> 8.63 -<title>Aside: Mercurial tracks files, not directories</title> 8.64 - 8.65 -<para>Mercurial does not track directory information. Instead, it tracks 8.66 -the path to a file. Before creating a file, it first creates any 8.67 -missing directory components of the path. After it deletes a file, it 8.68 -then deletes any empty directories that were in the deleted file's 8.69 -path. This sounds like a trivial distinction, but it has one minor 8.70 -practical consequence: it is not possible to represent a completely 8.71 -empty directory in Mercurial. 8.72 -</para> 8.73 - 8.74 -<para>Empty directories are rarely useful, and there are unintrusive 8.75 -workarounds that you can use to achieve an appropriate effect. The 8.76 -developers of Mercurial thus felt that the complexity that would be 8.77 -required to manage empty directories was not worth the limited benefit 8.78 -this feature would bring. 8.79 -</para> 8.80 - 8.81 -<para>If you need an empty directory in your repository, there are a few 8.82 -ways to achieve this. One is to create a directory, then <command role="hg-cmd">hg add</command> a 8.83 -<quote>hidden</quote> file to that directory. On Unix-like systems, any file 8.84 -name that begins with a period (<quote><literal>.</literal></quote>) is treated as hidden 8.85 -by most commands and GUI tools. This approach is illustrated in 8.86 -figure <xref linkend="ex:daily:hidden"/>. 8.87 -</para> 8.88 - 8.89 -<informalfigure> 8.90 -<para> <!-- &interaction.daily.files.hidden; --> 8.91 - <caption><para>Simulating an empty directory using a hidden file</para></caption> 8.92 - \label{ex:daily:hidden} 8.93 -</para> 8.94 -</informalfigure> 8.95 - 8.96 -<para>Another way to tackle a need for an empty directory is to simply 8.97 -create one in your automated build scripts before they will need it. 8.98 -</para> 8.99 - 8.100 -</sect2> 8.101 -</sect1> 8.102 -<sect1> 8.103 -<title>How to stop tracking a file</title> 8.104 - 8.105 -<para>Once you decide that a file no longer belongs in your repository, use 8.106 -the <command role="hg-cmd">hg remove</command> command; this deletes the file, and tells Mercurial 8.107 -to stop tracking it. A removed file is represented in the output of 8.108 -<command role="hg-cmd">hg status</command> with a <quote><literal>R</literal></quote>. 8.109 -<!-- &interaction.daily.files.remove; --> 8.110 -</para> 8.111 - 8.112 -<para>After you <command role="hg-cmd">hg remove</command> a file, Mercurial will no longer track 8.113 -changes to that file, even if you recreate a file with the same name 8.114 -in your working directory. If you do recreate a file with the same 8.115 -name and want Mercurial to track the new file, simply <command role="hg-cmd">hg add</command> it. 8.116 -Mercurial will know that the newly added file is not related to the 8.117 -old file of the same name. 8.118 -</para> 8.119 - 8.120 -<sect2> 8.121 -<title>Removing a file does not affect its history</title> 8.122 - 8.123 -<para>It is important to understand that removing a file has only two 8.124 -effects. 8.125 -</para> 8.126 -<itemizedlist> 8.127 -<listitem><para>It removes the current version of the file from the working 8.128 - directory. 8.129 -</para> 8.130 -</listitem> 8.131 -<listitem><para>It stops Mercurial from tracking changes to the file, from the 8.132 - time of the next commit. 8.133 -</para> 8.134 -</listitem></itemizedlist> 8.135 -<para>Removing a file <emphasis>does not</emphasis> in any way alter the <emphasis>history</emphasis> of 8.136 -the file. 8.137 -</para> 8.138 - 8.139 -<para>If you update the working directory to a changeset in which a file 8.140 -that you have removed was still tracked, it will reappear in the 8.141 -working directory, with the contents it had when you committed that 8.142 -changeset. If you then update the working directory to a later 8.143 -changeset, in which the file had been removed, Mercurial will once 8.144 -again remove the file from the working directory. 8.145 -</para> 8.146 - 8.147 -</sect2> 8.148 -<sect2> 8.149 -<title>Missing files</title> 8.150 - 8.151 -<para>Mercurial considers a file that you have deleted, but not used 8.152 -<command role="hg-cmd">hg remove</command> to delete, to be <emphasis>missing</emphasis>. A missing file is 8.153 -represented with <quote><literal>!</literal></quote> in the output of <command role="hg-cmd">hg status</command>. 8.154 -Mercurial commands will not generally do anything with missing files. 8.155 -<!-- &interaction.daily.files.missing; --> 8.156 -</para> 8.157 - 8.158 -<para>If your repository contains a file that <command role="hg-cmd">hg status</command> reports as 8.159 -missing, and you want the file to stay gone, you can run 8.160 -<command role="hg-cmd">hg remove <option role="hg-opt-remove">--after</option></command> at any time later on, to 8.161 -tell Mercurial that you really did mean to remove the file. 8.162 -<!-- &interaction.daily.files.remove-after; --> 8.163 -</para> 8.164 - 8.165 -<para>On the other hand, if you deleted the missing file by accident, use 8.166 -<command role="hg-cmd">hg revert <emphasis>filename</emphasis></command> to recover the file. It will 8.167 -reappear, in unmodified form. 8.168 -<!-- &interaction.daily.files.recover-missing; --> 8.169 -</para> 8.170 - 8.171 -<para>\subsection{Aside: why tell Mercurial explicitly to 8.172 - remove a file?} 8.173 -</para> 8.174 - 8.175 -<para>You might wonder why Mercurial requires you to explicitly tell it that 8.176 -you are deleting a file. Early during the development of Mercurial, 8.177 -it let you delete a file however you pleased; Mercurial would notice 8.178 -the absence of the file automatically when you next ran a 8.179 -<command role="hg-cmd">hg commit</command>, and stop tracking the file. In practice, this made it 8.180 -too easy to accidentally remove a file without noticing. 8.181 -</para> 8.182 - 8.183 -<para>\subsection{Useful shorthand&emdash;adding and removing files 8.184 - in one step} 8.185 -</para> 8.186 - 8.187 -<para>Mercurial offers a combination command, <command role="hg-cmd">hg addremove</command>, that adds 8.188 -untracked files and marks missing files as removed. 8.189 -<!-- &interaction.daily.files.addremove; --> 8.190 -The <command role="hg-cmd">hg commit</command> command also provides a <option role="hg-opt-commit">-A</option> option 8.191 -that performs this same add-and-remove, immediately followed by a 8.192 -commit. 8.193 -<!-- &interaction.daily.files.commit-addremove; --> 8.194 -</para> 8.195 - 8.196 -</sect2> 8.197 -</sect1> 8.198 -<sect1> 8.199 -<title>Copying files</title> 8.200 - 8.201 -<para>Mercurial provides a <command role="hg-cmd">hg copy</command> command that lets you make a new 8.202 -copy of a file. When you copy a file using this command, Mercurial 8.203 -makes a record of the fact that the new file is a copy of the original 8.204 -file. It treats these copied files specially when you merge your work 8.205 -with someone else's. 8.206 -</para> 8.207 - 8.208 -<sect2> 8.209 -<title>The results of copying during a merge</title> 8.210 - 8.211 -<para>What happens during a merge is that changes <quote>follow</quote> a copy. To 8.212 -best illustrate what this means, let's create an example. We'll start 8.213 -with the usual tiny repository that contains a single file. 8.214 -<!-- &interaction.daily.copy.init; --> 8.215 -We need to do some work in parallel, so that we'll have something to 8.216 -merge. So let's clone our repository. 8.217 -<!-- &interaction.daily.copy.clone; --> 8.218 -Back in our initial repository, let's use the <command role="hg-cmd">hg copy</command> command to 8.219 -make a copy of the first file we created. 8.220 -<!-- &interaction.daily.copy.copy; --> 8.221 -</para> 8.222 - 8.223 -<para>If we look at the output of the <command role="hg-cmd">hg status</command> command afterwards, the 8.224 -copied file looks just like a normal added file. 8.225 -<!-- &interaction.daily.copy.status; --> 8.226 -But if we pass the <option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command>, it 8.227 -prints another line of output: this is the file that our newly-added 8.228 -file was copied <emphasis>from</emphasis>. 8.229 -<!-- &interaction.daily.copy.status-copy; --> 8.230 -</para> 8.231 - 8.232 -<para>Now, back in the repository we cloned, let's make a change in 8.233 -parallel. We'll add a line of content to the original file that we 8.234 -created. 8.235 -<!-- &interaction.daily.copy.other; --> 8.236 -Now we have a modified <filename>file</filename> in this repository. When we 8.237 -pull the changes from the first repository, and merge the two heads, 8.238 -Mercurial will propagate the changes that we made locally to 8.239 -<filename>file</filename> into its copy, <filename>new-file</filename>. 8.240 -<!-- &interaction.daily.copy.merge; --> 8.241 -</para> 8.242 - 8.243 -</sect2> 8.244 -<sect2> 8.245 -<title>Why should changes follow copies?</title> 8.246 -<para>\label{sec:daily:why-copy} 8.247 -</para> 8.248 - 8.249 -<para>This behaviour, of changes to a file propagating out to copies of the 8.250 -file, might seem esoteric, but in most cases it's highly desirable. 8.251 -</para> 8.252 - 8.253 -<para>First of all, remember that this propagation <emphasis>only</emphasis> happens when 8.254 -you merge. So if you <command role="hg-cmd">hg copy</command> a file, and subsequently modify the 8.255 -original file during the normal course of your work, nothing will 8.256 -happen. 8.257 -</para> 8.258 - 8.259 -<para>The second thing to know is that modifications will only propagate 8.260 -across a copy as long as the repository that you're pulling changes 8.261 -from <emphasis>doesn't know</emphasis> about the copy. 8.262 -</para> 8.263 - 8.264 -<para>The reason that Mercurial does this is as follows. Let's say I make 8.265 -an important bug fix in a source file, and commit my changes. 8.266 -Meanwhile, you've decided to <command role="hg-cmd">hg copy</command> the file in your repository, 8.267 -without knowing about the bug or having seen the fix, and you have 8.268 -started hacking on your copy of the file. 8.269 -</para> 8.270 - 8.271 -<para>If you pulled and merged my changes, and Mercurial <emphasis>didn't</emphasis> 8.272 -propagate changes across copies, your source file would now contain 8.273 -the bug, and unless you remembered to propagate the bug fix by hand, 8.274 -the bug would <emphasis>remain</emphasis> in your copy of the file. 8.275 -</para> 8.276 - 8.277 -<para>By automatically propagating the change that fixed the bug from the 8.278 -original file to the copy, Mercurial prevents this class of problem. 8.279 -To my knowledge, Mercurial is the <emphasis>only</emphasis> revision control system 8.280 -that propagates changes across copies like this. 8.281 -</para> 8.282 - 8.283 -<para>Once your change history has a record that the copy and subsequent 8.284 -merge occurred, there's usually no further need to propagate changes 8.285 -from the original file to the copied file, and that's why Mercurial 8.286 -only propagates changes across copies until this point, and no 8.287 -further. 8.288 -</para> 8.289 - 8.290 -</sect2> 8.291 -<sect2> 8.292 -<title>How to make changes <emphasis>not</emphasis> follow a copy</title> 8.293 - 8.294 -<para>If, for some reason, you decide that this business of automatically 8.295 -propagating changes across copies is not for you, simply use your 8.296 -system's normal file copy command (on Unix-like systems, that's 8.297 -<command>cp</command>) to make a copy of a file, then <command role="hg-cmd">hg add</command> the new copy 8.298 -by hand. Before you do so, though, please do reread 8.299 -section <xref linkend="sec:daily:why-copy"/>, and make an informed decision that 8.300 -this behaviour is not appropriate to your specific case. 8.301 -</para> 8.302 - 8.303 -</sect2> 8.304 -<sect2> 8.305 -<title>Behaviour of the <command role="hg-cmd">hg copy</command> command</title> 8.306 - 8.307 -<para>When you use the <command role="hg-cmd">hg copy</command> command, Mercurial makes a copy of each 8.308 -source file as it currently stands in the working directory. This 8.309 -means that if you make some modifications to a file, then <command role="hg-cmd">hg copy</command> 8.310 -it without first having committed those changes, the new copy will 8.311 -also contain the modifications you have made up until that point. (I 8.312 -find this behaviour a little counterintuitive, which is why I mention 8.313 -it here.) 8.314 -</para> 8.315 - 8.316 -<para>The <command role="hg-cmd">hg copy</command> command acts similarly to the Unix <command>cp</command> 8.317 -command (you can use the <command role="hg-cmd">hg cp</command> alias if you prefer). The last 8.318 -argument is the <emphasis>destination</emphasis>, and all prior arguments are 8.319 -<emphasis>sources</emphasis>. If you pass it a single file as the source, and the 8.320 -destination does not exist, it creates a new file with that name. 8.321 -<!-- &interaction.daily.copy.simple; --> 8.322 -If the destination is a directory, Mercurial copies its sources into 8.323 -that directory. 8.324 -<!-- &interaction.daily.copy.dir-dest; --> 8.325 -Copying a directory is recursive, and preserves the directory 8.326 -structure of the source. 8.327 -<!-- &interaction.daily.copy.dir-src; --> 8.328 -If the source and destination are both directories, the source tree is 8.329 -recreated in the destination directory. 8.330 -<!-- &interaction.daily.copy.dir-src-dest; --> 8.331 -</para> 8.332 - 8.333 -<para>As with the <command role="hg-cmd">hg rename</command> command, if you copy a file manually and 8.334 -then want Mercurial to know that you've copied the file, simply use 8.335 -the <option role="hg-opt-copy">--after</option> option to <command role="hg-cmd">hg copy</command>. 8.336 -<!-- &interaction.daily.copy.after; --> 8.337 -</para> 8.338 - 8.339 -</sect2> 8.340 -</sect1> 8.341 -<sect1> 8.342 -<title>Renaming files</title> 8.343 - 8.344 -<para>It's rather more common to need to rename a file than to make a copy 8.345 -of it. The reason I discussed the <command role="hg-cmd">hg copy</command> command before talking 8.346 -about renaming files is that Mercurial treats a rename in essentially 8.347 -the same way as a copy. Therefore, knowing what Mercurial does when 8.348 -you copy a file tells you what to expect when you rename a file. 8.349 -</para> 8.350 - 8.351 -<para>When you use the <command role="hg-cmd">hg rename</command> command, Mercurial makes a copy of 8.352 -each source file, then deletes it and marks the file as removed. 8.353 -<!-- &interaction.daily.rename.rename; --> 8.354 -The <command role="hg-cmd">hg status</command> command shows the newly copied file as added, and 8.355 -the copied-from file as removed. 8.356 -<!-- &interaction.daily.rename.status; --> 8.357 -As with the results of a <command role="hg-cmd">hg copy</command>, we must use the 8.358 -<option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command> to see that the added file 8.359 -is really being tracked by Mercurial as a copy of the original, now 8.360 -removed, file. 8.361 -<!-- &interaction.daily.rename.status-copy; --> 8.362 -</para> 8.363 - 8.364 -<para>As with <command role="hg-cmd">hg remove</command> and <command role="hg-cmd">hg copy</command>, you can tell Mercurial about 8.365 -a rename after the fact using the <option role="hg-opt-rename">--after</option> option. In 8.366 -most other respects, the behaviour of the <command role="hg-cmd">hg rename</command> command, and 8.367 -the options it accepts, are similar to the <command role="hg-cmd">hg copy</command> command. 8.368 -</para> 8.369 - 8.370 -<sect2> 8.371 -<title>Renaming files and merging changes</title> 8.372 - 8.373 -<para>Since Mercurial's rename is implemented as copy-and-remove, the same 8.374 -propagation of changes happens when you merge after a rename as after 8.375 -a copy. 8.376 -</para> 8.377 - 8.378 -<para>If I modify a file, and you rename it to a new name, and then we merge 8.379 -our respective changes, my modifications to the file under its 8.380 -original name will be propagated into the file under its new name. 8.381 -(This is something you might expect to <quote>simply work,</quote> but not all 8.382 -revision control systems actually do this.) 8.383 -</para> 8.384 - 8.385 -<para>Whereas having changes follow a copy is a feature where you can 8.386 -perhaps nod and say <quote>yes, that might be useful,</quote> it should be clear 8.387 -that having them follow a rename is definitely important. Without 8.388 -this facility, it would simply be too easy for changes to become 8.389 -orphaned when files are renamed. 8.390 -</para> 8.391 - 8.392 -</sect2> 8.393 -<sect2> 8.394 -<title>Divergent renames and merging</title> 8.395 - 8.396 -<para>The case of diverging names occurs when two developers start with a 8.397 -file&emdash;let's call it <filename>foo</filename>&emdash;in their respective 8.398 -repositories. 8.399 -</para> 8.400 - 8.401 -<para><!-- &interaction.rename.divergent.clone; --> 8.402 -Anne renames the file to <filename>bar</filename>. 8.403 -<!-- &interaction.rename.divergent.rename.anne; --> 8.404 -Meanwhile, Bob renames it to <filename>quux</filename>. 8.405 -<!-- &interaction.rename.divergent.rename.bob; --> 8.406 -</para> 8.407 - 8.408 -<para>I like to think of this as a conflict because each developer has 8.409 -expressed different intentions about what the file ought to be named. 8.410 -</para> 8.411 - 8.412 -<para>What do you think should happen when they merge their work? 8.413 -Mercurial's actual behaviour is that it always preserves <emphasis>both</emphasis> 8.414 -names when it merges changesets that contain divergent renames. 8.415 -<!-- &interaction.rename.divergent.merge; --> 8.416 -</para> 8.417 - 8.418 -<para>Notice that Mercurial does warn about the divergent renames, but it 8.419 -leaves it up to you to do something about the divergence after the merge. 8.420 -</para> 8.421 - 8.422 -</sect2> 8.423 -<sect2> 8.424 -<title>Convergent renames and merging</title> 8.425 - 8.426 -<para>Another kind of rename conflict occurs when two people choose to 8.427 -rename different <emphasis>source</emphasis> files to the same <emphasis>destination</emphasis>. 8.428 -In this case, Mercurial runs its normal merge machinery, and lets you 8.429 -guide it to a suitable resolution. 8.430 -</para> 8.431 - 8.432 -</sect2> 8.433 -<sect2> 8.434 -<title>Other name-related corner cases</title> 8.435 - 8.436 -<para>Mercurial has a longstanding bug in which it fails to handle a merge 8.437 -where one side has a file with a given name, while another has a 8.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>. 8.439 -<!-- &interaction.issue29.go; --> 8.440 -</para> 8.441 - 8.442 -</sect2> 8.443 -</sect1> 8.444 -<sect1> 8.445 -<title>Recovering from mistakes</title> 8.446 - 8.447 -<para>Mercurial has some useful commands that will help you to recover from 8.448 -some common mistakes. 8.449 -</para> 8.450 - 8.451 -<para>The <command role="hg-cmd">hg revert</command> command lets you undo changes that you have made to 8.452 -your working directory. For example, if you <command role="hg-cmd">hg add</command> a file by 8.453 -accident, just run <command role="hg-cmd">hg revert</command> with the name of the file you added, 8.454 -and while the file won't be touched in any way, it won't be tracked 8.455 -for adding by Mercurial any longer, either. You can also use 8.456 -<command role="hg-cmd">hg revert</command> to get rid of erroneous changes to a file. 8.457 -</para> 8.458 - 8.459 -<para>It's useful to remember that the <command role="hg-cmd">hg revert</command> command is useful for 8.460 -changes that you have not yet committed. Once you've committed a 8.461 -change, if you decide it was a mistake, you can still do something 8.462 -about it, though your options may be more limited. 8.463 -</para> 8.464 - 8.465 -<para>For more information about the <command role="hg-cmd">hg revert</command> command, and details 8.466 -about how to deal with changes you have already committed, see 8.467 -chapter <xref linkend="chap:undo"/>. 8.468 -</para> 8.469 - 8.470 -</sect1> 8.471 +<chapter id="chap:daily"> 8.472 + <?dbhtml filename="mercurial-in-daily-use.html"?> 8.473 + <title>Mercurial pour une utilisation de tous les jours</title> 8.474 + 8.475 + <sect1> 8.476 + <title>Informer Mercurial des fichier à suivre</title> 8.477 + 8.478 + <para id="x_1a3">Mercurial ne suit pas les fichiers de votre dépôt tant 8.479 + que vous ne lui avez pas dit de les gérer. La commande <command 8.480 + role="hg-cmd">hg status</command> vous dira quels fichiers sont 8.481 + inconnus de Mercurial. Il utilise un 8.482 + <quote><literal>?</literal></quote> pour montrer ces fichiers.</para> 8.483 + 8.484 + <para id="x_1a4">Pour informer Mercurial de suivre un fichier, utilisez 8.485 + la commande <command role="hg-cmd">hg add</command>. Une fois que vous 8.486 + avez ajouté un fichier, la ligne correspondante à ce fichier dans la 8.487 + sortie de <command role="hg-cmd">hg status</command> change de 8.488 + <quote><literal>?</literal></quote> à 8.489 + <quote><literal>A</literal></quote>.</para> 8.490 + 8.491 + &interaction.daily.files.add; 8.492 + 8.493 + <para id="x_1a5">Après avoir exécuté un <command role="hg-cmd">hg 8.494 + commit</command>, les fichiers que vous avez ajoutés avant le commit 8.495 + ne seront plus listés dans la sortie de <command role="hg-cmd">hg 8.496 + status</command>. La raison de ceci est que, par défaut, <command 8.497 + role="hg-cmd">hg status</command> ne vous montre que les fichiers 8.498 + <quote>intéressants</quote> &emdash;ceux que vous avez (par exemple) 8.499 + modifiés, supprimés ou renommés. Si vous aviez un dépôt qui contient un 8.500 + millier de fichiers, vous ne voudriez certainement que rarement entendre 8.501 + parler des fichiers que Mercurial suit, mais qui n'ont pas changés. 8.502 + (Vous pouvez quand même avoir cette information, nous y reviendrons 8.503 + plus tard.)</para> 8.504 + 8.505 + <para id="x_1a6">Une fois que vous ajoutez un fichier, Mercurial ne fait 8.506 + rien du tout avec celui-ci immédiatement. Au lieu de ça, il va prendre 8.507 + un "snapshot" de l'état du fichier la prochaine fois que vous 8.508 + exécuterez un commit. Il continuera ensuite à suivre les changements 8.509 + que vous avez fait au fichier chaque fois que vous committerez, et ce, 8.510 + jusqu'à ce que vous supprimiez le fichier.</para> 8.511 + 8.512 + <sect2> 8.513 + <title>Nommage des fichiers explicite versus implicite</title> 8.514 + 8.515 + <para id="x_1a7">Un comportement utile que Mercurial possède est que si 8.516 + vous passez le nom d'un répertoire à une commande, toute commande 8.517 + Mercurial la traitera comme : <quote>Je veux opérer sur chaque fichier 8.518 + dans ce répertoire et ses sous-répertoires</quote>.</para> 8.519 + 8.520 + &interaction.daily.files.add-dir; 8.521 + 8.522 + <para id="x_1a8">Remarquez que dans cet exemple, Mercurial affiche le 8.523 + nom des fichiers qu'il a ajouté, alors qu'il ne l'a pas fait lorsque 8.524 + nous avons ajouté le fichier nommé <filename>myfile.txt</filename> 8.525 + dans l'exemple précédent.</para> 8.526 + 8.527 + <para id="x_1a9">Ce qu'il se passe est que dans le premier cas, nous 8.528 + avons nommé explicitement le fichier à ajouter sur la ligne de 8.529 + commande. Ce que Mercurial suppose dans ce cas est que nous savons ce 8.530 + que nous faisons, il n'affiche donc rien en sortie.</para> 8.531 + 8.532 + <para id="x_1aa">Cependant, lorsque nous avons 8.533 + <emphasis>implicitement</emphasis> donné les fichiers à l'aide du nom 8.534 + d'un répertoire, Mercurial prend l'initiative d'afficher le nom de 8.535 + chaque fichier avec lequel il fait quelque chose. Ceci clarifie ce 8.536 + qu'il se passe et réduit la probabilité d'une mauvaise surprise 8.537 + restée silencieuse. Ce comportement est commun à la plupart des 8.538 + commandes Mercurial.</para> 8.539 + </sect2> 8.540 + <sect2> 8.541 + <title>Mercurial suit les fichiers, pas les répertoires</title> 8.542 + 8.543 + <para id="x_1ab">Mercurial ne suit pas les informations sur les 8.544 + répertoires. En contrepartie, il suit le chemin vers un fichier. Avant 8.545 + de créer un fichier, il crée au préalable les répertoires manquants 8.546 + dans le chemin. Après avoir supprimé un fichier, il supprime chaque 8.547 + répertoire vide qui apparaît dans le chemin du fichier. Ceci apparaît 8.548 + comme une distinction triviale, cependant, cela a une conséquence 8.549 + pratique mineure : il n'est pas possible de représenter un répertoire 8.550 + totalement vide dans Mercurial.</para> 8.551 + 8.552 + <para id="x_1ac">Les répertoires vides sont rarement utiles. Il existe 8.553 + cependant des solutions alternatives et non intrusives que vous 8.554 + pouvez utiliser pour obtenir l'effet approprié. Les développeurs de 8.555 + Mercurial ont ainsi pensé que la complexité requise pour gérer les 8.556 + répertoires n'était pas aussi importante que le bénéfice que cette 8.557 + fonctionnalité apporterait.</para> 8.558 + 8.559 + <para id="x_1ad">Si vous avez besoin d'un répertoire vide dans votre 8.560 + dépôt, il existe quelques façons d'y arriver. L'une d'elles est de 8.561 + créer un répertoire et ensuite, de faire un <command role="hg-cmd">hg 8.562 + add</command> sur un fichier <quote>caché</quote> dans ce 8.563 + répertoire. Sur les systèmes de type Unix, tout fichier dont le nom 8.564 + commence avec un point (<quote><literal>.</literal></quote>) est 8.565 + considéré comme caché par la plupart des commandes et outils 8.566 + graphiques. Cette approche est illustrée ci-après.</para> 8.567 + 8.568 + &interaction.daily.files.hidden; 8.569 + 8.570 + <para id="x_1ae">Une autre façon de s'attaquer au besoin d'un 8.571 + répertoire vide est de simplement d'en créer un dans vos scripts 8.572 + de construction avant qu'ils n'en aient le besoin.</para> 8.573 + </sect2> 8.574 + </sect1> 8.575 + 8.576 + <sect1> 8.577 + <title>Comment arrêter de suivre un fichier</title> 8.578 + 8.579 + <para id="x_1af">Une fois que vous décidez qu'un fichier n'appartient 8.580 + plus à votre dépôt, utilisez la commande <command role="hg-cmd">hg 8.581 + remove</command>. Ceci supprime le fichier et informe Mercurial 8.582 + d'arrêter de le suivre (ce qui prendra effet lors du prochain commit). 8.583 + Un fichier supprimé est représenté dans la sortie de la commande 8.584 + <command role="hg-cmd">hg status</command> par un 8.585 + <quote><literal>R</literal></quote>.</para> 8.586 + 8.587 + &interaction.daily.files.remove; 8.588 + 8.589 + <para id="x_1b0">Après avoir fait un <command role="hg-cmd">hg 8.590 + remove</command> sur un fichier, Mercurial ne suivra plus aucun 8.591 + changement sur ce fichier, même si vous recréez un fichier avec le même 8.592 + nom dans votre répertoire de travail. Si vous recréez un fichier avec le 8.593 + même nom et que vous désirez que Mercurial suive ce dernier, faite 8.594 + simplement un <command role="hg-cmd">hg add</command> sur celui-ci. 8.595 + Mercurial saura alors que le nouveau fichier ne fait pas référence à 8.596 + l'ancien fichier qui portait le même nom.</para> 8.597 + 8.598 + <sect2> 8.599 + <title>Supprimer un fichier n'affecte pas son historique</title> 8.600 + 8.601 + <para id="x_1b1">Il est important de comprendre que supprimer un fichier 8.602 + n'a que deux effets.</para> 8.603 + 8.604 + <itemizedlist> 8.605 + <listitem><para id="x_1b2">Il supprime la version actuelle de ce 8.606 + fichier du répertoire de travail.</para> 8.607 + </listitem> 8.608 + <listitem><para id="x_1b3">Il arrête, à partir du prochain commit, le 8.609 + suivi de Mercurial sur les changements qui ont lieu sur ce 8.610 + fichier.</para> 8.611 + </listitem></itemizedlist> 8.612 + 8.613 + <para id="x_1b4">Supprimer un fichier <emphasis>n'</emphasis>affecte en 8.614 + <emphasis>aucun</emphasis> cas l'<emphasis>historique</emphasis> du 8.615 + fichier.</para> 8.616 + 8.617 + <para id="x_1b5">Si vous mettez à jour le répertoire de travail à un 8.618 + changeset qui a été committé alors que le fichier que vous venez de 8.619 + supprimer était encore suivi, ce fichier réapparaîtra dans le 8.620 + répertoire de travail, avec le contenu qu'il avait lorsque vous aviez 8.621 + committé ce changeset. Si vous mettez à jour (update) le répertoire de 8.622 + travail à un changeset ultérieur dans lequel le fichier a été 8.623 + supprimé, Mercurial supprimera une nouvelle fois le fichier du 8.624 + répertoire de travail.</para> 8.625 + </sect2> 8.626 + 8.627 + <sect2> 8.628 + <title>Fichiers manquants</title> 8.629 + 8.630 + <para id="x_1b6">Mercurial considère qu'un fichier que vous avez 8.631 + supprimé sans utiliser<command role="hg-cmd">hg remove</command> 8.632 + comme étant <emphasis>manquant</emphasis>. Un fichier manquant est 8.633 + représenté avec un <quote><literal>!</literal></quote> en sortie de 8.634 + <command role="hg-cmd">hg status</command>. 8.635 + Les commandes Mercurial ne feront rien avec les fichiers 8.636 + manquants.</para> 8.637 + 8.638 + &interaction.daily.files.missing; 8.639 + 8.640 + <para id="x_1b7">Si votre dépôt contient un fichier que <command 8.641 + role="hg-cmd">hg status</command> reporte comme manquant, et que 8.642 + vous voulez que ce fichier reste supprimé, vous pouvez exécuter 8.643 + <command role="hg-cmd">hg remove <option 8.644 + role="hg-opt-remove">--after</option></command> à tout moment 8.645 + pour dire à Mercurial que vous aviez bien voulu supprimer ce 8.646 + fichier.</para> 8.647 + 8.648 + &interaction.daily.files.remove-after; 8.649 + 8.650 + <para id="x_1b8">D'un autre coté, si vous avez supprimé le fichier 8.651 + manquant par accident, donnez à la commande <command role="hg-cmd">hg 8.652 + revert</command> le nom du fichier à retrouver. Il réapparaitra dans 8.653 + sa forme non modifiée.</para> 8.654 + 8.655 + &interaction.daily.files.recover-missing; 8.656 + 8.657 + </sect2> 8.658 + 8.659 + <sect2> 8.660 + <title>Entre nous : Pourquoi dire explicitement à Mercurial de supprimer un 8.661 + fichier ?</title> 8.662 + 8.663 + <para id="x_1b9">Vous pourriez vous demander pourquoi il est nécessaire 8.664 + de dire explicitement à Mercurial que vous souhaitez supprimer un 8.665 + fichier. Au début du développement de Mercurial, celui ci vous 8.666 + laissait pourtant supprimer un fichier sans soucis ; Mercurial vous 8.667 + aurait automatiquement informé de l'absence du fichier lorsque vous 8.668 + auriez lancé un <command role="hg-cmd">hg commit</command> et arrêté 8.669 + de le suivre. En pratique, ceci a montré qu'il était trop facile de 8.670 + supprimer accidentellement un fichier sans le remarquer.</para> 8.671 + </sect2> 8.672 + 8.673 + <sect2> 8.674 + <title>Raccourci utile&emdash;ajouter et supprimer des fichiers en une 8.675 + seule étape.</title> 8.676 + 8.677 + <para id="x_1ba">Mercurial offre une commande combinée, <command 8.678 + role="hg-cmd">hg addremove</command>, qui ajoute les fichiers non 8.679 + suivis et marque les fichiers manquants comme supprimés.</para> 8.680 + 8.681 + &interaction.daily.files.addremove; 8.682 + 8.683 + <para id="x_1bb">La commande <command role="hg-cmd">hg commit</command> 8.684 + fournit aussi une option <option role="hg-opt-commit">-A</option> qui 8.685 + exécute le même ajouter-et-supprimer, immédiatement suivi d'un 8.686 + commit.</para> 8.687 + 8.688 + &interaction.daily.files.commit-addremove; 8.689 + 8.690 + </sect2> 8.691 + </sect1> 8.692 + 8.693 + <sect1 id="chap:daily.copy"> 8.694 + <title>Copier des fichiers</title> 8.695 + 8.696 + <para id="x_1bc">Mercurial fournit une commande <command role="hg-cmd">hg 8.697 + copy</command> qui vous permet de faire une nouvelle copie d'un 8.698 + fichier. Lorsque vous copiez un fichier en utilisant cette commande, 8.699 + Mercurial crée un enregistrement du fait que ce nouveau fichier est une 8.700 + copie du fichier originel. Il traite ces fichiers copiés spécialement 8.701 + lorsque vous fusionnez (merge) votre travail avec quelqu'un 8.702 + d'autre.</para> 8.703 + 8.704 + <sect2> 8.705 + <title>Les résultats d'une copie durant une fusion (merge)</title> 8.706 + 8.707 + <para id="x_1bd">Ce qu'il se passe durant une fusion (merge) est que 8.708 + les changements <quote>suivent</quote> une copie. Pour illustrer ce 8.709 + que cela veut dire de la meilleure façon, créons un exemple. Nous 8.710 + allons commencer avec le mini dépôt usuel qui contient un simple 8.711 + fichier.</para> 8.712 + 8.713 + &interaction.daily.copy.init; 8.714 + 8.715 + <para id="x_1be">Nous devons faire du travail en parallèle, ainsi, 8.716 + nous aurons quelque chose à fusionner (merge). Donc clonons notre 8.717 + dépôt.</para> 8.718 + 8.719 + &interaction.daily.copy.clone; 8.720 + 8.721 + <para id="x_1bf">De retour dans notre dépôt initial, utilisons la 8.722 + commande <command role="hg-cmd">hg copy</command> pour faire une 8.723 + copie du premier fichier que nous avons créé.</para> 8.724 + 8.725 + &interaction.daily.copy.copy; 8.726 + 8.727 + <para id="x_1c0">Si nous regardons ensuite à la sortie de la commande 8.728 + <command role="hg-cmd">hg status</command>, les fichiers copiés 8.729 + ont l'air de fichiers normalement ajoutés.</para> 8.730 + 8.731 + &interaction.daily.copy.status; 8.732 + 8.733 + <para id="x_1c1">Mais si nous passons l'option <option 8.734 + role="hg-opt-status">-C</option> à <command role="hg-cmd">hg 8.735 + status</command>, il affiche une autre ligne de sortie : il s'agit 8.736 + du fichier <emphasis>source</emphasis> pour notre copie.</para> 8.737 + 8.738 + &interaction.daily.copy.status-copy; 8.739 + 8.740 + <para id="x_1c2">Maintenant, de retour dans le dépôt que nous avons 8.741 + cloné, créons un changement en parallèle. Nous allons ajouter une 8.742 + ligne de contenu au fichier original qui a été créé.</para> 8.743 + 8.744 + &interaction.daily.copy.other; 8.745 + 8.746 + <para id="x_1c3">Nous avons alors un fichier <filename>file</filename> 8.747 + modifié dans ce dépôt. Lorsque nous récupérons (pull) les changements 8.748 + depuis le premier répertoire et fusionnons (merge) les deux "heads", 8.749 + Mercurial propagera les changements que nous avons faits localement 8.750 + au fichier <filename>file</filename> dans sa copie 8.751 + <filename>new-file</filename>.</para> 8.752 + 8.753 + &interaction.daily.copy.merge; 8.754 + 8.755 + </sect2> 8.756 + <sect2 id="sec:daily:why-copy"> 8.757 + <title>Pourquoi est-ce que les changements devraient suivre les copies 8.758 + ?</title> 8.759 + 8.760 + <para id="x_1c4">Ce comportement&emdash;des changements d'un fichiers 8.761 + qui se propagent aux copies de ce fichier&emdash;peut sembler 8.762 + ésotérique, mais, dans la plupart des cas, c'est hautement 8.763 + désirable.</para> 8.764 + 8.765 + <para id="x_1c5">Pour commencer, souvenez vous que cette propagation 8.766 + a lieue <emphasis>seulement</emphasis> lors des fusions (merge). 8.767 + Donc, si vous faites un <command role="hg-cmd">hg copy</command> sur 8.768 + un fichier, et par la suite modifiez le fichier original durant le 8.769 + cours normal de votre travail, rien n'a lieu.</para> 8.770 + 8.771 + <para id="x_1c6">La deuxième chose à savoir c'est que les modifications 8.772 + ne se propageront à travers une copie que si le changeset à partir 8.773 + duquel vous faites une fusion (merge) <emphasis>n'a pas encore 8.774 + vu</emphasis> la copie.</para> 8.775 + 8.776 + <para id="x_1c7">La raison pour laquelle Mercurial fait ainsi est une 8.777 + règle. Imaginons que je corrige un important bug dans un fichier source 8.778 + et que je commit mes changements. Pendant ce temps, vous avez décidé de 8.779 + faire un <command role="hg-cmd">hg copy</command> du fichier dans 8.780 + votre dépôt, sans rien savoir au sujet du bug ou à propos de la 8.781 + correction. Vous avez alors commencé à "hacker" sur votre copie du 8.782 + fichier.</para> 8.783 + 8.784 + <para id="x_1c8">Si vous aviez récupéré (pull) et fusionné (merge) mes 8.785 + changements, et que Mercurial <emphasis>n'avait pas</emphasis> 8.786 + propagé les changements à travers les copies, votre nouveau fichier 8.787 + source contiendrait maintenant le bug, et à moins que vous ne sachiez 8.788 + qu'il faille propager la correction du bug à la main, le bug aurait 8.789 + <emphasis>subsisté</emphasis> dans votre copie du fichier.</para> 8.790 + 8.791 + <para id="x_1c9">En propageant automatiquement les changements qui 8.792 + fixent les bugs à partir du fichier original vers les copies, 8.793 + Mercurial prévient ce type de problèmes. A ma connaissance, Mercurial 8.794 + est le <emphasis>seul</emphasis> système de gestion de révisions qui 8.795 + propage les changements à travers les copies comme ceci.</para> 8.796 + 8.797 + <para id="x_1ca">Une fois que votre historique des changements a un 8.798 + enregistrement concernant une copie et qu'une fusion postérieure a 8.799 + eu lieue, il n'y a d'habitude pas d'autre besoin de propager les 8.800 + changements du fichier originel vers le fichier copié. C'est pourquoi 8.801 + Mercurial ne propage les changements à travers les copies qu'à la 8.802 + première fusion, et pas d'avantage.</para> 8.803 + </sect2> 8.804 + 8.805 + <sect2> 8.806 + <title>Comment faire des changements qui <emphasis>ne</emphasis> 8.807 + suivent <emphasis>pas</emphasis> une copie</title> 8.808 + 8.809 + <para id="x_1cb">Si pour une raison ou une autre, vous décidez que 8.810 + cette fonctionnalité de propager automatiquement les changements à 8.811 + travers les copies n'est pas pour vous, utilisez simplement la 8.812 + commande normale de copie de votre système (sur les systèmes de type 8.813 + Unix, il s'agit de <command>cp</command>) pour faire une copie d'un 8.814 + fichier. Utilisez ensuite <command role="hg-cmd">hg add</command> 8.815 + pour ajouter les nouveaux fichiers à la main. Cependant, avant d'en 8.816 + faire ainsi, relisez <xref linkend="sec:daily:why-copy"/>, et faites 8.817 + un choix en connaissance de cause comme quoi cette fonctionnalité 8.818 + n'est pas appropriée à votre cas spécifique.</para> 8.819 + 8.820 + </sect2> 8.821 + <sect2> 8.822 + <title>Comportement de la commande <command role="hg-cmd">hg copy</command></title> 8.823 + 8.824 + <para id="x_1cc">Lorsque vous utilisez la commande <command 8.825 + role="hg-cmd">hg copy</command>, Mercurial crée une copie de chaque 8.826 + fichier source tel qu'il est actuellement dans le répertoire de 8.827 + travail. Cela signifie que si vous effectuez des modifications sur un 8.828 + fichier, puis faites un <command role="hg-cmd">hg copy</command> sur 8.829 + celui-ci sans avoir au préalable committé ces changements, la nouvelle 8.830 + copie contiendra aussi les modifications que vous avez fait jusqu'à 8.831 + ce point. (Je trouve ce comportement quelque peu contre intuitif, 8.832 + c'est pourquoi j'en fais mention ici.)</para> 8.833 + <!-- Vérifier que je n'ai pas fait de contre sens en relisant la 8.834 + version anglaise, ce que je comprend ici me paraît un peu bizarre --> 8.835 + 8.836 + <para id="x_1cd">La commande <command role="hg-cmd">hg copy</command> 8.837 + agit comme la commande Unix <command>cp</command> (vous pouvez 8.838 + utilisez l'alias <command role="hg-cmd">hg cp</command> si vous 8.839 + préférez). Nous devons lui donner deux ou plus arguments où le 8.840 + dernier est considéré comme la <emphasis>destination</emphasis>, et 8.841 + les autres comme les <emphasis>sources</emphasis>.</para> 8.842 + 8.843 + <para id="x_685">Si vous passez à <command role="hg-cmd">hg 8.844 + copy</command> un seul fichier source, et que la destination 8.845 + n'existe pas, ceci créera un nouveau fichier avec ce nom.</para> 8.846 + 8.847 + &interaction.daily.copy.simple; 8.848 + 8.849 + <para id="x_1ce">Si la destination est un répertoire, Mercurial copie 8.850 + les sources dans ce répertoire.</para> 8.851 + 8.852 + &interaction.daily.copy.dir-dest; 8.853 + 8.854 + <para id="x_1cf">La copie de répertoire est récursive et préserve la 8.855 + structure du répertoire source.</para> 8.856 + 8.857 + &interaction.daily.copy.dir-src; 8.858 + 8.859 + <para id="x_1d0">Si la source et la destination sont tous deux des 8.860 + répertoires, l'arborescence de la source est recréée dans le 8.861 + répertoire destination.</para> 8.862 + 8.863 + &interaction.daily.copy.dir-src-dest; 8.864 + 8.865 + <para id="x_1d1">Comme avec la commande <command role="hg-cmd">hg 8.866 + remove</command>, si vous copiez un fichier manuellement et voulez 8.867 + que Mercurial sache qu'il s'agit d'une copie, utilisez simplement 8.868 + l'option <option role="hg-opt-copy">--after</option> avec <command 8.869 + role="hg-cmd">hg copy</command>.</para> 8.870 + 8.871 + &interaction.daily.copy.after; 8.872 + </sect2> 8.873 + </sect1> 8.874 + 8.875 + <sect1> 8.876 + <title>Renommer les fichiers</title> 8.877 + 8.878 + <para id="x_1d2">Il est plus commun d'avoir besoin de renommer un 8.879 + fichier que d'en faire une copie. La raison pour laquelle j'ai discuté 8.880 + de la commande <command role="hg-cmd">hg copy</command> avant de parler 8.881 + de renommage des fichiers est que Mercurial traite les renommages 8.882 + essentiellement comme une copie. Ainsi, savoir comment Mercurial traite 8.883 + les copies de fichiers vous informe sur ce que vous êtes en droit 8.884 + d'attendre lorsque vous renommez un fichier.</para> 8.885 + 8.886 + <para id="x_1d3">Lorsque vous utilisez la commande <command 8.887 + role="hg-cmd">hg rename</command>, Mercurial crée une copie de tous 8.888 + les fichiers sources, les supprime et marque ces fichiers comme étant 8.889 + supprimés.</para> 8.890 + 8.891 + &interaction.daily.rename.rename; 8.892 + 8.893 + <para id="x_1d4">La commande <command role="hg-cmd">hg status</command> 8.894 + montre les nouveaux fichiers comme ajoutés et les fichiers originaux 8.895 + comme supprimés.</para> 8.896 + 8.897 + &interaction.daily.rename.status; 8.898 + 8.899 + <para id="x_1d5">A cause du <command role="hg-cmd">hg copy</command>, 8.900 + nous devons utiliser l'option <option role="hg-opt-status">-C</option> 8.901 + pour la commande <command role="hg-cmd">hg status</command> afin 8.902 + d'observer que le fichier ajouté est bien suivi par Mercurial comme 8.903 + étant une copie de l'original maintenant supprimé.</para> 8.904 + 8.905 + &interaction.daily.rename.status-copy; 8.906 + 8.907 + <para id="x_1d6">Comme avec <command role="hg-cmd">hg remove</command> et 8.908 + <command role="hg-cmd">hg copy</command>, vous pouvez informer 8.909 + Mercurial au sujet d'un renommage après coup en utilisant l'option 8.910 + <option role="hg-opt-rename">--after</option>. Dans le plus grand 8.911 + respect, le comportement de la commande <command role="hg-cmd">hg 8.912 + rename</command>, et les options qu'il accepte sont similaires à la 8.913 + commande <command role="hg-cmd">hg copy</command>.</para> 8.914 + 8.915 + <para id="x_686">Si vous êtes familier avec la ligne de commande Unix, 8.916 + vous serez heureux d'apprendre que la commande <command 8.917 + role="hg-cmd">hg rename</command> peut être invoquée par <command 8.918 + role="hg-cmd">hg mv</command>.</para> 8.919 + 8.920 + <sect2> 8.921 + <title>Renommer les fichiers et fusionner (merge) les changements</title> 8.922 + 8.923 + <para id="x_1d7">Puise que le "rename" de Mercurial est implanté comme un 8.924 + "copy-and-remove", la même propagation des changements a lieue après 8.925 + un "rename" qu'après un "copy" lorsque vous fusionnez (merge).</para> 8.926 + 8.927 + <para id="x_1d8">Si je modifie un fichier et que vous le renommez, si 8.928 + ensuite nous fusionnons nos changements respectifs, mes modifications 8.929 + sur le fichier sous son nom originel seront propagés vers le même 8.930 + fichier sous son nouveau nom. (C'est quelque chose que vous pourriez 8.931 + espérer voir <quote>fonctionner simplement</quote>, mais tous les 8.932 + systèmes de gestion de version ne le font pas.)</para> 8.933 + 8.934 + <para id="x_1d9">Tandis qu'avoir des changements qui suivent une copie 8.935 + est une fonctionnalité où vous hocheriez sûrement la tête en disant 8.936 + <quote>oui, cela pourrait être utile</quote>, il est clair que les 8.937 + voir suivre un renommage est définitivement important. Sans cette 8.938 + aptitude, il serait vraiment trop facile d'avoir des changements 8.939 + qui deviennent orphelins lorsque des fichiers sont renommés.</para> 8.940 + </sect2> 8.941 + 8.942 + <sect2> 8.943 + <title>Renommages divergeants et fusion (merge)</title> 8.944 + 8.945 + <para id="x_1da">Le cas de noms divergeants a lieu lorsque deux 8.946 + développeurs commencent avec un fichier&emdash;appelons le 8.947 + <filename>foo</filename>&emdash;dans leurs dépôts respectifs.</para> 8.948 + 8.949 + &interaction.rename.divergent.clone; 8.950 + 8.951 + <para id="x_1db">Anne renomme le fichier en 8.952 + <filename>bar</filename>.</para> 8.953 + 8.954 + &interaction.rename.divergent.rename.anne; 8.955 + 8.956 + <para id="x_1dc">Pendant ce temps, Bob le renomme en 8.957 + <filename>quux</filename>. (Souvenez vous que <command 8.958 + role="hg-cmd">hg mv</command> est un alias pour <command 8.959 + role="hg-cmd">hg rename</command>.)</para> 8.960 + 8.961 + &interaction.rename.divergent.rename.bob; 8.962 + 8.963 + <para id="x_1dd">J'aime à penser qu'il s'agit d'un conflit puisque 8.964 + chaque développeur a exprimé différentes intentions au sujet de ce 8.965 + que le nom de ce fichier aurait du être.</para> 8.966 + 8.967 + <para id="x_1de">Que pensez vous qu'il devrait se produire lorsqu'ils 8.968 + fusionnent (merge) leurs travaux ? Le comportement actuel de 8.969 + Mercurial est qu'il préserve toujours les <emphasis>deux</emphasis> 8.970 + noms lorsqu'il fusionne (merge) des changesets qui contiennent des 8.971 + renommages divergeants.</para> 8.972 + 8.973 + &interaction.rename.divergent.merge; 8.974 + 8.975 + <para id="x_1df">Remarquez que bien que Mercurial vous avertisse au 8.976 + sujet de la divergeance des renommages, il vous laisse faire quelque 8.977 + chose au sujet de la divergeance après la fusion (merge).</para> 8.978 + </sect2> 8.979 + 8.980 + <sect2> 8.981 + <title>Renommages et fusion convergeants</title> 8.982 + 8.983 + <para id="x_1e0">Un autre type de conflit de renommage intervient 8.984 + lorsque deux personne choisissent de renommer différents fichiers 8.985 + <emphasis>source</emphasis> vers la même 8.986 + <emphasis>destination</emphasis>. Dans ce cas, Mercurial exécute la 8.987 + machinerie normale de fusion (merge) et vous guide vers une 8.988 + solution convenable.</para> 8.989 + </sect2> 8.990 + 8.991 + <sect2> 8.992 + <title>Autres cas anguleux relatifs aux noms</title> 8.993 + 8.994 + <para id="x_1e1">Mercurial possède un bug de longue date dans lequel il 8.995 + échoue à traiter une fusion (merge) où un coté a un fichier avec un 8.996 + nom donné, alors que l'autre coté possède un répertoire avec le même nom. 8.997 + Ceci est documenté dans l'<ulink role="hg-bug" 8.998 + url="http://www.selenic.com/mercurial/bts/issue29">issue 8.999 + 29</ulink>.</para> 8.1000 + 8.1001 + &interaction.issue29.go; 8.1002 + 8.1003 + </sect2> 8.1004 + </sect1> 8.1005 + 8.1006 + <sect1> 8.1007 + <title>Récupération d'erreurs</title> 8.1008 + 8.1009 + <para id="x_1e2">Mercurial possède certaines commandes utiles qui vont 8.1010 + vous aider à récupérer de certaines erreurs communes.</para> 8.1011 + 8.1012 + <para id="x_1e3">La commande <command role="hg-cmd">hg revert</command> 8.1013 + vous permet d'annuler les changements que vous avez faits dans votre 8.1014 + répertoire de travail. Par exemple, si vous faites un <command 8.1015 + role="hg-cmd">hg add</command> sur un fichier par accident, exécutez 8.1016 + juste <command role="hg-cmd">hg revert</command> avec le nom du fichier 8.1017 + que vous avez ajouté et tandis que le fichier ne sera touché d'une 8.1018 + quelconque manière, il ne sera plus suivi comme ajouté par Mercurial. 8.1019 + Vous pouvez aussi utiliser la commande <command role="hg-cmd">hg 8.1020 + revert</command> pour vous débarrasser de modifications erronés 8.1021 + apportées à un fichier.</para> 8.1022 + 8.1023 + <para id="x_1e4">Il est utile de se souvenir que la commande <command 8.1024 + role="hg-cmd">hg revert</command> est utile pour les modifications 8.1025 + qui n'ont pas encore été committées. Une fois que vous avez committé un 8.1026 + changement, si vous décidez qu'il s'agissait d'une erreur, vous pouvez 8.1027 + toujours faire quelque chose à ce sujet, bien que vos options soient 8.1028 + un peu plus limitées.</para> 8.1029 + 8.1030 + <para id="x_1e5">Pour plus d'informations au sujet de la commande 8.1031 + <command role="hg-cmd">hg revert</command>, et des détails sur comment 8.1032 + traiter les modifications que vous avez déjà committées, référez vous à 8.1033 + <xref linkend="chap:undo"/>.</para> 8.1034 + </sect1> 8.1035 + 8.1036 + <sect1> 8.1037 + <title>Traiter avec les fusions (merge) malicieuses</title> 8.1038 + 8.1039 + <para id="x_687">Dans des projets compliqués ou conséquents, il n'est pas 8.1040 + rare qu'une fusion (merge) de deux changesets finisse par une migraine. 8.1041 + Supposez qu'il y ait un gros fichier source qui ait été largement édité de 8.1042 + chaque coté de la fusion (merge) : ceci va inévitablement résulter en 8.1043 + conflits, dont certains peuvent prendre plusieurs essais pour s'en 8.1044 + sortir.</para> 8.1045 + 8.1046 + <para id="x_688">Développons en un cas simple pour voir comment le gérer. 8.1047 + Nous allons commencer avec un dépôt contenant un fichier, et le 8.1048 + cloner deux fois.</para> 8.1049 + 8.1050 + &interaction.ch04-resolve.init; 8.1051 + 8.1052 + <para id="x_689">Dans un des clones, nous allons modifier le fichier 8.1053 + d'une façon.</para> 8.1054 + 8.1055 + &interaction.ch04-resolve.left; 8.1056 + 8.1057 + <para id="x_68a">Dans un autre, nous allons modifier le fichier 8.1058 + différemment.</para> 8.1059 + 8.1060 + &interaction.ch04-resolve.right; 8.1061 + 8.1062 + <para id="x_68b">Ensuite, nous allons récupérer (pull) chaque ensemble de 8.1063 + changement dans notre dépôt original.</para> 8.1064 + 8.1065 + &interaction.ch04-resolve.pull; 8.1066 + 8.1067 + <para id="x_68c">Nous nous attendons à ce que notre dépôt contienne deux 8.1068 + "heads".</para> 8.1069 + 8.1070 + &interaction.ch04-resolve.heads; 8.1071 + 8.1072 + <para id="x_68d">Normalement, si nous lançons <command role="hg-cmd">hg 8.1073 + merge</command> à ce point, il nous renverra vers une interface 8.1074 + utilisateur qui nous permettra de résoudre manuellement les éditions 8.1075 + conflictuelles sur le fichier <filename>myfile.txt</filename>. 8.1076 + Cependant, pour simplifier ici les choses dans la présentation, nous 8.1077 + aimerions plutôt que la fusion (merge) échoue immédiatement. Voici une 8.1078 + façon de le faire.</para> 8.1079 + 8.1080 + &interaction.ch04-resolve.export; 8.1081 + 8.1082 + <para id="x_68e">Nous avons dit au processus de fusion de Mercurial 8.1083 + d'exécuter la commande <command>false</command> (qui échoue 8.1084 + immédiatement, à la demande) s'il détecte une fusion (merge) qu'il ne 8.1085 + peut pas arranger automatiquement.</para> 8.1086 + 8.1087 + <para id="x_68f">Si nous appelons maintenant <command role="hg-cmd">hg 8.1088 + merge</command>, il devrait échouer et reporter une erreur.</para> 8.1089 + 8.1090 + &interaction.ch04-resolve.merge; 8.1091 + 8.1092 + <para id="x_690">Même si nous ne remarquons pas qu'une fusion (merge) a 8.1093 + échoué, Mercurial nous empêchera de committer le résultat d'une fusion 8.1094 + ratée.</para> 8.1095 + 8.1096 + &interaction.ch04-resolve.cifail; 8.1097 + 8.1098 + <para id="x_691">Lorsque <command role="hg-cmd">hg commit</command> 8.1099 + échoue dans ce cas, il suggère que nous utilisons la commande peu 8.1100 + connue <command role="hg-cmd">hg resolve</command>. Comme d'habitude, 8.1101 + <command role="hg-cmd">hg help resolve</command> affichera une aide 8.1102 + sommaire.</para> 8.1103 + 8.1104 + <sect2> 8.1105 + <title>États de résolution des fichiers</title> 8.1106 + <!-- TODO Vérifier traduction : File resolution states --> 8.1107 + 8.1108 + <para id="x_692">Lorsqu'une fusion intervient, la plupart des fichiers 8.1109 + vont, la plupart du temps, rester sans modification. Pour chaque 8.1110 + fichier sur lequel Mercurial doit faire quelque chose, il suit l'état 8.1111 + de celui-ci.</para> 8.1112 + 8.1113 + <itemizedlist> 8.1114 + <listitem><para id="x_693">Un fichier 8.1115 + <quote><emphasis>resolved</emphasis></quote> a été fusionné 8.1116 + (merge) avec succès, que ce soit automatiquement par Mercurial ou 8.1117 + manuellement par une intervention humaine.</para></listitem> 8.1118 + <listitem><para id="x_694">Un fichier 8.1119 + <quote><emphasis>unresolved</emphasis></quote> n'a pas été 8.1120 + fusionné (merge) correctement et a besoin de plus 8.1121 + d'attention.</para> 8.1122 + </listitem> 8.1123 + </itemizedlist> 8.1124 + 8.1125 + <para id="x_695">Si Mercurial voit un fichier 8.1126 + <emphasis>quelconque</emphasis> dans un état 8.1127 + <quote>unresolved</quote> après une fusion (merge), il considère que 8.1128 + la fusion (merge) a échoué. Heureusement, nous n'avons pas à 8.1129 + recommencer la procédure à partir du début.</para> 8.1130 + 8.1131 + <para id="x_696">L'option <option role="hg-opt-resolve">--list</option> 8.1132 + ou <option role="hg-opt-resolve">-l</option> passée à <command 8.1133 + role="hg-cmd">hg resolve</command> liste l'état de chaque fichier 8.1134 + fusionné (merge).</para> 8.1135 + 8.1136 + &interaction.ch04-resolve.list; 8.1137 + 8.1138 + <para id="x_697">En sortie de <command role="hg-cmd">hg 8.1139 + resolve</command>, un fichier "resolved" est marqué avec un 8.1140 + <literal>R</literal>, alors qu'un fichier "unresolved" est marqué 8.1141 + d'un <literal>U</literal>. S'il existe un fichier listé avec un 8.1142 + <literal>U</literal>, nous savons qu'essayer de committer le résultat 8.1143 + de la fusion (merge) échouera.</para> 8.1144 + </sect2> 8.1145 + 8.1146 + <sect2> 8.1147 + <title>Résoudre une fusion de fichier</title> 8.1148 + 8.1149 + <para id="x_698">Nous avons plusieurs options pour changer l'état d'un 8.1150 + fichier de "unresolved" à "resolved". Le plus commun est de relancer 8.1151 + <command role="hg-cmd">hg resolve</command>. Si nous passons les noms 8.1152 + des fichiers individuels ou des répertoires, ceci retentera la fusion 8.1153 + de tous les fichiers présents à cet endroit. Nous pouvons aussi 8.1154 + passer l'option <option role="hg-opt-resolve">--all</option> ou 8.1155 + <option role="hg-opt-resolve">-a</option> qui tentera de fusionner 8.1156 + <emphasis>tous</emphasis> les fichiers "unresolved".</para> 8.1157 + 8.1158 + <para id="x_699">Mercurial nous laisse aussi modifier la résolution 8.1159 + d'un fichier directement. Nous pouvons marquer un fichier "resolved" 8.1160 + en utilisant l'option <option role="hg-opt-resolve">--mark</option>, 8.1161 + ou "unresolved" en utilisant l'option <option 8.1162 + role="hg-opt-resolve">--unmark</option>. Ceci nous autorise à 8.1163 + nettoyer une fusion particulièrement compliquée à la main, et de 8.1164 + garder un suivi de nos progrès avec chaque fichier pendant que nous 8.1165 + procédons.</para> 8.1166 + </sect2> 8.1167 + </sect1> 8.1168 + 8.1169 + <sect1> 8.1170 + <title>Des "diffs" plus utiles</title> 8.1171 + 8.1172 + <para id="x_6c7">La sortie par défaut de la commande <command 8.1173 + role="hg-cmd">hg diff</command> est compatible rétrospectivement avec 8.1174 + la commande régulière <command>diff</command>, mais ceci a quelques 8.1175 + inconvénients.</para> 8.1176 + 8.1177 + <para id="x_6c8">Considérez le cas où nous utilisons <command role="hg-cmd">hg 8.1178 + rename</command> pour renommer un fichier.</para> 8.1179 + 8.1180 + &interaction.ch04-diff.rename.basic; 8.1181 + 8.1182 + <para id="x_6c9">La sortie de <command role="hg-cmd">hg diff</command> 8.1183 + ci-dessus cache le fait que nous avons simplement renommé un fichier. 8.1184 + La commande <command role="hg-cmd">hg diff</command> accepte l'option 8.1185 + <option>--git</option> ou <option>-g</option> pour utiliser un nouveau 8.1186 + format de diff qui montre ces informations sous une forme plus 8.1187 + expressive.</para> 8.1188 + 8.1189 + &interaction.ch04-diff.rename.git; 8.1190 + 8.1191 + <para id="x_6ca">Cette option peut aussi aider avec le cas autrement 8.1192 + confus : un fichier qui apparaît comme étant modifié en accord avec 8.1193 + <command role="hg-cmd">hg status</command>, mais où <command 8.1194 + role="hg-cmd">hg diff</command> n'affiche rien. Cette situation peut 8.1195 + survenir si nous changeons les permissions d'exécution du 8.1196 + fichier.</para> 8.1197 + 8.1198 + &interaction.ch04-diff.chmod; 8.1199 + 8.1200 + <para id="x_6cb">La commande normale <command>diff</command> ne fait pas 8.1201 + attention aux permissions des fichiers, ce qui explique pourquoi 8.1202 + <command role="hg-cmd">hg diff</command> n'affiche rien du tout par 8.1203 + défaut. Si nous lui passons l'option <option>-g</option>, ceci nous 8.1204 + informe de ce qu'il s'est vraiment passé.</para> 8.1205 + 8.1206 + &interaction.ch04-diff.chmod.git; 8.1207 + </sect1> 8.1208 + 8.1209 + <sect1> 8.1210 + <title>Quels fichiers suivre et lesquels éviter</title> 8.1211 + 8.1212 + <para id="x_6cc">Les systèmes de gestion de révisions sont en général 8.1213 + meilleurs pour gérer les fichiers textes qui sont écrits par les 8.1214 + humains, comme le code source, où les fichiers ne changent pas 8.1215 + énormément d'une révision à l'autre. Certains systèmes de gestion de 8.1216 + révisions centralisés peuvent aussi traiter très convenablement les 8.1217 + fichiers binaires, tels que les images bitmap.</para> 8.1218 + 8.1219 + <para id="x_6cd">Par exemple, une équipe de développement de jeux va 8.1220 + probablement gérer les deux types : ses codes source et tous ses binaires 8.1221 + (ex. données géométriques, textures, schémas de cartes) dans un système 8.1222 + de contrôle de révisions.</para> 8.1223 + <!-- Vérifier la traduction de map layouts que j'ai traduit par schémas 8.1224 + de cartes --> 8.1225 + 8.1226 + <para id="x_6ce">Puisqu'il est d'habitude impossible de fusionner (merge) 8.1227 + deux modifications conflictuelles sur un fichier binaire, les systèmes 8.1228 + de version centralisés offrent souvent un mécanisme de verrou (lock) qui 8.1229 + permet à un utilisateur de dire <quote>Je suis la seule personne qui 8.1230 + peut éditer ce fichier</quote>.</para> 8.1231 + 8.1232 + <para id="x_6cf">En comparaison avec un système centralisé, un système 8.1233 + décentralisé de gestion de révision change certains facteurs qui 8.1234 + guident les décisions sur quels fichiers gérer et comment.</para> 8.1235 + 8.1236 + <para id="x_6d0">Par exemple, un système distribué de gestion de révisions 8.1237 + ne peut pas, par sa nature, offrir un système de véroux (lock) sur les 8.1238 + fichiers. Il n'y a donc pas de mécanisme inclus pour empêcher deux 8.1239 + personnes de faire des modifications conflictuelles sur un fichier 8.1240 + binaire. Si vous avez une équipe où plusieurs personnes peuvent souvent 8.1241 + éditer un fichier binaire, cela ne serait pas une très bonne idée 8.1242 + d'utiliser Mercurial &emdash;ou tout autre système distribué de gestion 8.1243 + de révisions&emdash;pour gérer ces fichiers.</para> 8.1244 + 8.1245 + <para id="x_6d1">Lorsque vous sauvegardez les modifications sur un 8.1246 + fichier, Mercurial ne sauvegarde d'habitude que les différences entre 8.1247 + la version précédente et la version actuelle d'un fichier. Pour la 8.1248 + plupart des fichiers texte, ceci est très efficace. Cependant, certains 8.1249 + fichiers (en particulier les fichiers binaires) sont construits d'une 8.1250 + façon que même un petit changement sur un contenu logique résulte sur 8.1251 + un changement de la plupart des octets du fichier. Par exemple, les 8.1252 + fichiers compressés sont particulièrement sujets à ce comportement. Si 8.1253 + les différences entre deux versions successives d'un fichier sont 8.1254 + toujours très grandes, Mercurial ne sera pas capable de sauvegarder 8.1255 + l'historique des révisions sur le fichier très efficacement. Ceci peut 8.1256 + affecter aussi bien les besoins pour la sauvegarde locale que le temps 8.1257 + nécessaire à cloner le dépôt.</para> 8.1258 + 8.1259 + <para id="x_6d2">Pour avoir une idée de comment ceci pourrait vous 8.1260 + affecter en pratique, supposez que nous voulions que Mercurial gère des 8.1261 + documents OpenOffice. OpenOffice sauvegarde les documents sur le disque 8.1262 + comme des fichiers compressés zip. Même le fait d'éditer ces fichiers 8.1263 + d'une seule lettre, changera les bits de la quasi totalité du fichier 8.1264 + lorsque vous le sauvegarderez. Maintenant, supposez que ce fichier 8.1265 + fasse une taille de 2Mo. Puisque la plupart du fichier change à chaque 8.1266 + fois que vous sauvegardez, Mercurial aura à sauvegarder tous les 2Mo du 8.1267 + fichier à chaque commit, alors que de votre point de vue, il n'y a 8.1268 + que peu de mots qui changent à chaque fois. Un seul fichier 8.1269 + souvent édité qui n'est pas bien traité par les hypothèses que Mercurial 8.1270 + fait sur les sauvegardes peut facilement avoir un effet colossal sur la 8.1271 + taille du dépôt.</para> 8.1272 + 8.1273 + <para id="x_6d3">Même pire, si vous et quelqu'un d'autre éditez le même 8.1274 + document OpenOffice sur lequel vous travaillez, il n'y a pas de façon 8.1275 + utile pour fusionner votre travail. En fait, il n'y a pas de moyen 8.1276 + utile de montrer que les différences sont faites à partir de votre 8.1277 + vision des modifications.</para> 8.1278 + 8.1279 + <para id="x_6d4">Il y a ainsi quelques recommandations claires sur les 8.1280 + types de fichiers spécifiques avec lesquels faire très 8.1281 + attention.</para> 8.1282 + 8.1283 + <itemizedlist> 8.1284 + <listitem><para id="x_6d5">Les fichier qui sont très gros et 8.1285 + incompressibles, comme les images ISO de CD-ROM, sont, par 8.1286 + construction très gros et les cloner à travers un réseau sera très 8.1287 + long.</para></listitem> 8.1288 + <!-- TODO : Trouver une meilleure traduction pour : ISO CD-ROM images, will by 8.1289 + virtue of sheer size make clones over a network very slow. --> 8.1290 + <listitem><para id="x_6d6">Les fichiers qui changent beaucoup d'une 8.1291 + révision à l'autre peuvent être très chers à sauvegarder si vous 8.1292 + les éditez fréquemment, de même que les conflits entre deux éditions 8.1293 + concurrentes peuvent être difficiles à résoudre.</para> 8.1294 + </listitem> 8.1295 + </itemizedlist> 8.1296 + </sect1> 8.1297 + 8.1298 + <sect1> 8.1299 + <title>Sauvegardes et miroirs</title> 8.1300 + 8.1301 + <para id="x_6d7">Puisque Mercurial maintient une copie complète de 8.1302 + l'historique de chaque clone, toute personne qui utilise Mercurial pour 8.1303 + collaborer à un projet peut potentiellement agir comme une source de 8.1304 + sauvegarde si une catastrophe survenait. Si un dépôt central devient 8.1305 + indisponible, vous pouvez construire un remplaçant en clonant une copie 8.1306 + du dépôt à partir d'un des contributeurs en récupérant (pull) tous les 8.1307 + changements qui n'auraient pas été vus par les autres.</para> 8.1308 + 8.1309 + <para id="x_6d8">Il est simple d'utiliser Mercurial pour construire des 8.1310 + serveurs hors site de sauvegarde et des miroirs distants. Initiez une 8.1311 + tâche périodique (ex. via la commande <command>cron</command>) sur un 8.1312 + serveur distant pour récupérer (pull) les changements de votre dépôt 8.1313 + distant chaque heure. Ceci sera difficile seulement dans le cas 8.1314 + improbable où le nombre des dépôts maîtres que vous maintenez change 8.1315 + souvent, auquel cas vous aurez besoin de faire un peu de scripting pour 8.1316 + rafraichir la liste des dépôt à sauvegarder.</para> 8.1317 + 8.1318 + <para id="x_6d9">Si vous exécutez des sauvegardes traditionnelles de 8.1319 + votre dépôt maître sur bande ou disque, et que vous voulez sauvegarder 8.1320 + un dépôt nommé <filename>myrepo</filename>, utilisez la commande 8.1321 + <command>hg clone -U myrepo myrepo.bak</command> pour créer un clone de 8.1322 + <filename>myrepo</filename> avant de commencer vos backups. 8.1323 + L'option <option>-U</option> ne crée pas de répertoire de travail après 8.1324 + que le clone soit accompli, puisque ceci serait superflu et ferait que 8.1325 + la sauvegarde prenne plus de temps.</para> 8.1326 + 8.1327 + <para id="x_6da">Si vous voulez ensuite sauvegarder 8.1328 + <filename>myrepo.bak</filename> au lieu de <filename>myrepo</filename>, 8.1329 + vous aurez la garantie d'avoir une image (snapshot) consistante de 8.1330 + votre dépôt sur lequel un développeur insomniaque n'enverra (push) pas de 8.1331 + changements en milieu de sauvegarde.</para> 8.1332 + </sect1> 8.1333 </chapter> 8.1334 8.1335 <!-- 8.1336 local variables: 8.1337 sgml-parent-document: ("00book.xml" "book" "chapter") 8.1338 end: 8.1339 ---> 8.1340 \ No newline at end of file 8.1341 +-->
9.1 --- a/fr/ch06-collab.xml Sat Sep 12 17:58:26 2009 +0200 9.2 +++ b/fr/ch06-collab.xml Sat Sep 12 17:58:56 2009 +0200 9.3 @@ -1,1405 +1,1565 @@ 9.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 9.5 9.6 -<chapter> 9.7 -<title>Collaborating with other people</title> 9.8 -<para>\label{cha:collab}</para> 9.9 - 9.10 -<para>As a completely decentralised tool, Mercurial doesn't impose any 9.11 -policy on how people ought to work with each other. However, if 9.12 -you're new to distributed revision control, it helps to have some 9.13 -tools and examples in mind when you're thinking about possible 9.14 -workflow models.</para> 9.15 - 9.16 -<sect1> 9.17 -<title>Mercurial's web interface</title> 9.18 - 9.19 -<para>Mercurial has a powerful web interface that provides several 9.20 -useful capabilities.</para> 9.21 - 9.22 -<para>For interactive use, the web interface lets you browse a single 9.23 -repository or a collection of repositories. You can view the history 9.24 -of a repository, examine each change (comments and diffs), and view 9.25 -the contents of each directory and file.</para> 9.26 - 9.27 -<para>Also for human consumption, the web interface provides an RSS feed of 9.28 -the changes in a repository. This lets you <quote>subscribe</quote> to a 9.29 -repository using your favourite feed reader, and be automatically 9.30 -notified of activity in that repository as soon as it happens. I find 9.31 -this capability much more convenient than the model of subscribing to 9.32 -a mailing list to which notifications are sent, as it requires no 9.33 -additional configuration on the part of whoever is serving the 9.34 -repository.</para> 9.35 - 9.36 -<para>The web interface also lets remote users clone a repository, pull 9.37 -changes from it, and (when the server is configured to permit it) push 9.38 -changes back to it. Mercurial's HTTP tunneling protocol aggressively 9.39 -compresses data, so that it works efficiently even over low-bandwidth 9.40 -network connections.</para> 9.41 - 9.42 -<para>The easiest way to get started with the web interface is to use your 9.43 -web browser to visit an existing repository, such as the master 9.44 -Mercurial repository at 9.45 -<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para> 9.46 - 9.47 -<para>If you're interested in providing a web interface to your own 9.48 -repositories, Mercurial provides two ways to do this. The first is 9.49 -using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term 9.50 -<quote>lightweight</quote> serving. See section <xref linkend="sec:collab:serve"/> below for 9.51 -details of how to use this command. If you have a long-lived 9.52 -repository that you'd like to make permanently available, Mercurial 9.53 -has built-in support for the CGI (Common Gateway Interface) standard, 9.54 -which all common web servers support. See 9.55 -section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para> 9.56 - 9.57 -</sect1> 9.58 -<sect1> 9.59 -<title>Collaboration models</title> 9.60 - 9.61 -<para>With a suitably flexible tool, making decisions about workflow is much 9.62 -more of a social engineering challenge than a technical one. 9.63 -Mercurial imposes few limitations on how you can structure the flow of 9.64 -work in a project, so it's up to you and your group to set up and live 9.65 -with a model that matches your own particular needs. 9.66 -</para> 9.67 - 9.68 -<sect2> 9.69 -<title>Factors to keep in mind</title> 9.70 - 9.71 -<para>The most important aspect of any model that you must keep in mind is 9.72 -how well it matches the needs and capabilities of the people who will 9.73 -be using it. This might seem self-evident; even so, you still can't 9.74 -afford to forget it for a moment. 9.75 -</para> 9.76 - 9.77 -<para>I once put together a workflow model that seemed to make perfect sense 9.78 -to me, but that caused a considerable amount of consternation and 9.79 -strife within my development team. In spite of my attempts to explain 9.80 -why we needed a complex set of branches, and how changes ought to flow 9.81 -between them, a few team members revolted. Even though they were 9.82 -smart people, they didn't want to pay attention to the constraints we 9.83 -were operating under, or face the consequences of those constraints in 9.84 -the details of the model that I was advocating. 9.85 -</para> 9.86 - 9.87 -<para>Don't sweep foreseeable social or technical problems under the rug. 9.88 -Whatever scheme you put into effect, you should plan for mistakes and 9.89 -problem scenarios. Consider adding automated machinery to prevent, or 9.90 -quickly recover from, trouble that you can anticipate. As an example, 9.91 -if you intend to have a branch with not-for-release changes in it, 9.92 -you'd do well to think early about the possibility that someone might 9.93 -accidentally merge those changes into a release branch. You could 9.94 -avoid this particular problem by writing a hook that prevents changes 9.95 -from being merged from an inappropriate branch. 9.96 -</para> 9.97 - 9.98 -</sect2> 9.99 -<sect2> 9.100 -<title>Informal anarchy</title> 9.101 - 9.102 -<para>I wouldn't suggest an <quote>anything goes</quote> approach as something 9.103 -sustainable, but it's a model that's easy to grasp, and it works 9.104 -perfectly well in a few unusual situations. 9.105 -</para> 9.106 - 9.107 -<para>As one example, many projects have a loose-knit group of collaborators 9.108 -who rarely physically meet each other. Some groups like to overcome 9.109 -the isolation of working at a distance by organising occasional 9.110 -<quote>sprints</quote>. In a sprint, a number of people get together in a single 9.111 -location (a company's conference room, a hotel meeting room, that kind 9.112 -of place) and spend several days more or less locked in there, hacking 9.113 -intensely on a handful of projects. 9.114 -</para> 9.115 - 9.116 -<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since 9.117 -<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure. You 9.118 -can get started with <command role="hg-cmd">hg serve</command> in moments, by reading 9.119 -section <xref linkend="sec:collab:serve"/> below. Then simply tell the person 9.120 -next to you that you're running a server, send the URL to them in an 9.121 -instant message, and you immediately have a quick-turnaround way to 9.122 -work together. They can type your URL into their web browser and 9.123 -quickly review your changes; or they can pull a bugfix from you and 9.124 -verify it; or they can clone a branch containing a new feature and try 9.125 -it out. 9.126 -</para> 9.127 - 9.128 -<para>The charm, and the problem, with doing things in an ad hoc fashion 9.129 -like this is that only people who know about your changes, and where 9.130 -they are, can see them. Such an informal approach simply doesn't 9.131 -scale beyond a handful people, because each individual needs to know 9.132 -about $n$ different repositories to pull from. 9.133 -</para> 9.134 - 9.135 -</sect2> 9.136 -<sect2> 9.137 -<title>A single central repository</title> 9.138 - 9.139 -<para>For smaller projects migrating from a centralised revision control 9.140 -tool, perhaps the easiest way to get started is to have changes flow 9.141 -through a single shared central repository. This is also the 9.142 -most common <quote>building block</quote> for more ambitious workflow schemes. 9.143 -</para> 9.144 - 9.145 -<para>Contributors start by cloning a copy of this repository. They can 9.146 -pull changes from it whenever they need to, and some (perhaps all) 9.147 -developers have permission to push a change back when they're ready 9.148 -for other people to see it. 9.149 -</para> 9.150 - 9.151 -<para>Under this model, it can still often make sense for people to pull 9.152 -changes directly from each other, without going through the central 9.153 -repository. Consider a case in which I have a tentative bug fix, but 9.154 -I am worried that if I were to publish it to the central repository, 9.155 -it might subsequently break everyone else's trees as they pull it. To 9.156 -reduce the potential for damage, I can ask you to clone my repository 9.157 -into a temporary repository of your own and test it. This lets us put 9.158 -off publishing the potentially unsafe change until it has had a little 9.159 -testing. 9.160 -</para> 9.161 - 9.162 -<para>In this kind of scenario, people usually use the <command>ssh</command> 9.163 -protocol to securely push changes to the central repository, as 9.164 -documented in section <xref linkend="sec:collab:ssh"/>. It's also usual to 9.165 -publish a read-only copy of the repository over HTTP using CGI, as in 9.166 -section <xref linkend="sec:collab:cgi"/>. Publishing over HTTP satisfies the 9.167 -needs of people who don't have push access, and those who want to use 9.168 -web browsers to browse the repository's history. 9.169 -</para> 9.170 - 9.171 -</sect2> 9.172 -<sect2> 9.173 -<title>Working with multiple branches</title> 9.174 - 9.175 -<para>Projects of any significant size naturally tend to make progress on 9.176 -several fronts simultaneously. In the case of software, it's common 9.177 -for a project to go through periodic official releases. A release 9.178 -might then go into <quote>maintenance mode</quote> for a while after its first 9.179 -publication; maintenance releases tend to contain only bug fixes, not 9.180 -new features. In parallel with these maintenance releases, one or 9.181 -more future releases may be under development. People normally use 9.182 -the word <quote>branch</quote> to refer to one of these many slightly different 9.183 -directions in which development is proceeding. 9.184 -</para> 9.185 - 9.186 -<para>Mercurial is particularly well suited to managing a number of 9.187 -simultaneous, but not identical, branches. Each <quote>development 9.188 -direction</quote> can live in its own central repository, and you can merge 9.189 -changes from one to another as the need arises. Because repositories 9.190 -are independent of each other, unstable changes in a development 9.191 -branch will never affect a stable branch unless someone explicitly 9.192 -merges those changes in. 9.193 -</para> 9.194 - 9.195 -<para>Here's an example of how this can work in practice. Let's say you 9.196 -have one <quote>main branch</quote> on a central server. 9.197 -<!-- &interaction.branching.init; --> 9.198 -People clone it, make changes locally, test them, and push them back. 9.199 -</para> 9.200 - 9.201 -<para>Once the main branch reaches a release milestone, you can use the 9.202 -<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone 9.203 -revision. 9.204 -<!-- &interaction.branching.tag; --> 9.205 -Let's say some ongoing development occurs on the main branch. 9.206 -<!-- &interaction.branching.main; --> 9.207 -Using the tag that was recorded at the milestone, people who clone 9.208 -that repository at any time in the future can use <command role="hg-cmd">hg update</command> to 9.209 -get a copy of the working directory exactly as it was when that tagged 9.210 -revision was committed. 9.211 -<!-- &interaction.branching.update; --> 9.212 -</para> 9.213 - 9.214 -<para>In addition, immediately after the main branch is tagged, someone can 9.215 -then clone the main branch on the server to a new <quote>stable</quote> branch, 9.216 -also on the server. 9.217 -<!-- &interaction.branching.clone; --> 9.218 -</para> 9.219 - 9.220 -<para>Someone who needs to make a change to the stable branch can then clone 9.221 -<emphasis>that</emphasis> repository, make their changes, commit, and push their 9.222 -changes back there. 9.223 -<!-- &interaction.branching.stable; --> 9.224 -Because Mercurial repositories are independent, and Mercurial doesn't 9.225 -move changes around automatically, the stable and main branches are 9.226 -<emphasis>isolated</emphasis> from each other. The changes that you made on the 9.227 -main branch don't <quote>leak</quote> to the stable branch, and vice versa. 9.228 -</para> 9.229 - 9.230 -<para>You'll often want all of your bugfixes on the stable branch to show up 9.231 -on the main branch, too. Rather than rewrite a bugfix on the main 9.232 -branch, you can simply pull and merge changes from the stable to the 9.233 -main branch, and Mercurial will bring those bugfixes in for you. 9.234 -<!-- &interaction.branching.merge; --> 9.235 -The main branch will still contain changes that are not on the stable 9.236 -branch, but it will also contain all of the bugfixes from the stable 9.237 -branch. The stable branch remains unaffected by these changes. 9.238 -</para> 9.239 - 9.240 -</sect2> 9.241 -<sect2> 9.242 -<title>Feature branches</title> 9.243 - 9.244 -<para>For larger projects, an effective way to manage change is to break up 9.245 -a team into smaller groups. Each group has a shared branch of its 9.246 -own, cloned from a single <quote>master</quote> branch used by the entire 9.247 -project. People working on an individual branch are typically quite 9.248 -isolated from developments on other branches. 9.249 -</para> 9.250 - 9.251 -<informalfigure> 9.252 - 9.253 -<para> <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 9.254 - <caption><para>Feature branches</para></caption> 9.255 - \label{fig:collab:feature-branches} 9.256 -</para> 9.257 -</informalfigure> 9.258 - 9.259 -<para>When a particular feature is deemed to be in suitable shape, someone 9.260 -on that feature team pulls and merges from the master branch into the 9.261 -feature branch, then pushes back up to the master branch. 9.262 -</para> 9.263 - 9.264 -</sect2> 9.265 -<sect2> 9.266 -<title>The release train</title> 9.267 - 9.268 -<para>Some projects are organised on a <quote>train</quote> basis: a release is 9.269 -scheduled to happen every few months, and whatever features are ready 9.270 -when the <quote>train</quote> is ready to leave are allowed in. 9.271 -</para> 9.272 - 9.273 -<para>This model resembles working with feature branches. The difference is 9.274 -that when a feature branch misses a train, someone on the feature team 9.275 -pulls and merges the changes that went out on that train release into 9.276 -the feature branch, and the team continues its work on top of that 9.277 -release so that their feature can make the next release. 9.278 -</para> 9.279 - 9.280 -</sect2> 9.281 -<sect2> 9.282 -<title>The Linux kernel model</title> 9.283 - 9.284 -<para>The development of the Linux kernel has a shallow hierarchical 9.285 -structure, surrounded by a cloud of apparent chaos. Because most 9.286 -Linux developers use <command>git</command>, a distributed revision control 9.287 -tool with capabilities similar to Mercurial, it's useful to describe 9.288 -the way work flows in that environment; if you like the ideas, the 9.289 -approach translates well across tools. 9.290 -</para> 9.291 - 9.292 -<para>At the center of the community sits Linus Torvalds, the creator of 9.293 -Linux. He publishes a single source repository that is considered the 9.294 -<quote>authoritative</quote> current tree by the entire developer community. 9.295 -Anyone can clone Linus's tree, but he is very choosy about whose trees 9.296 -he pulls from. 9.297 -</para> 9.298 - 9.299 -<para>Linus has a number of <quote>trusted lieutenants</quote>. As a general rule, he 9.300 -pulls whatever changes they publish, in most cases without even 9.301 -reviewing those changes. Some of those lieutenants are generally 9.302 -agreed to be <quote>maintainers</quote>, responsible for specific subsystems 9.303 -within the kernel. If a random kernel hacker wants to make a change 9.304 -to a subsystem that they want to end up in Linus's tree, they must 9.305 -find out who the subsystem's maintainer is, and ask that maintainer to 9.306 -take their change. If the maintainer reviews their changes and agrees 9.307 -to take them, they'll pass them along to Linus in due course. 9.308 -</para> 9.309 - 9.310 -<para>Individual lieutenants have their own approaches to reviewing, 9.311 -accepting, and publishing changes; and for deciding when to feed them 9.312 -to Linus. In addition, there are several well known branches that 9.313 -people use for different purposes. For example, a few people maintain 9.314 -<quote>stable</quote> repositories of older versions of the kernel, to which they 9.315 -apply critical fixes as needed. Some maintainers publish multiple 9.316 -trees: one for experimental changes; one for changes that they are 9.317 -about to feed upstream; and so on. Others just publish a single 9.318 -tree. 9.319 -</para> 9.320 - 9.321 -<para>This model has two notable features. The first is that it's <quote>pull 9.322 -only</quote>. You have to ask, convince, or beg another developer to take a 9.323 -change from you, because there are almost no trees to which more than 9.324 -one person can push, and there's no way to push changes into a tree 9.325 -that someone else controls. 9.326 -</para> 9.327 - 9.328 -<para>The second is that it's based on reputation and acclaim. If you're an 9.329 -unknown, Linus will probably ignore changes from you without even 9.330 -responding. But a subsystem maintainer will probably review them, and 9.331 -will likely take them if they pass their criteria for suitability. 9.332 -The more <quote>good</quote> changes you contribute to a maintainer, the more 9.333 -likely they are to trust your judgment and accept your changes. If 9.334 -you're well-known and maintain a long-lived branch for something Linus 9.335 -hasn't yet accepted, people with similar interests may pull your 9.336 -changes regularly to keep up with your work. 9.337 -</para> 9.338 - 9.339 -<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote> 9.340 -boundaries. If you're a respected but specialised storage hacker, and 9.341 -you try to fix a networking bug, that change will receive a level of 9.342 -scrutiny from a network maintainer comparable to a change from a 9.343 -complete stranger. 9.344 -</para> 9.345 - 9.346 -<para>To people who come from more orderly project backgrounds, the 9.347 -comparatively chaotic Linux kernel development process often seems 9.348 -completely insane. It's subject to the whims of individuals; people 9.349 -make sweeping changes whenever they deem it appropriate; and the pace 9.350 -of development is astounding. And yet Linux is a highly successful, 9.351 -well-regarded piece of software. 9.352 -</para> 9.353 - 9.354 -</sect2> 9.355 -<sect2> 9.356 -<title>Pull-only versus shared-push collaboration</title> 9.357 - 9.358 -<para>A perpetual source of heat in the open source community is whether a 9.359 -development model in which people only ever pull changes from others 9.360 -is <quote>better than</quote> one in which multiple people can push changes to a 9.361 -shared repository. 9.362 -</para> 9.363 - 9.364 -<para>Typically, the backers of the shared-push model use tools that 9.365 -actively enforce this approach. If you're using a centralised 9.366 -revision control tool such as Subversion, there's no way to make a 9.367 -choice over which model you'll use: the tool gives you shared-push, 9.368 -and if you want to do anything else, you'll have to roll your own 9.369 -approach on top (such as applying a patch by hand). 9.370 -</para> 9.371 - 9.372 -<para>A good distributed revision control tool, such as Mercurial, will 9.373 -support both models. You and your collaborators can then structure 9.374 -how you work together based on your own needs and preferences, not on 9.375 -what contortions your tools force you into. 9.376 -</para> 9.377 - 9.378 -</sect2> 9.379 -<sect2> 9.380 -<title>Where collaboration meets branch management</title> 9.381 - 9.382 -<para>Once you and your team set up some shared repositories and start 9.383 -propagating changes back and forth between local and shared repos, you 9.384 -begin to face a related, but slightly different challenge: that of 9.385 -managing the multiple directions in which your team may be moving at 9.386 -once. Even though this subject is intimately related to how your team 9.387 -collaborates, it's dense enough to merit treatment of its own, in 9.388 -chapter <xref linkend="chap:branch"/>. 9.389 -</para> 9.390 - 9.391 -</sect2> 9.392 -</sect1> 9.393 -<sect1> 9.394 -<title>The technical side of sharing</title> 9.395 - 9.396 -<para>The remainder of this chapter is devoted to the question of serving 9.397 -data to your collaborators. 9.398 -</para> 9.399 - 9.400 -</sect1> 9.401 -<sect1> 9.402 -<title>Informal sharing with <command role="hg-cmd">hg serve</command></title> 9.403 -<para>\label{sec:collab:serve} 9.404 -</para> 9.405 - 9.406 -<para>Mercurial's <command role="hg-cmd">hg serve</command> command is wonderfully suited to small, 9.407 -tight-knit, and fast-paced group environments. It also provides a 9.408 -great way to get a feel for using Mercurial commands over a network. 9.409 -</para> 9.410 - 9.411 -<para>Run <command role="hg-cmd">hg serve</command> inside a repository, and in under a second it will 9.412 -bring up a specialised HTTP server; this will accept connections from 9.413 -any client, and serve up data for that repository until you terminate 9.414 -it. Anyone who knows the URL of the server you just started, and can 9.415 -talk to your computer over the network, can then use a web browser or 9.416 -Mercurial to read data from that repository. A URL for a 9.417 -<command role="hg-cmd">hg serve</command> instance running on a laptop is likely to look something 9.418 -like <literal>http://my-laptop.local:8000/</literal>. 9.419 -</para> 9.420 - 9.421 -<para>The <command role="hg-cmd">hg serve</command> command is <emphasis>not</emphasis> a general-purpose web server. 9.422 -It can do only two things: 9.423 -</para> 9.424 -<itemizedlist> 9.425 -<listitem><para>Allow people to browse the history of the repository it's 9.426 - serving, from their normal web browsers. 9.427 -</para> 9.428 -</listitem> 9.429 -<listitem><para>Speak Mercurial's wire protocol, so that people can 9.430 - <command role="hg-cmd">hg clone</command> or <command role="hg-cmd">hg pull</command> changes from that repository. 9.431 -</para> 9.432 -</listitem></itemizedlist> 9.433 -<para>In particular, <command role="hg-cmd">hg serve</command> won't allow remote users to <emphasis>modify</emphasis> 9.434 -your repository. It's intended for read-only use. 9.435 -</para> 9.436 - 9.437 -<para>If you're getting started with Mercurial, there's nothing to prevent 9.438 -you from using <command role="hg-cmd">hg serve</command> to serve up a repository on your own 9.439 -computer, then use commands like <command role="hg-cmd">hg clone</command>, <command role="hg-cmd">hg incoming</command>, and 9.440 -so on to talk to that server as if the repository was hosted remotely. 9.441 -This can help you to quickly get acquainted with using commands on 9.442 -network-hosted repositories. 9.443 -</para> 9.444 - 9.445 -<sect2> 9.446 -<title>A few things to keep in mind</title> 9.447 - 9.448 -<para>Because it provides unauthenticated read access to all clients, you 9.449 -should only use <command role="hg-cmd">hg serve</command> in an environment where you either don't 9.450 -care, or have complete control over, who can access your network and 9.451 -pull data from your repository. 9.452 -</para> 9.453 - 9.454 -<para>The <command role="hg-cmd">hg serve</command> command knows nothing about any firewall software 9.455 -you might have installed on your system or network. It cannot detect 9.456 -or control your firewall software. If other people are unable to talk 9.457 -to a running <command role="hg-cmd">hg serve</command> instance, the second thing you should do 9.458 -(<emphasis>after</emphasis> you make sure that they're using the correct URL) is 9.459 -check your firewall configuration. 9.460 -</para> 9.461 - 9.462 -<para>By default, <command role="hg-cmd">hg serve</command> listens for incoming connections on 9.463 -port 8000. If another process is already listening on the port you 9.464 -want to use, you can specify a different port to listen on using the 9.465 -<option role="hg-opt-serve">-p</option> option. 9.466 -</para> 9.467 - 9.468 -<para>Normally, when <command role="hg-cmd">hg serve</command> starts, it prints no output, which can be 9.469 -a bit unnerving. If you'd like to confirm that it is indeed running 9.470 -correctly, and find out what URL you should send to your 9.471 -collaborators, start it with the <option role="hg-opt-global">-v</option> option. 9.472 -</para> 9.473 - 9.474 -</sect2> 9.475 -</sect1> 9.476 -<sect1> 9.477 -<title>Using the Secure Shell (ssh) protocol</title> 9.478 -<para>\label{sec:collab:ssh} 9.479 -</para> 9.480 - 9.481 -<para>You can pull and push changes securely over a network connection using 9.482 -the Secure Shell (<literal>ssh</literal>) protocol. To use this successfully, 9.483 -you may have to do a little bit of configuration on the client or 9.484 -server sides. 9.485 -</para> 9.486 - 9.487 -<para>If you're not familiar with ssh, it's a network protocol that lets you 9.488 -securely communicate with another computer. To use it with Mercurial, 9.489 -you'll be setting up one or more user accounts on a server so that 9.490 -remote users can log in and execute commands. 9.491 -</para> 9.492 - 9.493 -<para>(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some of the 9.494 -material that follows to be elementary in nature.) 9.495 -</para> 9.496 - 9.497 -<sect2> 9.498 -<title>How to read and write ssh URLs</title> 9.499 - 9.500 -<para>An ssh URL tends to look like this: 9.501 -</para> 9.502 -<programlisting> 9.503 -<para> ssh://bos@hg.serpentine.com:22/hg/hgbook 9.504 -</para> 9.505 +<chapter id="cha:collab"> 9.506 + <?dbhtml filename="collaborating-with-other-people.html"?> 9.507 + <title>Collaborating with other people</title> 9.508 + 9.509 + <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 9.510 + any policy on how people ought to work with each other. However, 9.511 + if you're new to distributed revision control, it helps to have 9.512 + some tools and examples in mind when you're thinking about 9.513 + possible workflow models.</para> 9.514 + 9.515 + <sect1> 9.516 + <title>Mercurial's web interface</title> 9.517 + 9.518 + <para id="x_44b">Mercurial has a powerful web interface that provides several 9.519 + useful capabilities.</para> 9.520 + 9.521 + <para id="x_44c">For interactive use, the web interface lets you browse a 9.522 + single repository or a collection of repositories. You can view 9.523 + the history of a repository, examine each change (comments and 9.524 + diffs), and view the contents of each directory and file. You 9.525 + can even get a view of history that gives a graphical view of 9.526 + the relationships between individual changes and merges.</para> 9.527 + 9.528 + <para id="x_44d">Also for human consumption, the web interface provides 9.529 + Atom and RSS feeds of the changes in a repository. This lets you 9.530 + <quote>subscribe</quote> to a repository using your favorite 9.531 + feed reader, and be automatically notified of activity in that 9.532 + repository as soon as it happens. I find this capability much 9.533 + more convenient than the model of subscribing to a mailing list 9.534 + to which notifications are sent, as it requires no additional 9.535 + configuration on the part of whoever is serving the 9.536 + repository.</para> 9.537 + 9.538 + <para id="x_44e">The web interface also lets remote users clone a repository, 9.539 + pull changes from it, and (when the server is configured to 9.540 + permit it) push changes back to it. Mercurial's HTTP tunneling 9.541 + protocol aggressively compresses data, so that it works 9.542 + efficiently even over low-bandwidth network connections.</para> 9.543 + 9.544 + <para id="x_44f">The easiest way to get started with the web interface is to 9.545 + use your web browser to visit an existing repository, such as 9.546 + the master Mercurial repository at <ulink 9.547 + url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para> 9.548 + 9.549 + <para id="x_450">If you're interested in providing a web interface 9.550 + to your own repositories, there are several good ways to do 9.551 + this.</para> 9.552 + 9.553 + <para id="x_69d">The easiest and fastest way to get started in an informal 9.554 + environment is to use the <command role="hg-cmd">hg 9.555 + serve</command> command, which is best suited to short-term 9.556 + <quote>lightweight</quote> serving. See <xref 9.557 + linkend="sec:collab:serve"/> below for details of how to use 9.558 + this command.</para> 9.559 + 9.560 + <para id="x_69e">For longer-lived repositories that you'd like to 9.561 + have permanently available, there are several public hosting 9.562 + services available. Some are free to open source projects, 9.563 + while others offer paid commercial hosting. An up-to-date list 9.564 + is available at <ulink 9.565 + url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para> 9.566 + 9.567 + <para id="x_6a0">If you would prefer to host your own repositories, Mercurial 9.568 + has built-in support for several popular hosting technologies, 9.569 + most notably CGI (Common Gateway Interface), and WSGI (Web 9.570 + Services Gateway Interface). See <xref 9.571 + linkend="sec:collab:cgi"/> for details of CGI and WSGI 9.572 + configuration.</para> 9.573 + </sect1> 9.574 + 9.575 + <sect1> 9.576 + <title>Collaboration models</title> 9.577 + 9.578 + <para id="x_451">With a suitably flexible tool, making decisions about 9.579 + workflow is much more of a social engineering challenge than a 9.580 + technical one. Mercurial imposes few limitations on how you can 9.581 + structure the flow of work in a project, so it's up to you and 9.582 + your group to set up and live with a model that matches your own 9.583 + particular needs.</para> 9.584 + 9.585 + <sect2> 9.586 + <title>Factors to keep in mind</title> 9.587 + 9.588 + <para id="x_452">The most important aspect of any model that you must keep 9.589 + in mind is how well it matches the needs and capabilities of 9.590 + the people who will be using it. This might seem 9.591 + self-evident; even so, you still can't afford to forget it for 9.592 + a moment.</para> 9.593 + 9.594 + <para id="x_453">I once put together a workflow model that seemed to make 9.595 + perfect sense to me, but that caused a considerable amount of 9.596 + consternation and strife within my development team. In spite 9.597 + of my attempts to explain why we needed a complex set of 9.598 + branches, and how changes ought to flow between them, a few 9.599 + team members revolted. Even though they were smart people, 9.600 + they didn't want to pay attention to the constraints we were 9.601 + operating under, or face the consequences of those constraints 9.602 + in the details of the model that I was advocating.</para> 9.603 + 9.604 + <para id="x_454">Don't sweep foreseeable social or technical problems under 9.605 + the rug. Whatever scheme you put into effect, you should plan 9.606 + for mistakes and problem scenarios. Consider adding automated 9.607 + machinery to prevent, or quickly recover from, trouble that 9.608 + you can anticipate. As an example, if you intend to have a 9.609 + branch with not-for-release changes in it, you'd do well to 9.610 + think early about the possibility that someone might 9.611 + accidentally merge those changes into a release branch. You 9.612 + could avoid this particular problem by writing a hook that 9.613 + prevents changes from being merged from an inappropriate 9.614 + branch.</para> 9.615 + </sect2> 9.616 + 9.617 + <sect2> 9.618 + <title>Informal anarchy</title> 9.619 + 9.620 + <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 9.621 + approach as something sustainable, but it's a model that's 9.622 + easy to grasp, and it works perfectly well in a few unusual 9.623 + situations.</para> 9.624 + 9.625 + <para id="x_456">As one example, many projects have a loose-knit group of 9.626 + collaborators who rarely physically meet each other. Some 9.627 + groups like to overcome the isolation of working at a distance 9.628 + by organizing occasional <quote>sprints</quote>. In a sprint, 9.629 + a number of people get together in a single location (a 9.630 + company's conference room, a hotel meeting room, that kind of 9.631 + place) and spend several days more or less locked in there, 9.632 + hacking intensely on a handful of projects.</para> 9.633 + 9.634 + <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the 9.635 + <command role="hg-cmd">hg serve</command> command, since 9.636 + <command role="hg-cmd">hg serve</command> does not require any 9.637 + fancy server infrastructure. You can get started with 9.638 + <command role="hg-cmd">hg serve</command> in moments, by 9.639 + reading <xref linkend="sec:collab:serve"/> below. Then simply 9.640 + tell the person next to you that you're running a server, send 9.641 + the URL to them in an instant message, and you immediately 9.642 + have a quick-turnaround way to work together. They can type 9.643 + your URL into their web browser and quickly review your 9.644 + changes; or they can pull a bugfix from you and verify it; or 9.645 + they can clone a branch containing a new feature and try it 9.646 + out.</para> 9.647 + 9.648 + <para id="x_458">The charm, and the problem, with doing things 9.649 + in an ad hoc fashion like this is that only people who know 9.650 + about your changes, and where they are, can see them. Such an 9.651 + informal approach simply doesn't scale beyond a handful 9.652 + people, because each individual needs to know about 9.653 + <emphasis>n</emphasis> different repositories to pull 9.654 + from.</para> 9.655 + </sect2> 9.656 + 9.657 + <sect2> 9.658 + <title>A single central repository</title> 9.659 + 9.660 + <para id="x_459">For smaller projects migrating from a centralised revision 9.661 + control tool, perhaps the easiest way to get started is to 9.662 + have changes flow through a single shared central repository. 9.663 + This is also the most common <quote>building block</quote> for 9.664 + more ambitious workflow schemes.</para> 9.665 + 9.666 + <para id="x_45a">Contributors start by cloning a copy of this repository. 9.667 + They can pull changes from it whenever they need to, and some 9.668 + (perhaps all) developers have permission to push a change back 9.669 + when they're ready for other people to see it.</para> 9.670 + 9.671 + <para id="x_45b">Under this model, it can still often make sense for people 9.672 + to pull changes directly from each other, without going 9.673 + through the central repository. Consider a case in which I 9.674 + have a tentative bug fix, but I am worried that if I were to 9.675 + publish it to the central repository, it might subsequently 9.676 + break everyone else's trees as they pull it. To reduce the 9.677 + potential for damage, I can ask you to clone my repository 9.678 + into a temporary repository of your own and test it. This 9.679 + lets us put off publishing the potentially unsafe change until 9.680 + it has had a little testing.</para> 9.681 + 9.682 + <para id="x_45c">If a team is hosting its own repository in this 9.683 + kind of scenario, people will usually use the 9.684 + <command>ssh</command> protocol to securely push changes to 9.685 + the central repository, as documented in <xref 9.686 + linkend="sec:collab:ssh"/>. It's also usual to publish a 9.687 + read-only copy of the repository over HTTP, as in 9.688 + <xref linkend="sec:collab:cgi"/>. Publishing over HTTP 9.689 + satisfies the needs of people who don't have push access, and 9.690 + those who want to use web browsers to browse the repository's 9.691 + history.</para> 9.692 + </sect2> 9.693 + 9.694 + <sect2> 9.695 + <title>A hosted central repository</title> 9.696 + 9.697 + <para id="x_6a1">A wonderful thing about public hosting services like 9.698 + <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that 9.699 + not only do they handle the fiddly server configuration 9.700 + details, such as user accounts, authentication, and secure 9.701 + wire protocols, they provide additional infrastructure to make 9.702 + this model work well.</para> 9.703 + 9.704 + <para id="x_6a2">For instance, a well-engineered hosting service will let 9.705 + people clone their own copies of a repository with a single 9.706 + click. This lets people work in separate spaces and share 9.707 + their changes when they're ready.</para> 9.708 + 9.709 + <para id="x_6a3">In addition, a good hosting service will let people 9.710 + communicate with each other, for instance to say <quote>there 9.711 + are changes ready for you to review in this 9.712 + tree</quote>.</para> 9.713 + </sect2> 9.714 + 9.715 + <sect2> 9.716 + <title>Working with multiple branches</title> 9.717 + 9.718 + <para id="x_45d">Projects of any significant size naturally tend to make 9.719 + progress on several fronts simultaneously. In the case of 9.720 + software, it's common for a project to go through periodic 9.721 + official releases. A release might then go into 9.722 + <quote>maintenance mode</quote> for a while after its first 9.723 + publication; maintenance releases tend to contain only bug 9.724 + fixes, not new features. In parallel with these maintenance 9.725 + releases, one or more future releases may be under 9.726 + development. People normally use the word 9.727 + <quote>branch</quote> to refer to one of these many slightly 9.728 + different directions in which development is 9.729 + proceeding.</para> 9.730 + 9.731 + <para id="x_45e">Mercurial is particularly well suited to managing a number 9.732 + of simultaneous, but not identical, branches. Each 9.733 + <quote>development direction</quote> can live in its own 9.734 + central repository, and you can merge changes from one to 9.735 + another as the need arises. Because repositories are 9.736 + independent of each other, unstable changes in a development 9.737 + branch will never affect a stable branch unless someone 9.738 + explicitly merges those changes into the stable branch.</para> 9.739 + 9.740 + <para id="x_45f">Here's an example of how this can work in practice. Let's 9.741 + say you have one <quote>main branch</quote> on a central 9.742 + server.</para> 9.743 + 9.744 + &interaction.branching.init; 9.745 + 9.746 + <para id="x_460">People clone it, make changes locally, test them, and push 9.747 + them back.</para> 9.748 + 9.749 + <para id="x_461">Once the main branch reaches a release milestone, you can 9.750 + use the <command role="hg-cmd">hg tag</command> command to 9.751 + give a permanent name to the milestone revision.</para> 9.752 + 9.753 + &interaction.branching.tag; 9.754 + 9.755 + <para id="x_462">Let's say some ongoing 9.756 + development occurs on the main branch.</para> 9.757 + 9.758 + &interaction.branching.main; 9.759 + 9.760 + <para id="x_463">Using the tag that was recorded at the milestone, people 9.761 + who clone that repository at any time in the future can use 9.762 + <command role="hg-cmd">hg update</command> to get a copy of 9.763 + the working directory exactly as it was when that tagged 9.764 + revision was committed.</para> 9.765 + 9.766 + &interaction.branching.update; 9.767 + 9.768 + <para id="x_464">In addition, immediately after the main branch is tagged, 9.769 + we can then clone the main branch on the server to a new 9.770 + <quote>stable</quote> branch, also on the server.</para> 9.771 + 9.772 + &interaction.branching.clone; 9.773 + 9.774 + <para id="x_465">If we need to make a change to the stable 9.775 + branch, we can then clone <emphasis>that</emphasis> 9.776 + repository, make our changes, commit, and push our changes 9.777 + back there.</para> 9.778 + 9.779 + &interaction.branching.stable; 9.780 + 9.781 + <para id="x_466">Because Mercurial repositories are independent, and 9.782 + Mercurial doesn't move changes around automatically, the 9.783 + stable and main branches are <emphasis>isolated</emphasis> 9.784 + from each other. The changes that we made on the main branch 9.785 + don't <quote>leak</quote> to the stable branch, and vice 9.786 + versa.</para> 9.787 + 9.788 + <para id="x_467">We'll often want all of our bugfixes on the stable 9.789 + branch to show up on the main branch, too. Rather than 9.790 + rewrite a bugfix on the main branch, we can simply pull and 9.791 + merge changes from the stable to the main branch, and 9.792 + Mercurial will bring those bugfixes in for us.</para> 9.793 + 9.794 + &interaction.branching.merge; 9.795 + 9.796 + <para id="x_468">The main branch will still contain changes that 9.797 + are not on the stable branch, but it will also contain all of 9.798 + the bugfixes from the stable branch. The stable branch 9.799 + remains unaffected by these changes, since changes are only 9.800 + flowing from the stable to the main branch, and not the other 9.801 + way.</para> 9.802 + </sect2> 9.803 + 9.804 + <sect2> 9.805 + <title>Feature branches</title> 9.806 + 9.807 + <para id="x_469">For larger projects, an effective way to manage change is 9.808 + to break up a team into smaller groups. Each group has a 9.809 + shared branch of its own, cloned from a single 9.810 + <quote>master</quote> branch used by the entire project. 9.811 + People working on an individual branch are typically quite 9.812 + isolated from developments on other branches.</para> 9.813 + 9.814 + <figure id="fig:collab:feature-branches"> 9.815 + <title>Feature branches</title> 9.816 + <mediaobject> 9.817 + <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject> 9.818 + <textobject><phrase>XXX add text</phrase></textobject> 9.819 + </mediaobject> 9.820 + </figure> 9.821 + 9.822 + <para id="x_46b">When a particular feature is deemed to be in suitable 9.823 + shape, someone on that feature team pulls and merges from the 9.824 + master branch into the feature branch, then pushes back up to 9.825 + the master branch.</para> 9.826 + </sect2> 9.827 + 9.828 + <sect2> 9.829 + <title>The release train</title> 9.830 + 9.831 + <para id="x_46c">Some projects are organized on a <quote>train</quote> 9.832 + basis: a release is scheduled to happen every few months, and 9.833 + whatever features are ready when the <quote>train</quote> is 9.834 + ready to leave are allowed in.</para> 9.835 + 9.836 + <para id="x_46d">This model resembles working with feature branches. The 9.837 + difference is that when a feature branch misses a train, 9.838 + someone on the feature team pulls and merges the changes that 9.839 + went out on that train release into the feature branch, and 9.840 + the team continues its work on top of that release so that 9.841 + their feature can make the next release.</para> 9.842 + </sect2> 9.843 + 9.844 + <sect2> 9.845 + <title>The Linux kernel model</title> 9.846 + 9.847 + <para id="x_46e">The development of the Linux kernel has a shallow 9.848 + hierarchical structure, surrounded by a cloud of apparent 9.849 + chaos. Because most Linux developers use 9.850 + <command>git</command>, a distributed revision control tool 9.851 + with capabilities similar to Mercurial, it's useful to 9.852 + describe the way work flows in that environment; if you like 9.853 + the ideas, the approach translates well across tools.</para> 9.854 + 9.855 + <para id="x_46f">At the center of the community sits Linus Torvalds, the 9.856 + creator of Linux. He publishes a single source repository 9.857 + that is considered the <quote>authoritative</quote> current 9.858 + tree by the entire developer community. Anyone can clone 9.859 + Linus's tree, but he is very choosy about whose trees he pulls 9.860 + from.</para> 9.861 + 9.862 + <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 9.863 + As a general rule, he pulls whatever changes they publish, in 9.864 + most cases without even reviewing those changes. Some of 9.865 + those lieutenants are generally agreed to be 9.866 + <quote>maintainers</quote>, responsible for specific 9.867 + subsystems within the kernel. If a random kernel hacker wants 9.868 + to make a change to a subsystem that they want to end up in 9.869 + Linus's tree, they must find out who the subsystem's 9.870 + maintainer is, and ask that maintainer to take their change. 9.871 + If the maintainer reviews their changes and agrees to take 9.872 + them, they'll pass them along to Linus in due course.</para> 9.873 + 9.874 + <para id="x_471">Individual lieutenants have their own approaches to 9.875 + reviewing, accepting, and publishing changes; and for deciding 9.876 + when to feed them to Linus. In addition, there are several 9.877 + well known branches that people use for different purposes. 9.878 + For example, a few people maintain <quote>stable</quote> 9.879 + repositories of older versions of the kernel, to which they 9.880 + apply critical fixes as needed. Some maintainers publish 9.881 + multiple trees: one for experimental changes; one for changes 9.882 + that they are about to feed upstream; and so on. Others just 9.883 + publish a single tree.</para> 9.884 + 9.885 + <para id="x_472">This model has two notable features. The first is that 9.886 + it's <quote>pull only</quote>. You have to ask, convince, or 9.887 + beg another developer to take a change from you, because there 9.888 + are almost no trees to which more than one person can push, 9.889 + and there's no way to push changes into a tree that someone 9.890 + else controls.</para> 9.891 + 9.892 + <para id="x_473">The second is that it's based on reputation and acclaim. 9.893 + If you're an unknown, Linus will probably ignore changes from 9.894 + you without even responding. But a subsystem maintainer will 9.895 + probably review them, and will likely take them if they pass 9.896 + their criteria for suitability. The more <quote>good</quote> 9.897 + changes you contribute to a maintainer, the more likely they 9.898 + are to trust your judgment and accept your changes. If you're 9.899 + well-known and maintain a long-lived branch for something 9.900 + Linus hasn't yet accepted, people with similar interests may 9.901 + pull your changes regularly to keep up with your work.</para> 9.902 + 9.903 + <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 9.904 + or <quote>people</quote> boundaries. If you're a respected 9.905 + but specialised storage hacker, and you try to fix a 9.906 + networking bug, that change will receive a level of scrutiny 9.907 + from a network maintainer comparable to a change from a 9.908 + complete stranger.</para> 9.909 + 9.910 + <para id="x_475">To people who come from more orderly project backgrounds, 9.911 + the comparatively chaotic Linux kernel development process 9.912 + often seems completely insane. It's subject to the whims of 9.913 + individuals; people make sweeping changes whenever they deem 9.914 + it appropriate; and the pace of development is astounding. 9.915 + And yet Linux is a highly successful, well-regarded piece of 9.916 + software.</para> 9.917 + </sect2> 9.918 + 9.919 + <sect2> 9.920 + <title>Pull-only versus shared-push collaboration</title> 9.921 + 9.922 + <para id="x_476">A perpetual source of heat in the open source community is 9.923 + whether a development model in which people only ever pull 9.924 + changes from others is <quote>better than</quote> one in which 9.925 + multiple people can push changes to a shared 9.926 + repository.</para> 9.927 + 9.928 + <para id="x_477">Typically, the backers of the shared-push model use tools 9.929 + that actively enforce this approach. If you're using a 9.930 + centralised revision control tool such as Subversion, there's 9.931 + no way to make a choice over which model you'll use: the tool 9.932 + gives you shared-push, and if you want to do anything else, 9.933 + you'll have to roll your own approach on top (such as applying 9.934 + a patch by hand).</para> 9.935 + 9.936 + <para id="x_478">A good distributed revision control tool will 9.937 + support both models. You and your collaborators can then 9.938 + structure how you work together based on your own needs and 9.939 + preferences, not on what contortions your tools force you 9.940 + into.</para> 9.941 + </sect2> 9.942 + <sect2> 9.943 + <title>Where collaboration meets branch management</title> 9.944 + 9.945 + <para id="x_479">Once you and your team set up some shared 9.946 + repositories and start propagating changes back and forth 9.947 + between local and shared repos, you begin to face a related, 9.948 + but slightly different challenge: that of managing the 9.949 + multiple directions in which your team may be moving at once. 9.950 + Even though this subject is intimately related to how your 9.951 + team collaborates, it's dense enough to merit treatment of its 9.952 + own, in <xref linkend="chap:branch"/>.</para> 9.953 + </sect2> 9.954 + </sect1> 9.955 + 9.956 + <sect1> 9.957 + <title>The technical side of sharing</title> 9.958 + 9.959 + <para id="x_47a">The remainder of this chapter is devoted to the question of 9.960 + sharing changes with your collaborators.</para> 9.961 + </sect1> 9.962 + 9.963 + <sect1 id="sec:collab:serve"> 9.964 + <title>Informal sharing with <command role="hg-cmd">hg 9.965 + serve</command></title> 9.966 + 9.967 + <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 9.968 + command is wonderfully suited to small, tight-knit, and 9.969 + fast-paced group environments. It also provides a great way to 9.970 + get a feel for using Mercurial commands over a network.</para> 9.971 + 9.972 + <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 9.973 + repository, and in under a second it will bring up a specialised 9.974 + HTTP server; this will accept connections from any client, and 9.975 + serve up data for that repository until you terminate it. 9.976 + Anyone who knows the URL of the server you just started, and can 9.977 + talk to your computer over the network, can then use a web 9.978 + browser or Mercurial to read data from that repository. A URL 9.979 + for a <command role="hg-cmd">hg serve</command> instance running 9.980 + on a laptop is likely to look something like 9.981 + <literal>http://my-laptop.local:8000/</literal>.</para> 9.982 + 9.983 + <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 9.984 + <emphasis>not</emphasis> a general-purpose web server. It can do 9.985 + only two things:</para> 9.986 + <itemizedlist> 9.987 + <listitem><para id="x_47e">Allow people to browse the history of the 9.988 + repository it's serving, from their normal web 9.989 + browsers.</para> 9.990 + </listitem> 9.991 + <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 9.992 + can <command role="hg-cmd">hg clone</command> or <command 9.993 + role="hg-cmd">hg pull</command> changes from that 9.994 + repository.</para> 9.995 + </listitem></itemizedlist> 9.996 + <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 9.997 + won't allow remote users to <emphasis>modify</emphasis> your 9.998 + repository. It's intended for read-only use.</para> 9.999 + 9.1000 + <para id="x_481">If you're getting started with Mercurial, there's nothing to 9.1001 + prevent you from using <command role="hg-cmd">hg serve</command> 9.1002 + to serve up a repository on your own computer, then use commands 9.1003 + like <command role="hg-cmd">hg clone</command>, <command 9.1004 + role="hg-cmd">hg incoming</command>, and so on to talk to that 9.1005 + server as if the repository was hosted remotely. This can help 9.1006 + you to quickly get acquainted with using commands on 9.1007 + network-hosted repositories.</para> 9.1008 + 9.1009 + <sect2> 9.1010 + <title>A few things to keep in mind</title> 9.1011 + 9.1012 + <para id="x_482">Because it provides unauthenticated read access to all 9.1013 + clients, you should only use <command role="hg-cmd">hg 9.1014 + serve</command> in an environment where you either don't 9.1015 + care, or have complete control over, who can access your 9.1016 + network and pull data from your repository.</para> 9.1017 + 9.1018 + <para id="x_483">The <command role="hg-cmd">hg serve</command> command 9.1019 + knows nothing about any firewall software you might have 9.1020 + installed on your system or network. It cannot detect or 9.1021 + control your firewall software. If other people are unable to 9.1022 + talk to a running <command role="hg-cmd">hg serve</command> 9.1023 + instance, the second thing you should do 9.1024 + (<emphasis>after</emphasis> you make sure that they're using 9.1025 + the correct URL) is check your firewall configuration.</para> 9.1026 + 9.1027 + <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 9.1028 + listens for incoming connections on port 8000. If another 9.1029 + process is already listening on the port you want to use, you 9.1030 + can specify a different port to listen on using the <option 9.1031 + role="hg-opt-serve">-p</option> option.</para> 9.1032 + 9.1033 + <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 9.1034 + starts, it prints no output, which can be a bit unnerving. If 9.1035 + you'd like to confirm that it is indeed running correctly, and 9.1036 + find out what URL you should send to your collaborators, start 9.1037 + it with the <option role="hg-opt-global">-v</option> 9.1038 + option.</para> 9.1039 + </sect2> 9.1040 + </sect1> 9.1041 + 9.1042 + <sect1 id="sec:collab:ssh"> 9.1043 + <title>Using the Secure Shell (ssh) protocol</title> 9.1044 + 9.1045 + <para id="x_486">You can pull and push changes securely over a network 9.1046 + connection using the Secure Shell (<literal>ssh</literal>) 9.1047 + protocol. To use this successfully, you may have to do a little 9.1048 + bit of configuration on the client or server sides.</para> 9.1049 + 9.1050 + <para id="x_487">If you're not familiar with ssh, it's the name of 9.1051 + both a command and a network protocol that let you securely 9.1052 + communicate with another computer. To use it with Mercurial, 9.1053 + you'll be setting up one or more user accounts on a server so 9.1054 + that remote users can log in and execute commands.</para> 9.1055 + 9.1056 + <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 9.1057 + probably find some of the material that follows to be elementary 9.1058 + in nature.)</para> 9.1059 + 9.1060 + <sect2> 9.1061 + <title>How to read and write ssh URLs</title> 9.1062 + 9.1063 + <para id="x_489">An ssh URL tends to look like this:</para> 9.1064 + <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 9.1065 + <orderedlist> 9.1066 + <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 9.1067 + part tells Mercurial to use the ssh protocol.</para> 9.1068 + </listitem> 9.1069 + <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 9.1070 + component indicates what username to log into the server 9.1071 + as. You can leave this out if the remote username is the 9.1072 + same as your local username.</para> 9.1073 + </listitem> 9.1074 + <listitem><para id="x_48c">The 9.1075 + <quote><literal>hg.serpentine.com</literal></quote> gives 9.1076 + the hostname of the server to log into.</para> 9.1077 + </listitem> 9.1078 + <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 9.1079 + number to connect to the server on. The default port is 9.1080 + 22, so you only need to specify a colon and port number if 9.1081 + you're <emphasis>not</emphasis> using port 22.</para> 9.1082 + </listitem> 9.1083 + <listitem><para id="x_48e">The remainder of the URL is the local path to 9.1084 + the repository on the server.</para> 9.1085 + </listitem></orderedlist> 9.1086 + 9.1087 + <para id="x_48f">There's plenty of scope for confusion with the path 9.1088 + component of ssh URLs, as there is no standard way for tools 9.1089 + to interpret it. Some programs behave differently than others 9.1090 + when dealing with these paths. This isn't an ideal situation, 9.1091 + but it's unlikely to change. Please read the following 9.1092 + paragraphs carefully.</para> 9.1093 + 9.1094 + <para id="x_490">Mercurial treats the path to a repository on the server as 9.1095 + relative to the remote user's home directory. For example, if 9.1096 + user <literal>foo</literal> on the server has a home directory 9.1097 + of <filename class="directory">/home/foo</filename>, then an 9.1098 + ssh URL that contains a path component of <filename 9.1099 + class="directory">bar</filename> <emphasis>really</emphasis> 9.1100 + refers to the directory <filename 9.1101 + class="directory">/home/foo/bar</filename>.</para> 9.1102 + 9.1103 + <para id="x_491">If you want to specify a path relative to another user's 9.1104 + home directory, you can use a path that starts with a tilde 9.1105 + character followed by the user's name (let's call them 9.1106 + <literal>otheruser</literal>), like this.</para> 9.1107 + <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 9.1108 + 9.1109 + <para id="x_492">And if you really want to specify an 9.1110 + <emphasis>absolute</emphasis> path on the server, begin the 9.1111 + path component with two slashes, as in this example.</para> 9.1112 + <programlisting>ssh://server//absolute/path</programlisting> 9.1113 + </sect2> 9.1114 + 9.1115 + <sect2> 9.1116 + <title>Finding an ssh client for your system</title> 9.1117 + 9.1118 + <para id="x_493">Almost every Unix-like system comes with OpenSSH 9.1119 + preinstalled. If you're using such a system, run 9.1120 + <literal>which ssh</literal> to find out if the 9.1121 + <command>ssh</command> command is installed (it's usually in 9.1122 + <filename class="directory">/usr/bin</filename>). In the 9.1123 + unlikely event that it isn't present, take a look at your 9.1124 + system documentation to figure out how to install it.</para> 9.1125 + 9.1126 + <para id="x_494">On Windows, the TortoiseHg package is bundled 9.1127 + with a version of Simon Tatham's excellent 9.1128 + <command>plink</command> command, and you should not need to 9.1129 + do any further configuration.</para> 9.1130 + </sect2> 9.1131 + 9.1132 + <sect2> 9.1133 + <title>Generating a key pair</title> 9.1134 + 9.1135 + <para id="x_499">To avoid the need to repetitively type a 9.1136 + password every time you need to use your ssh client, I 9.1137 + recommend generating a key pair.</para> 9.1138 + 9.1139 + <tip> 9.1140 + <title>Key pairs are not mandatory</title> 9.1141 + 9.1142 + <para id="x_6a4">Mercurial knows nothing about ssh authentication or key 9.1143 + pairs. You can, if you like, safely ignore this section and 9.1144 + the one that follows until you grow tired of repeatedly 9.1145 + typing ssh passwords.</para> 9.1146 + </tip> 9.1147 + 9.1148 + <itemizedlist> 9.1149 + <listitem> 9.1150 + <para id="x_6a5">On a Unix-like system, the 9.1151 + <command>ssh-keygen</command> command will do the 9.1152 + trick.</para> 9.1153 + <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need 9.1154 + to download a command named <command>puttygen</command> 9.1155 + from <ulink 9.1156 + url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 9.1157 + PuTTY web site</ulink> to generate a key pair. See 9.1158 + <ulink 9.1159 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 9.1160 + <command>puttygen</command> documentation</ulink> for 9.1161 + details of how use the command.</para> 9.1162 + </listitem> 9.1163 + </itemizedlist> 9.1164 + 9.1165 + <para id="x_49a">When you generate a key pair, it's usually 9.1166 + <emphasis>highly</emphasis> advisable to protect it with a 9.1167 + passphrase. (The only time that you might not want to do this 9.1168 + is when you're using the ssh protocol for automated tasks on a 9.1169 + secure network.)</para> 9.1170 + 9.1171 + <para id="x_49b">Simply generating a key pair isn't enough, however. 9.1172 + You'll need to add the public key to the set of authorised 9.1173 + keys for whatever user you're logging in remotely as. For 9.1174 + servers using OpenSSH (the vast majority), this will mean 9.1175 + adding the public key to a list in a file called <filename 9.1176 + role="special">authorized_keys</filename> in their <filename 9.1177 + role="special" class="directory">.ssh</filename> 9.1178 + directory.</para> 9.1179 + 9.1180 + <para id="x_49c">On a Unix-like system, your public key will have a 9.1181 + <filename>.pub</filename> extension. If you're using 9.1182 + <command>puttygen</command> on Windows, you can save the 9.1183 + public key to a file of your choosing, or paste it from the 9.1184 + window it's displayed in straight into the <filename 9.1185 + role="special">authorized_keys</filename> file.</para> 9.1186 + </sect2> 9.1187 + <sect2> 9.1188 + <title>Using an authentication agent</title> 9.1189 + 9.1190 + <para id="x_49d">An authentication agent is a daemon that stores 9.1191 + passphrases in memory (so it will forget passphrases if you 9.1192 + log out and log back in again). An ssh client will notice if 9.1193 + it's running, and query it for a passphrase. If there's no 9.1194 + authentication agent running, or the agent doesn't store the 9.1195 + necessary passphrase, you'll have to type your passphrase 9.1196 + every time Mercurial tries to communicate with a server on 9.1197 + your behalf (e.g. whenever you pull or push changes).</para> 9.1198 + 9.1199 + <para id="x_49e">The downside of storing passphrases in an agent is that 9.1200 + it's possible for a well-prepared attacker to recover the 9.1201 + plain text of your passphrases, in some cases even if your 9.1202 + system has been power-cycled. You should make your own 9.1203 + judgment as to whether this is an acceptable risk. It 9.1204 + certainly saves a lot of repeated typing.</para> 9.1205 + 9.1206 + <itemizedlist> 9.1207 + <listitem> 9.1208 + <para id="x_49f">On Unix-like systems, the agent is called 9.1209 + <command>ssh-agent</command>, and it's often run 9.1210 + automatically for you when you log in. You'll need to use 9.1211 + the <command>ssh-add</command> command to add passphrases 9.1212 + to the agent's store.</para> 9.1213 + </listitem> 9.1214 + <listitem> 9.1215 + <para id="x_6a7">On Windows, if you're using TortoiseHg, the 9.1216 + <command>pageant</command> command acts as the agent. As 9.1217 + with <command>puttygen</command>, you'll need to <ulink 9.1218 + url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 9.1219 + <command>pageant</command></ulink> from the PuTTY web 9.1220 + site and read <ulink 9.1221 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 9.1222 + documentation</ulink>. The <command>pageant</command> 9.1223 + command adds an icon to your system tray that will let you 9.1224 + manage stored passphrases.</para> 9.1225 + </listitem> 9.1226 + </itemizedlist> 9.1227 + </sect2> 9.1228 + 9.1229 + <sect2> 9.1230 + <title>Configuring the server side properly</title> 9.1231 + 9.1232 + <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 9.1233 + a variety of things can go wrong. Add Mercurial 9.1234 + on top, and there's plenty more scope for head-scratching. 9.1235 + Most of these potential problems occur on the server side, not 9.1236 + the client side. The good news is that once you've gotten a 9.1237 + configuration working, it will usually continue to work 9.1238 + indefinitely.</para> 9.1239 + 9.1240 + <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 9.1241 + it's best to make sure that you can use the normal 9.1242 + <command>ssh</command> or <command>putty</command> command to 9.1243 + talk to the server first. If you run into problems with using 9.1244 + these commands directly, Mercurial surely won't work. Worse, 9.1245 + it will obscure the underlying problem. Any time you want to 9.1246 + debug ssh-related Mercurial problems, you should drop back to 9.1247 + making sure that plain ssh client commands work first, 9.1248 + <emphasis>before</emphasis> you worry about whether there's a 9.1249 + problem with Mercurial.</para> 9.1250 + 9.1251 + <para id="x_4a2">The first thing to be sure of on the server side is that 9.1252 + you can actually log in from another machine at all. If you 9.1253 + can't use <command>ssh</command> or <command>putty</command> 9.1254 + to log in, the error message you get may give you a few hints 9.1255 + as to what's wrong. The most common problems are as 9.1256 + follows.</para> 9.1257 + <itemizedlist> 9.1258 + <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 9.1259 + error, either there isn't an SSH daemon running on the 9.1260 + server at all, or it's inaccessible due to firewall 9.1261 + configuration.</para> 9.1262 + </listitem> 9.1263 + <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 9.1264 + error, you either have an incorrect address for the server 9.1265 + or a seriously locked down firewall that won't admit its 9.1266 + existence at all.</para> 9.1267 + </listitem> 9.1268 + <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 9.1269 + error, you may have mistyped the username on the server, 9.1270 + or you could have mistyped your key's passphrase or the 9.1271 + remote user's password.</para> 9.1272 + </listitem></itemizedlist> 9.1273 + <para id="x_4a6">In summary, if you're having trouble talking to the 9.1274 + server's ssh daemon, first make sure that one is running at 9.1275 + all. On many systems it will be installed, but disabled, by 9.1276 + default. Once you're done with this step, you should then 9.1277 + check that the server's firewall is configured to allow 9.1278 + incoming connections on the port the ssh daemon is listening 9.1279 + on (usually 22). Don't worry about more exotic possibilities 9.1280 + for misconfiguration until you've checked these two 9.1281 + first.</para> 9.1282 + 9.1283 + <para id="x_4a7">If you're using an authentication agent on the client side 9.1284 + to store passphrases for your keys, you ought to be able to 9.1285 + log into the server without being prompted for a passphrase or 9.1286 + a password. If you're prompted for a passphrase, there are a 9.1287 + few possible culprits.</para> 9.1288 + <itemizedlist> 9.1289 + <listitem><para id="x_4a8">You might have forgotten to use 9.1290 + <command>ssh-add</command> or <command>pageant</command> 9.1291 + to store the passphrase.</para> 9.1292 + </listitem> 9.1293 + <listitem><para id="x_4a9">You might have stored the passphrase for the 9.1294 + wrong key.</para> 9.1295 + </listitem></itemizedlist> 9.1296 + <para id="x_4aa">If you're being prompted for the remote user's password, 9.1297 + there are another few possible problems to check.</para> 9.1298 + <itemizedlist> 9.1299 + <listitem><para id="x_4ab">Either the user's home directory or their 9.1300 + <filename role="special" class="directory">.ssh</filename> 9.1301 + directory might have excessively liberal permissions. As 9.1302 + a result, the ssh daemon will not trust or read their 9.1303 + <filename role="special">authorized_keys</filename> file. 9.1304 + For example, a group-writable home or <filename 9.1305 + role="special" class="directory">.ssh</filename> 9.1306 + directory will often cause this symptom.</para> 9.1307 + </listitem> 9.1308 + <listitem><para id="x_4ac">The user's <filename 9.1309 + role="special">authorized_keys</filename> file may have 9.1310 + a problem. If anyone other than the user owns or can write 9.1311 + to that file, the ssh daemon will not trust or read 9.1312 + it.</para> 9.1313 + </listitem></itemizedlist> 9.1314 + 9.1315 + <para id="x_4ad">In the ideal world, you should be able to run the 9.1316 + following command successfully, and it should print exactly 9.1317 + one line of output, the current date and time.</para> 9.1318 + <programlisting>ssh myserver date</programlisting> 9.1319 + 9.1320 + <para id="x_4ae">If, on your server, you have login scripts that print 9.1321 + banners or other junk even when running non-interactive 9.1322 + commands like this, you should fix them before you continue, 9.1323 + so that they only print output if they're run interactively. 9.1324 + Otherwise these banners will at least clutter up Mercurial's 9.1325 + output. Worse, they could potentially cause problems with 9.1326 + running Mercurial commands remotely. Mercurial tries to 9.1327 + detect and ignore banners in non-interactive 9.1328 + <command>ssh</command> sessions, but it is not foolproof. (If 9.1329 + you're editing your login scripts on your server, the usual 9.1330 + way to see if a login script is running in an interactive 9.1331 + shell is to check the return code from the command 9.1332 + <literal>tty -s</literal>.)</para> 9.1333 + 9.1334 + <para id="x_4af">Once you've verified that plain old ssh is working with 9.1335 + your server, the next step is to ensure that Mercurial runs on 9.1336 + the server. The following command should run 9.1337 + successfully:</para> 9.1338 + 9.1339 + <programlisting>ssh myserver hg version</programlisting> 9.1340 + 9.1341 + <para id="x_4b0">If you see an error message instead of normal <command 9.1342 + role="hg-cmd">hg version</command> output, this is usually 9.1343 + because you haven't installed Mercurial to <filename 9.1344 + class="directory">/usr/bin</filename>. Don't worry if this 9.1345 + is the case; you don't need to do that. But you should check 9.1346 + for a few possible problems.</para> 9.1347 + <itemizedlist> 9.1348 + <listitem><para id="x_4b1">Is Mercurial really installed on the server at 9.1349 + all? I know this sounds trivial, but it's worth 9.1350 + checking!</para> 9.1351 + </listitem> 9.1352 + <listitem><para id="x_4b2">Maybe your shell's search path (usually set 9.1353 + via the <envar>PATH</envar> environment variable) is 9.1354 + simply misconfigured.</para> 9.1355 + </listitem> 9.1356 + <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 9.1357 + variable is only being set to point to the location of the 9.1358 + <command>hg</command> executable if the login session is 9.1359 + interactive. This can happen if you're setting the path 9.1360 + in the wrong shell login script. See your shell's 9.1361 + documentation for details.</para> 9.1362 + </listitem> 9.1363 + <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 9.1364 + variable may need to contain the path to the Mercurial 9.1365 + Python modules. It might not be set at all; it could be 9.1366 + incorrect; or it may be set only if the login is 9.1367 + interactive.</para> 9.1368 + </listitem></itemizedlist> 9.1369 + 9.1370 + <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 9.1371 + over an ssh connection, well done! You've got the server and 9.1372 + client sorted out. You should now be able to use Mercurial to 9.1373 + access repositories hosted by that username on that server. 9.1374 + If you run into problems with Mercurial and ssh at this point, 9.1375 + try using the <option role="hg-opt-global">--debug</option> 9.1376 + option to get a clearer picture of what's going on.</para> 9.1377 + </sect2> 9.1378 + <sect2> 9.1379 + <title>Using compression with ssh</title> 9.1380 + 9.1381 + <para id="x_4b6">Mercurial does not compress data when it uses the ssh 9.1382 + protocol, because the ssh protocol can transparently compress 9.1383 + data. However, the default behavior of ssh clients is 9.1384 + <emphasis>not</emphasis> to request compression.</para> 9.1385 + 9.1386 + <para id="x_4b7">Over any network other than a fast LAN (even a wireless 9.1387 + network), using compression is likely to significantly speed 9.1388 + up Mercurial's network operations. For example, over a WAN, 9.1389 + someone measured compression as reducing the amount of time 9.1390 + required to clone a particularly large repository from 51 9.1391 + minutes to 17 minutes.</para> 9.1392 + 9.1393 + <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 9.1394 + accept a <option role="cmd-opt-ssh">-C</option> option which 9.1395 + turns on compression. You can easily edit your <filename 9.1396 + role="special">~/.hgrc</filename> to enable compression for 9.1397 + all of Mercurial's uses of the ssh protocol. Here is how to 9.1398 + do so for regular <command>ssh</command> on Unix-like systems, 9.1399 + for example.</para> 9.1400 + <programlisting>[ui] 9.1401 +ssh = ssh -C</programlisting> 9.1402 + 9.1403 + <para id="x_4b9">If you use <command>ssh</command> on a 9.1404 + Unix-like system, you can configure it to always use 9.1405 + compression when talking to your server. To do this, edit 9.1406 + your <filename role="special">.ssh/config</filename> file 9.1407 + (which may not yet exist), as follows.</para> 9.1408 + 9.1409 + <programlisting>Host hg 9.1410 + Compression yes 9.1411 + HostName hg.example.com</programlisting> 9.1412 + 9.1413 + <para id="x_4ba">This defines a hostname alias, 9.1414 + <literal>hg</literal>. When you use that hostname on the 9.1415 + <command>ssh</command> command line or in a Mercurial 9.1416 + <literal>ssh</literal>-protocol URL, it will cause 9.1417 + <command>ssh</command> to connect to 9.1418 + <literal>hg.example.com</literal> and use compression. This 9.1419 + gives you both a shorter name to type and compression, each of 9.1420 + which is a good thing in its own right.</para> 9.1421 + </sect2> 9.1422 + </sect1> 9.1423 + 9.1424 + <sect1 id="sec:collab:cgi"> 9.1425 + <title>Serving over HTTP using CGI</title> 9.1426 + 9.1427 + <para id="x_6a8">The simplest way to host one or more repositories in a 9.1428 + permanent way is to use a web server and Mercurial's CGI 9.1429 + support.</para> 9.1430 + 9.1431 + <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 9.1432 + CGI interface can take anything from a few moments to several 9.1433 + hours.</para> 9.1434 + 9.1435 + <para id="x_4bc">We'll begin with the simplest of examples, and work our way 9.1436 + towards a more complex configuration. Even for the most basic 9.1437 + case, you're almost certainly going to need to read and modify 9.1438 + your web server's configuration.</para> 9.1439 + 9.1440 + <note> 9.1441 + <title>High pain tolerance required</title> 9.1442 + 9.1443 + <para id="x_4bd">Configuring a web server is a complex, fiddly, 9.1444 + and highly system-dependent activity. I can't possibly give 9.1445 + you instructions that will cover anything like all of the 9.1446 + cases you will encounter. Please use your discretion and 9.1447 + judgment in following the sections below. Be prepared to make 9.1448 + plenty of mistakes, and to spend a lot of time reading your 9.1449 + server's error logs.</para> 9.1450 + 9.1451 + <para id="x_6a9">If you don't have a strong stomach for tweaking 9.1452 + configurations over and over, or a compelling need to host 9.1453 + your own services, you might want to try one of the public 9.1454 + hosting services that I mentioned earlier.</para> 9.1455 + </note> 9.1456 + 9.1457 + <sect2> 9.1458 + <title>Web server configuration checklist</title> 9.1459 + 9.1460 + <para id="x_4be">Before you continue, do take a few moments to check a few 9.1461 + aspects of your system's setup.</para> 9.1462 + 9.1463 + <orderedlist> 9.1464 + <listitem><para id="x_4bf">Do you have a web server installed 9.1465 + at all? Mac OS X and some Linux distributions ship with 9.1466 + Apache, but many other systems may not have a web server 9.1467 + installed.</para> 9.1468 + </listitem> 9.1469 + <listitem><para id="x_4c0">If you have a web server installed, is it 9.1470 + actually running? On most systems, even if one is 9.1471 + present, it will be disabled by default.</para> 9.1472 + </listitem> 9.1473 + <listitem><para id="x_4c1">Is your server configured to allow you to run 9.1474 + CGI programs in the directory where you plan to do so? 9.1475 + Most servers default to explicitly disabling the ability 9.1476 + to run CGI programs.</para> 9.1477 + </listitem></orderedlist> 9.1478 + 9.1479 + <para id="x_4c2">If you don't have a web server installed, and don't have 9.1480 + substantial experience configuring Apache, you should consider 9.1481 + using the <literal>lighttpd</literal> web server instead of 9.1482 + Apache. Apache has a well-deserved reputation for baroque and 9.1483 + confusing configuration. While <literal>lighttpd</literal> is 9.1484 + less capable in some ways than Apache, most of these 9.1485 + capabilities are not relevant to serving Mercurial 9.1486 + repositories. And <literal>lighttpd</literal> is undeniably 9.1487 + <emphasis>much</emphasis> easier to get started with than 9.1488 + Apache.</para> 9.1489 + </sect2> 9.1490 + 9.1491 + <sect2> 9.1492 + <title>Basic CGI configuration</title> 9.1493 + 9.1494 + <para id="x_4c3">On Unix-like systems, it's common for users to have a 9.1495 + subdirectory named something like <filename 9.1496 + class="directory">public_html</filename> in their home 9.1497 + directory, from which they can serve up web pages. A file 9.1498 + named <filename>foo</filename> in this directory will be 9.1499 + accessible at a URL of the form 9.1500 + <literal>http://www.example.com/username/foo</literal>.</para> 9.1501 + 9.1502 + <para id="x_4c4">To get started, find the <filename 9.1503 + role="special">hgweb.cgi</filename> script that should be 9.1504 + present in your Mercurial installation. If you can't quickly 9.1505 + find a local copy on your system, simply download one from the 9.1506 + master Mercurial repository at <ulink 9.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> 9.1508 + 9.1509 + <para id="x_4c5">You'll need to copy this script into your <filename 9.1510 + class="directory">public_html</filename> directory, and 9.1511 + ensure that it's executable.</para> 9.1512 + <programlisting>cp .../hgweb.cgi ~/public_html 9.1513 +chmod 755 ~/public_html/hgweb.cgi</programlisting> 9.1514 + <para id="x_4c6">The <literal>755</literal> argument to 9.1515 + <command>chmod</command> is a little more general than just 9.1516 + making the script executable: it ensures that the script is 9.1517 + executable by anyone, and that <quote>group</quote> and 9.1518 + <quote>other</quote> write permissions are 9.1519 + <emphasis>not</emphasis> set. If you were to leave those 9.1520 + write permissions enabled, Apache's <literal>suexec</literal> 9.1521 + subsystem would likely refuse to execute the script. In fact, 9.1522 + <literal>suexec</literal> also insists that the 9.1523 + <emphasis>directory</emphasis> in which the script resides 9.1524 + must not be writable by others.</para> 9.1525 + <programlisting>chmod 755 ~/public_html</programlisting> 9.1526 + 9.1527 + <sect3 id="sec:collab:wtf"> 9.1528 + <title>What could <emphasis>possibly</emphasis> go 9.1529 + wrong?</title> 9.1530 + 9.1531 + <para id="x_4c7">Once you've copied the CGI script into place, 9.1532 + go into a web browser, and try to open the URL 9.1533 + <literal>http://myhostname/~myuser/hgweb.cgi</literal>, 9.1534 + <emphasis>but</emphasis> brace yourself for instant failure. 9.1535 + There's a high probability that trying to visit this URL 9.1536 + will fail, and there are many possible reasons for this. In 9.1537 + fact, you're likely to stumble over almost every one of the 9.1538 + possible errors below, so please read carefully. The 9.1539 + following are all of the problems I ran into on a system 9.1540 + running Fedora 7, with a fresh installation of Apache, and a 9.1541 + user account that I created specially to perform this 9.1542 + exercise.</para> 9.1543 + 9.1544 + <para id="x_4c8">Your web server may have per-user directories disabled. 9.1545 + If you're using Apache, search your config file for a 9.1546 + <literal>UserDir</literal> directive. If there's none 9.1547 + present, per-user directories will be disabled. If one 9.1548 + exists, but its value is <literal>disabled</literal>, then 9.1549 + per-user directories will be disabled. Otherwise, the 9.1550 + string after <literal>UserDir</literal> gives the name of 9.1551 + the subdirectory that Apache will look in under your home 9.1552 + directory, for example <filename 9.1553 + class="directory">public_html</filename>.</para> 9.1554 + 9.1555 + <para id="x_4c9">Your file access permissions may be too restrictive. 9.1556 + The web server must be able to traverse your home directory 9.1557 + and directories under your <filename 9.1558 + class="directory">public_html</filename> directory, and 9.1559 + read files under the latter too. Here's a quick recipe to 9.1560 + help you to make your permissions more appropriate.</para> 9.1561 + <programlisting>chmod 755 ~ 9.1562 +find ~/public_html -type d -print0 | xargs -0r chmod 755 9.1563 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 9.1564 + 9.1565 + <para id="x_4ca">The other possibility with permissions is that you might 9.1566 + get a completely empty window when you try to load the 9.1567 + script. In this case, it's likely that your access 9.1568 + permissions are <emphasis>too permissive</emphasis>. Apache's 9.1569 + <literal>suexec</literal> subsystem won't execute a script 9.1570 + that's group- or world-writable, for example.</para> 9.1571 + 9.1572 + <para id="x_4cb">Your web server may be configured to disallow execution 9.1573 + of CGI programs in your per-user web directory. Here's 9.1574 + Apache's default per-user configuration from my Fedora 9.1575 + system.</para> 9.1576 + 9.1577 + &ch06-apache-config.lst; 9.1578 + 9.1579 + <para id="x_4cc">If you find a similar-looking 9.1580 + <literal>Directory</literal> group in your Apache 9.1581 + configuration, the directive to look at inside it is 9.1582 + <literal>Options</literal>. Add <literal>ExecCGI</literal> 9.1583 + to the end of this list if it's missing, and restart the web 9.1584 + server.</para> 9.1585 + 9.1586 + <para id="x_4cd">If you find that Apache serves you the text of the CGI 9.1587 + script instead of executing it, you may need to either 9.1588 + uncomment (if already present) or add a directive like 9.1589 + this.</para> 9.1590 + <programlisting>AddHandler cgi-script .cgi</programlisting> 9.1591 + 9.1592 + <para id="x_4ce">The next possibility is that you might be served with a 9.1593 + colourful Python backtrace claiming that it can't import a 9.1594 + <literal>mercurial</literal>-related module. This is 9.1595 + actually progress! The server is now capable of executing 9.1596 + your CGI script. This error is only likely to occur if 9.1597 + you're running a private installation of Mercurial, instead 9.1598 + of a system-wide version. Remember that the web server runs 9.1599 + the CGI program without any of the environment variables 9.1600 + that you take for granted in an interactive session. If 9.1601 + this error happens to you, edit your copy of <filename 9.1602 + role="special">hgweb.cgi</filename> and follow the 9.1603 + directions inside it to correctly set your 9.1604 + <envar>PYTHONPATH</envar> environment variable.</para> 9.1605 + 9.1606 + <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be 9.1607 + served with another colourful Python backtrace: this one 9.1608 + will complain that it can't find <filename 9.1609 + class="directory">/path/to/repository</filename>. Edit 9.1610 + your <filename role="special">hgweb.cgi</filename> script 9.1611 + and replace the <filename 9.1612 + class="directory">/path/to/repository</filename> string 9.1613 + with the complete path to the repository you want to serve 9.1614 + up.</para> 9.1615 + 9.1616 + <para id="x_4d0">At this point, when you try to reload the page, you 9.1617 + should be presented with a nice HTML view of your 9.1618 + repository's history. Whew!</para> 9.1619 + </sect3> 9.1620 + 9.1621 + <sect3> 9.1622 + <title>Configuring lighttpd</title> 9.1623 + 9.1624 + <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 9.1625 + the increasingly popular <literal>lighttpd</literal> web 9.1626 + server to serve the same repository as I described with 9.1627 + Apache above. I had already overcome all of the problems I 9.1628 + outlined with Apache, many of which are not server-specific. 9.1629 + As a result, I was fairly sure that my file and directory 9.1630 + permissions were good, and that my <filename 9.1631 + role="special">hgweb.cgi</filename> script was properly 9.1632 + edited.</para> 9.1633 + 9.1634 + <para id="x_4d2">Once I had Apache running, getting 9.1635 + <literal>lighttpd</literal> to serve the repository was a 9.1636 + snap (in other words, even if you're trying to use 9.1637 + <literal>lighttpd</literal>, you should read the Apache 9.1638 + section). I first had to edit the 9.1639 + <literal>mod_access</literal> section of its config file to 9.1640 + enable <literal>mod_cgi</literal> and 9.1641 + <literal>mod_userdir</literal>, both of which were disabled 9.1642 + by default on my system. I then added a few lines to the 9.1643 + end of the config file, to configure these modules.</para> 9.1644 + <programlisting>userdir.path = "public_html" 9.1645 +cgi.assign = (".cgi" => "" )</programlisting> 9.1646 + <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 9.1647 + immediately for me. If I had configured 9.1648 + <literal>lighttpd</literal> before Apache, I'd almost 9.1649 + certainly have run into many of the same system-level 9.1650 + configuration problems as I did with Apache. However, I 9.1651 + found <literal>lighttpd</literal> to be noticeably easier to 9.1652 + configure than Apache, even though I've used Apache for over 9.1653 + a decade, and this was my first exposure to 9.1654 + <literal>lighttpd</literal>.</para> 9.1655 + </sect3> 9.1656 + </sect2> 9.1657 + 9.1658 + <sect2> 9.1659 + <title>Sharing multiple repositories with one CGI script</title> 9.1660 + 9.1661 + <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 9.1662 + only lets you publish a single repository, which is an 9.1663 + annoying restriction. If you want to publish more than one 9.1664 + without wracking yourself with multiple copies of the same 9.1665 + script, each with different names, a better choice is to use 9.1666 + the <filename role="special">hgwebdir.cgi</filename> 9.1667 + script.</para> 9.1668 + 9.1669 + <para id="x_4d5">The procedure to configure <filename 9.1670 + role="special">hgwebdir.cgi</filename> is only a little more 9.1671 + involved than for <filename 9.1672 + role="special">hgweb.cgi</filename>. First, you must obtain 9.1673 + a copy of the script. If you don't have one handy, you can 9.1674 + download a copy from the master Mercurial repository at <ulink 9.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> 9.1676 + 9.1677 + <para id="x_4d6">You'll need to copy this script into your <filename 9.1678 + class="directory">public_html</filename> directory, and 9.1679 + ensure that it's executable.</para> 9.1680 + 9.1681 + <programlisting>cp .../hgwebdir.cgi ~/public_html 9.1682 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 9.1683 + 9.1684 + <para id="x_4d7">With basic configuration out of the way, try to 9.1685 + visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal> 9.1686 + in your browser. It should 9.1687 + display an empty list of repositories. If you get a blank 9.1688 + window or error message, try walking through the list of 9.1689 + potential problems in <xref 9.1690 + linkend="sec:collab:wtf"/>.</para> 9.1691 + 9.1692 + <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 9.1693 + script relies on an external configuration file. By default, 9.1694 + it searches for a file named <filename 9.1695 + role="special">hgweb.config</filename> in the same directory 9.1696 + as itself. You'll need to create this file, and make it 9.1697 + world-readable. The format of the file is similar to a 9.1698 + Windows <quote>ini</quote> file, as understood by Python's 9.1699 + <literal>ConfigParser</literal> 9.1700 + <citation>web:configparser</citation> module.</para> 9.1701 + 9.1702 + <para id="x_4d9">The easiest way to configure <filename 9.1703 + role="special">hgwebdir.cgi</filename> is with a section 9.1704 + named <literal>collections</literal>. This will automatically 9.1705 + publish <emphasis>every</emphasis> repository under the 9.1706 + directories you name. The section should look like 9.1707 + this:</para> 9.1708 + <programlisting>[collections] 9.1709 +/my/root = /my/root</programlisting> 9.1710 + <para id="x_4da">Mercurial interprets this by looking at the directory name 9.1711 + on the <emphasis>right</emphasis> hand side of the 9.1712 + <quote><literal>=</literal></quote> sign; finding repositories 9.1713 + in that directory hierarchy; and using the text on the 9.1714 + <emphasis>left</emphasis> to strip off matching text from the 9.1715 + names it will actually list in the web interface. The 9.1716 + remaining component of a path after this stripping has 9.1717 + occurred is called a <quote>virtual path</quote>.</para> 9.1718 + 9.1719 + <para id="x_4db">Given the example above, if we have a 9.1720 + repository whose local path is <filename 9.1721 + class="directory">/my/root/this/repo</filename>, the CGI 9.1722 + script will strip the leading <filename 9.1723 + class="directory">/my/root</filename> from the name, and 9.1724 + publish the repository with a virtual path of <filename 9.1725 + class="directory">this/repo</filename>. If the base URL for 9.1726 + our CGI script is 9.1727 + <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the 9.1728 + complete URL for that repository will be 9.1729 + <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para> 9.1730 + 9.1731 + <para id="x_4dc">If we replace <filename 9.1732 + class="directory">/my/root</filename> on the left hand side 9.1733 + of this example with <filename 9.1734 + class="directory">/my</filename>, then <filename 9.1735 + role="special">hgwebdir.cgi</filename> will only strip off 9.1736 + <filename class="directory">/my</filename> from the repository 9.1737 + name, and will give us a virtual path of <filename 9.1738 + class="directory">root/this/repo</filename> instead of 9.1739 + <filename class="directory">this/repo</filename>.</para> 9.1740 + 9.1741 + <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 9.1742 + script will recursively search each directory listed in the 9.1743 + <literal>collections</literal> section of its configuration 9.1744 + file, but it will <literal>not</literal> recurse into the 9.1745 + repositories it finds.</para> 9.1746 + 9.1747 + <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 9.1748 + to publish many repositories in a <quote>fire and 9.1749 + forget</quote> manner. You only need to set up the CGI 9.1750 + script and configuration file one time. Afterwards, you can 9.1751 + publish or unpublish a repository at any time by simply moving 9.1752 + it into, or out of, the directory hierarchy in which you've 9.1753 + configured <filename role="special">hgwebdir.cgi</filename> to 9.1754 + look.</para> 9.1755 + 9.1756 + <sect3> 9.1757 + <title>Explicitly specifying which repositories to 9.1758 + publish</title> 9.1759 + 9.1760 + <para id="x_4df">In addition to the <literal>collections</literal> 9.1761 + mechanism, the <filename 9.1762 + role="special">hgwebdir.cgi</filename> script allows you 9.1763 + to publish a specific list of repositories. To do so, 9.1764 + create a <literal>paths</literal> section, with contents of 9.1765 + the following form.</para> 9.1766 + <programlisting>[paths] 9.1767 +repo1 = /my/path/to/some/repo 9.1768 +repo2 = /some/path/to/another</programlisting> 9.1769 + <para id="x_4e0">In this case, the virtual path (the component that will 9.1770 + appear in a URL) is on the left hand side of each 9.1771 + definition, while the path to the repository is on the 9.1772 + right. Notice that there does not need to be any 9.1773 + relationship between the virtual path you choose and the 9.1774 + location of a repository in your filesystem.</para> 9.1775 + 9.1776 + <para id="x_4e1">If you wish, you can use both the 9.1777 + <literal>collections</literal> and <literal>paths</literal> 9.1778 + mechanisms simultaneously in a single configuration 9.1779 + file.</para> 9.1780 + 9.1781 + <note> 9.1782 + <title>Beware duplicate virtual paths</title> 9.1783 + 9.1784 + <para id="x_4e2"> If several repositories have the same 9.1785 + virtual path, <filename 9.1786 + role="special">hgwebdir.cgi</filename> will not report 9.1787 + an error. Instead, it will behave unpredictably.</para> 9.1788 + </note> 9.1789 + </sect3> 9.1790 + </sect2> 9.1791 + 9.1792 + <sect2> 9.1793 + <title>Downloading source archives</title> 9.1794 + 9.1795 + <para id="x_4e3">Mercurial's web interface lets users download an archive 9.1796 + of any revision. This archive will contain a snapshot of the 9.1797 + working directory as of that revision, but it will not contain 9.1798 + a copy of the repository data.</para> 9.1799 + 9.1800 + <para id="x_4e4">By default, this feature is not enabled. To enable it, 9.1801 + you'll need to add an <envar 9.1802 + role="rc-item-web">allow_archive</envar> item to the 9.1803 + <literal role="rc-web">web</literal> section of your <filename 9.1804 + role="special">~/.hgrc</filename>; see below for details.</para> 9.1805 + </sect2> 9.1806 + <sect2> 9.1807 + <title>Web configuration options</title> 9.1808 + 9.1809 + <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 9.1810 + serve</command> command, and the <filename 9.1811 + role="special">hgweb.cgi</filename> and <filename 9.1812 + role="special">hgwebdir.cgi</filename> scripts) have a 9.1813 + number of configuration options that you can set. These 9.1814 + belong in a section named <literal 9.1815 + role="rc-web">web</literal>.</para> 9.1816 + <itemizedlist> 9.1817 + <listitem><para id="x_4e6"><envar 9.1818 + role="rc-item-web">allow_archive</envar>: Determines 9.1819 + which (if any) archive download mechanisms Mercurial 9.1820 + supports. If you enable this feature, users of the web 9.1821 + interface will be able to download an archive of whatever 9.1822 + revision of a repository they are viewing. To enable the 9.1823 + archive feature, this item must take the form of a 9.1824 + sequence of words drawn from the list below.</para> 9.1825 + <itemizedlist> 9.1826 + <listitem><para id="x_4e7"><literal>bz2</literal>: A 9.1827 + <command>tar</command> archive, compressed using 9.1828 + <literal>bzip2</literal> compression. This has the 9.1829 + best compression ratio, but uses the most CPU time on 9.1830 + the server.</para> 9.1831 + </listitem> 9.1832 + <listitem><para id="x_4e8"><literal>gz</literal>: A 9.1833 + <command>tar</command> archive, compressed using 9.1834 + <literal>gzip</literal> compression.</para> 9.1835 + </listitem> 9.1836 + <listitem><para id="x_4e9"><literal>zip</literal>: A 9.1837 + <command>zip</command> archive, compressed using LZW 9.1838 + compression. This format has the worst compression 9.1839 + ratio, but is widely used in the Windows world.</para> 9.1840 + </listitem> 9.1841 + </itemizedlist> 9.1842 + <para id="x_4ea"> If you provide an empty list, or don't have an 9.1843 + <envar role="rc-item-web">allow_archive</envar> entry at 9.1844 + all, this feature will be disabled. Here is an example of 9.1845 + how to enable all three supported formats.</para> 9.1846 + <programlisting>[web] 9.1847 +allow_archive = bz2 gz zip</programlisting> 9.1848 + </listitem> 9.1849 + <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 9.1850 + Boolean. Determines whether the web interface allows 9.1851 + remote users to <command role="hg-cmd">hg pull</command> 9.1852 + and <command role="hg-cmd">hg clone</command> this 9.1853 + repository over HTTP. If set to <literal>no</literal> or 9.1854 + <literal>false</literal>, only the 9.1855 + <quote>human-oriented</quote> portion of the web interface 9.1856 + is available.</para> 9.1857 + </listitem> 9.1858 + <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 9.1859 + String. A free-form (but preferably brief) string 9.1860 + identifying the person or group in charge of the 9.1861 + repository. This often contains the name and email 9.1862 + address of a person or mailing list. It often makes sense 9.1863 + to place this entry in a repository's own <filename 9.1864 + role="special">.hg/hgrc</filename> file, but it can make 9.1865 + sense to use in a global <filename 9.1866 + role="special">~/.hgrc</filename> if every repository 9.1867 + has a single maintainer.</para> 9.1868 + </listitem> 9.1869 + <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 9.1870 + Integer. The default maximum number of changesets to 9.1871 + display in a single page of output.</para> 9.1872 + </listitem> 9.1873 + <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 9.1874 + Integer. The default maximum number of modified files to 9.1875 + display in a single page of output.</para> 9.1876 + </listitem> 9.1877 + <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 9.1878 + Integer. If the web interface displays alternating 9.1879 + <quote>stripes</quote> to make it easier to visually align 9.1880 + rows when you are looking at a table, this number controls 9.1881 + the number of rows in each stripe.</para> 9.1882 + </listitem> 9.1883 + <listitem><para id="x_4f0"><envar 9.1884 + role="rc-item-web">style</envar>: Controls the template 9.1885 + Mercurial uses to display the web interface. Mercurial 9.1886 + ships with several web templates.</para> 9.1887 + <itemizedlist> 9.1888 + <listitem> 9.1889 + <para id="x_6aa"><literal>coal</literal> is monochromatic.</para> 9.1890 + </listitem> 9.1891 + <listitem> 9.1892 + <para id="x_6ab"><literal>gitweb</literal> emulates the visual 9.1893 + style of git's web interface.</para> 9.1894 + </listitem> 9.1895 + <listitem> 9.1896 + <para id="x_6ac"><literal>monoblue</literal> uses solid blues and 9.1897 + greys.</para> 9.1898 + </listitem> 9.1899 + <listitem> 9.1900 + <para id="x_6ad"><literal>paper</literal> is the default.</para> 9.1901 + </listitem> 9.1902 + <listitem> 9.1903 + <para id="x_6ae"><literal>spartan</literal> was the default for a 9.1904 + long time.</para> 9.1905 + </listitem> 9.1906 + </itemizedlist> 9.1907 + <para id="x_6af">You can 9.1908 + also specify a custom template of your own; see 9.1909 + <xref linkend="chap:template"/> for details. Here, you can 9.1910 + see how to enable the <literal>gitweb</literal> 9.1911 + style.</para> 9.1912 + <programlisting>[web] 9.1913 +style = gitweb</programlisting> 9.1914 + </listitem> 9.1915 + <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 9.1916 + Path. The directory in which to search for template 9.1917 + files. By default, Mercurial searches in the directory in 9.1918 + which it was installed.</para> 9.1919 + </listitem></itemizedlist> 9.1920 + <para id="x_4f2">If you are using <filename 9.1921 + role="special">hgwebdir.cgi</filename>, you can place a few 9.1922 + configuration items in a <literal role="rc-web">web</literal> 9.1923 + section of the <filename 9.1924 + role="special">hgweb.config</filename> file instead of a 9.1925 + <filename role="special">~/.hgrc</filename> file, for 9.1926 + convenience. These items are <envar 9.1927 + role="rc-item-web">motd</envar> and <envar 9.1928 + role="rc-item-web">style</envar>.</para> 9.1929 + 9.1930 + <sect3> 9.1931 + <title>Options specific to an individual repository</title> 9.1932 + 9.1933 + <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 9.1934 + items ought to be placed in a repository's local <filename 9.1935 + role="special">.hg/hgrc</filename>, rather than a user's 9.1936 + or global <filename role="special">~/.hgrc</filename>.</para> 9.1937 + <itemizedlist> 9.1938 + <listitem><para id="x_4f4"><envar 9.1939 + role="rc-item-web">description</envar>: String. A 9.1940 + free-form (but preferably brief) string that describes 9.1941 + the contents or purpose of the repository.</para> 9.1942 + </listitem> 9.1943 + <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 9.1944 + String. The name to use for the repository in the web 9.1945 + interface. This overrides the default name, which is 9.1946 + the last component of the repository's path.</para> 9.1947 + </listitem></itemizedlist> 9.1948 + </sect3> 9.1949 + 9.1950 + <sect3> 9.1951 + <title>Options specific to the <command role="hg-cmd">hg 9.1952 + serve</command> command</title> 9.1953 + 9.1954 + <para id="x_4f6">Some of the items in the <literal 9.1955 + role="rc-web">web</literal> section of a <filename 9.1956 + role="special">~/.hgrc</filename> file are only for use 9.1957 + with the <command role="hg-cmd">hg serve</command> 9.1958 + command.</para> 9.1959 + <itemizedlist> 9.1960 + <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 9.1961 + Path. The name of a file into which to write an access 9.1962 + log. By default, the <command role="hg-cmd">hg 9.1963 + serve</command> command writes this information to 9.1964 + standard output, not to a file. Log entries are written 9.1965 + in the standard <quote>combined</quote> file format used 9.1966 + by almost all web servers.</para> 9.1967 + </listitem> 9.1968 + <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 9.1969 + String. The local address on which the server should 9.1970 + listen for incoming connections. By default, the server 9.1971 + listens on all addresses.</para> 9.1972 + </listitem> 9.1973 + <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 9.1974 + Path. The name of a file into which to write an error 9.1975 + log. By default, the <command role="hg-cmd">hg 9.1976 + serve</command> command writes this information to 9.1977 + standard error, not to a file.</para> 9.1978 + </listitem> 9.1979 + <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 9.1980 + Boolean. Whether to use the IPv6 protocol. By default, 9.1981 + IPv6 is not used.</para> 9.1982 + </listitem> 9.1983 + <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 9.1984 + Integer. The TCP port number on which the server should 9.1985 + listen. The default port number used is 8000.</para> 9.1986 + </listitem></itemizedlist> 9.1987 + </sect3> 9.1988 + 9.1989 + <sect3> 9.1990 + <title>Choosing the right <filename 9.1991 + role="special">~/.hgrc</filename> file to add <literal 9.1992 + role="rc-web">web</literal> items to</title> 9.1993 + 9.1994 + <para id="x_4fc">It is important to remember that a web server like 9.1995 + Apache or <literal>lighttpd</literal> will run under a user 9.1996 + ID that is different to yours. CGI scripts run by your 9.1997 + server, such as <filename 9.1998 + role="special">hgweb.cgi</filename>, will usually also run 9.1999 + under that user ID.</para> 9.2000 + 9.2001 + <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 9.2002 + your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 9.2003 + <filename role="special">~/.hgrc</filename> file. Those 9.2004 + settings will thus only affect the behavior of the <command 9.2005 + role="hg-cmd">hg serve</command> command when you run it. 9.2006 + To cause CGI scripts to see your settings, either create a 9.2007 + <filename role="special">~/.hgrc</filename> file in the 9.2008 + home directory of the user ID that runs your web server, or 9.2009 + add those settings to a system-wide <filename 9.2010 + role="special">hgrc</filename> file.</para> 9.2011 + </sect3> 9.2012 + </sect2> 9.2013 + </sect1> 9.2014 + 9.2015 + <sect1> 9.2016 + <title>System-wide configuration</title> 9.2017 + 9.2018 + <para id="x_6b0">On Unix-like systems shared by multiple users (such as a 9.2019 + server to which people publish changes), it often makes sense to 9.2020 + set up some global default behaviors, such as what theme to use 9.2021 + in web interfaces.</para> 9.2022 + 9.2023 + <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename> 9.2024 + exists, Mercurial will read it at startup time and apply any 9.2025 + configuration settings it finds in that file. It will also look 9.2026 + for files ending in a <literal>.rc</literal> extension in a 9.2027 + directory named <filename>/etc/mercurial/hgrc.d</filename>, and 9.2028 + apply any configuration settings it finds in each of those 9.2029 + files.</para> 9.2030 + 9.2031 + <sect2> 9.2032 + <title>Making Mercurial more trusting</title> 9.2033 + 9.2034 + <para id="x_6b2">One situation in which a global <filename>hgrc</filename> 9.2035 + can be useful is if users are pulling changes owned by other 9.2036 + users. By default, Mercurial will not trust most of the 9.2037 + configuration items in a <filename>.hg/hgrc</filename> file 9.2038 + inside a repository that is owned by a different user. If we 9.2039 + clone or pull changes from such a repository, Mercurial will 9.2040 + print a warning stating that it does not trust their 9.2041 + <filename>.hg/hgrc</filename>.</para> 9.2042 + 9.2043 + <para id="x_6b3">If everyone in a particular Unix group is on the same team 9.2044 + and <emphasis>should</emphasis> trust each other's 9.2045 + configuration settings, or we want to trust particular users, 9.2046 + we can override Mercurial's skeptical defaults by creating a 9.2047 + system-wide <filename>hgrc</filename> file such as the 9.2048 + following:</para> 9.2049 + 9.2050 + <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc 9.2051 +[trusted] 9.2052 +# Trust all entries in any hgrc file owned by the "editors" or 9.2053 +# "www-data" groups. 9.2054 +groups = editors, www-data 9.2055 + 9.2056 +# Trust entries in hgrc files owned by the following users. 9.2057 +users = apache, bobo 9.2058 </programlisting> 9.2059 -<orderedlist> 9.2060 -<listitem><para>The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the ssh 9.2061 - protocol. 9.2062 -</para> 9.2063 -</listitem> 9.2064 -<listitem><para>The <quote><literal>bos@</literal></quote> component indicates what username to log 9.2065 - into the server as. You can leave this out if the remote username 9.2066 - is the same as your local username. 9.2067 -</para> 9.2068 -</listitem> 9.2069 -<listitem><para>The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of the 9.2070 - server to log into. 9.2071 -</para> 9.2072 -</listitem> 9.2073 -<listitem><para>The <quote>:22</quote> identifies the port number to connect to the server 9.2074 - on. The default port is 22, so you only need to specify this part 9.2075 - if you're <emphasis>not</emphasis> using port 22. 9.2076 -</para> 9.2077 -</listitem> 9.2078 -<listitem><para>The remainder of the URL is the local path to the repository on 9.2079 - the server. 9.2080 -</para> 9.2081 -</listitem></orderedlist> 9.2082 - 9.2083 -<para>There's plenty of scope for confusion with the path component of ssh 9.2084 -URLs, as there is no standard way for tools to interpret it. Some 9.2085 -programs behave differently than others when dealing with these paths. 9.2086 -This isn't an ideal situation, but it's unlikely to change. Please 9.2087 -read the following paragraphs carefully. 9.2088 -</para> 9.2089 - 9.2090 -<para>Mercurial treats the path to a repository on the server as relative to 9.2091 -the remote user's home directory. For example, if user <literal>foo</literal> 9.2092 -on the server has a home directory of <filename class="directory">/home/foo</filename>, then an ssh 9.2093 -URL that contains a path component of <filename class="directory">bar</filename> 9.2094 -<emphasis>really</emphasis> refers to the directory <filename class="directory">/home/foo/bar</filename>. 9.2095 -</para> 9.2096 - 9.2097 -<para>If you want to specify a path relative to another user's home 9.2098 -directory, you can use a path that starts with a tilde character 9.2099 -followed by the user's name (let's call them <literal>otheruser</literal>), like 9.2100 -this. 9.2101 -</para> 9.2102 -<programlisting> 9.2103 -<para> ssh://server/ otheruser/hg/repo 9.2104 -</para> 9.2105 -</programlisting> 9.2106 - 9.2107 -<para>And if you really want to specify an <emphasis>absolute</emphasis> path on the 9.2108 -server, begin the path component with two slashes, as in this example. 9.2109 -</para> 9.2110 -<programlisting> 9.2111 -<para> ssh://server//absolute/path 9.2112 -</para> 9.2113 -</programlisting> 9.2114 - 9.2115 -</sect2> 9.2116 -<sect2> 9.2117 -<title>Finding an ssh client for your system</title> 9.2118 - 9.2119 -<para>Almost every Unix-like system comes with OpenSSH preinstalled. If 9.2120 -you're using such a system, run <literal>which ssh</literal> to find out if 9.2121 -the <command>ssh</command> command is installed (it's usually in 9.2122 -<filename class="directory">/usr/bin</filename>). In the unlikely event that it isn't present, 9.2123 -take a look at your system documentation to figure out how to install 9.2124 -it. 9.2125 -</para> 9.2126 - 9.2127 -<para>On Windows, you'll first need to download a suitable ssh 9.2128 -client. There are two alternatives. 9.2129 -</para> 9.2130 -<itemizedlist> 9.2131 -<listitem><para>Simon Tatham's excellent PuTTY package <citation>web:putty</citation> provides 9.2132 - a complete suite of ssh client commands. 9.2133 -</para> 9.2134 -</listitem> 9.2135 -<listitem><para>If you have a high tolerance for pain, you can use the Cygwin 9.2136 - port of OpenSSH. 9.2137 -</para> 9.2138 -</listitem></itemizedlist> 9.2139 -<para>In either case, you'll need to edit your \hgini\ file to tell 9.2140 -Mercurial where to find the actual client command. For example, if 9.2141 -you're using PuTTY, you'll need to use the <command>plink</command> command as 9.2142 -a command-line ssh client. 9.2143 -</para> 9.2144 -<programlisting> 9.2145 -<para> [ui] 9.2146 - ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" 9.2147 -</para> 9.2148 -</programlisting> 9.2149 - 9.2150 -<note> 9.2151 -<para> The path to <command>plink</command> shouldn't contain any whitespace 9.2152 - characters, or Mercurial may not be able to run it correctly (so 9.2153 - putting it in <filename class="directory">C:\\Program Files</filename> is probably not a good 9.2154 - idea). 9.2155 -</para> 9.2156 -</note> 9.2157 - 9.2158 -</sect2> 9.2159 -<sect2> 9.2160 -<title>Generating a key pair</title> 9.2161 - 9.2162 -<para>To avoid the need to repetitively type a password every time you need 9.2163 -to use your ssh client, I recommend generating a key pair. On a 9.2164 -Unix-like system, the <command>ssh-keygen</command> command will do the trick. 9.2165 -On Windows, if you're using PuTTY, the <command>puttygen</command> command is 9.2166 -what you'll need. 9.2167 -</para> 9.2168 - 9.2169 -<para>When you generate a key pair, it's usually <emphasis>highly</emphasis> advisable to 9.2170 -protect it with a passphrase. (The only time that you might not want 9.2171 -to do this is when you're using the ssh protocol for automated tasks 9.2172 -on a secure network.) 9.2173 -</para> 9.2174 - 9.2175 -<para>Simply generating a key pair isn't enough, however. You'll need to 9.2176 -add the public key to the set of authorised keys for whatever user 9.2177 -you're logging in remotely as. For servers using OpenSSH (the vast 9.2178 -majority), this will mean adding the public key to a list in a file 9.2179 -called <filename role="special">authorized_keys</filename> in their <filename role="special" class="directory">.ssh</filename> 9.2180 -directory. 9.2181 -</para> 9.2182 - 9.2183 -<para>On a Unix-like system, your public key will have a <filename>.pub</filename> 9.2184 -extension. If you're using <command>puttygen</command> on Windows, you can 9.2185 -save the public key to a file of your choosing, or paste it from the 9.2186 -window it's displayed in straight into the 9.2187 -<filename role="special">authorized_keys</filename> file. 9.2188 -</para> 9.2189 - 9.2190 -</sect2> 9.2191 -<sect2> 9.2192 -<title>Using an authentication agent</title> 9.2193 - 9.2194 -<para>An authentication agent is a daemon that stores passphrases in memory 9.2195 -(so it will forget passphrases if you log out and log back in again). 9.2196 -An ssh client will notice if it's running, and query it for a 9.2197 -passphrase. If there's no authentication agent running, or the agent 9.2198 -doesn't store the necessary passphrase, you'll have to type your 9.2199 -passphrase every time Mercurial tries to communicate with a server on 9.2200 -your behalf (e.g. whenever you pull or push changes). 9.2201 -</para> 9.2202 - 9.2203 -<para>The downside of storing passphrases in an agent is that it's possible 9.2204 -for a well-prepared attacker to recover the plain text of your 9.2205 -passphrases, in some cases even if your system has been power-cycled. 9.2206 -You should make your own judgment as to whether this is an acceptable 9.2207 -risk. It certainly saves a lot of repeated typing. 9.2208 -</para> 9.2209 - 9.2210 -<para>On Unix-like systems, the agent is called <command>ssh-agent</command>, and 9.2211 -it's often run automatically for you when you log in. You'll need to 9.2212 -use the <command>ssh-add</command> command to add passphrases to the agent's 9.2213 -store. On Windows, if you're using PuTTY, the <command>pageant</command> 9.2214 -command acts as the agent. It adds an icon to your system tray that 9.2215 -will let you manage stored passphrases. 9.2216 -</para> 9.2217 - 9.2218 -</sect2> 9.2219 -<sect2> 9.2220 -<title>Configuring the server side properly</title> 9.2221 - 9.2222 -<para>Because ssh can be fiddly to set up if you're new to it, there's a 9.2223 -variety of things that can go wrong. Add Mercurial on top, and 9.2224 -there's plenty more scope for head-scratching. Most of these 9.2225 -potential problems occur on the server side, not the client side. The 9.2226 -good news is that once you've gotten a configuration working, it will 9.2227 -usually continue to work indefinitely. 9.2228 -</para> 9.2229 - 9.2230 -<para>Before you try using Mercurial to talk to an ssh server, it's best to 9.2231 -make sure that you can use the normal <command>ssh</command> or <command>putty</command> 9.2232 -command to talk to the server first. If you run into problems with 9.2233 -using these commands directly, Mercurial surely won't work. Worse, it 9.2234 -will obscure the underlying problem. Any time you want to debug 9.2235 -ssh-related Mercurial problems, you should drop back to making sure 9.2236 -that plain ssh client commands work first, <emphasis>before</emphasis> you worry 9.2237 -about whether there's a problem with Mercurial. 9.2238 -</para> 9.2239 - 9.2240 -<para>The first thing to be sure of on the server side is that you can 9.2241 -actually log in from another machine at all. If you can't use 9.2242 -<command>ssh</command> or <command>putty</command> to log in, the error message you get 9.2243 -may give you a few hints as to what's wrong. The most common problems 9.2244 -are as follows. 9.2245 -</para> 9.2246 -<itemizedlist> 9.2247 -<listitem><para>If you get a <quote>connection refused</quote> error, either there isn't an 9.2248 - SSH daemon running on the server at all, or it's inaccessible due to 9.2249 - firewall configuration. 9.2250 -</para> 9.2251 -</listitem> 9.2252 -<listitem><para>If you get a <quote>no route to host</quote> error, you either have an 9.2253 - incorrect address for the server or a seriously locked down firewall 9.2254 - that won't admit its existence at all. 9.2255 -</para> 9.2256 -</listitem> 9.2257 -<listitem><para>If you get a <quote>permission denied</quote> error, you may have mistyped 9.2258 - the username on the server, or you could have mistyped your key's 9.2259 - passphrase or the remote user's password. 9.2260 -</para> 9.2261 -</listitem></itemizedlist> 9.2262 -<para>In summary, if you're having trouble talking to the server's ssh 9.2263 -daemon, first make sure that one is running at all. On many systems 9.2264 -it will be installed, but disabled, by default. Once you're done with 9.2265 -this step, you should then check that the server's firewall is 9.2266 -configured to allow incoming connections on the port the ssh daemon is 9.2267 -listening on (usually 22). Don't worry about more exotic 9.2268 -possibilities for misconfiguration until you've checked these two 9.2269 -first. 9.2270 -</para> 9.2271 - 9.2272 -<para>If you're using an authentication agent on the client side to store 9.2273 -passphrases for your keys, you ought to be able to log into the server 9.2274 -without being prompted for a passphrase or a password. If you're 9.2275 -prompted for a passphrase, there are a few possible culprits. 9.2276 -</para> 9.2277 -<itemizedlist> 9.2278 -<listitem><para>You might have forgotten to use <command>ssh-add</command> or 9.2279 - <command>pageant</command> to store the passphrase. 9.2280 -</para> 9.2281 -</listitem> 9.2282 -<listitem><para>You might have stored the passphrase for the wrong key. 9.2283 -</para> 9.2284 -</listitem></itemizedlist> 9.2285 -<para>If you're being prompted for the remote user's password, there are 9.2286 -another few possible problems to check. 9.2287 -</para> 9.2288 -<itemizedlist> 9.2289 -<listitem><para>Either the user's home directory or their <filename role="special" class="directory">.ssh</filename> 9.2290 - directory might have excessively liberal permissions. As a result, 9.2291 - the ssh daemon will not trust or read their 9.2292 - <filename role="special">authorized_keys</filename> file. For example, a group-writable 9.2293 - home or <filename role="special" class="directory">.ssh</filename> directory will often cause this symptom. 9.2294 -</para> 9.2295 -</listitem> 9.2296 -<listitem><para>The user's <filename role="special">authorized_keys</filename> file may have a problem. 9.2297 - If anyone other than the user owns or can write to that file, the 9.2298 - ssh daemon will not trust or read it. 9.2299 -</para> 9.2300 -</listitem></itemizedlist> 9.2301 - 9.2302 -<para>In the ideal world, you should be able to run the following command 9.2303 -successfully, and it should print exactly one line of output, the 9.2304 -current date and time. 9.2305 -</para> 9.2306 -<programlisting> 9.2307 -<para> ssh myserver date 9.2308 -</para> 9.2309 -</programlisting> 9.2310 - 9.2311 -<para>If, on your server, you have login scripts that print banners or other 9.2312 -junk even when running non-interactive commands like this, you should 9.2313 -fix them before you continue, so that they only print output if 9.2314 -they're run interactively. Otherwise these banners will at least 9.2315 -clutter up Mercurial's output. Worse, they could potentially cause 9.2316 -problems with running Mercurial commands remotely. Mercurial makes 9.2317 -tries to detect and ignore banners in non-interactive <command>ssh</command> 9.2318 -sessions, but it is not foolproof. (If you're editing your login 9.2319 -scripts on your server, the usual way to see if a login script is 9.2320 -running in an interactive shell is to check the return code from the 9.2321 -command <literal>tty -s</literal>.) 9.2322 -</para> 9.2323 - 9.2324 -<para>Once you've verified that plain old ssh is working with your server, 9.2325 -the next step is to ensure that Mercurial runs on the server. The 9.2326 -following command should run successfully: 9.2327 -</para> 9.2328 -<programlisting> 9.2329 -<para> ssh myserver hg version 9.2330 -</para> 9.2331 -</programlisting> 9.2332 -<para>If you see an error message instead of normal <command role="hg-cmd">hg version</command> output, 9.2333 -this is usually because you haven't installed Mercurial to 9.2334 -<filename class="directory">/usr/bin</filename>. Don't worry if this is the case; you don't need 9.2335 -to do that. But you should check for a few possible problems. 9.2336 -</para> 9.2337 -<itemizedlist> 9.2338 -<listitem><para>Is Mercurial really installed on the server at all? I know this 9.2339 - sounds trivial, but it's worth checking! 9.2340 -</para> 9.2341 -</listitem> 9.2342 -<listitem><para>Maybe your shell's search path (usually set via the <envar>PATH</envar> 9.2343 - environment variable) is simply misconfigured. 9.2344 -</para> 9.2345 -</listitem> 9.2346 -<listitem><para>Perhaps your <envar>PATH</envar> environment variable is only being set 9.2347 - to point to the location of the <command>hg</command> executable if the login 9.2348 - session is interactive. This can happen if you're setting the path 9.2349 - in the wrong shell login script. See your shell's documentation for 9.2350 - details. 9.2351 -</para> 9.2352 -</listitem> 9.2353 -<listitem><para>The <envar>PYTHONPATH</envar> environment variable may need to contain 9.2354 - the path to the Mercurial Python modules. It might not be set at 9.2355 - all; it could be incorrect; or it may be set only if the login is 9.2356 - interactive. 9.2357 -</para> 9.2358 -</listitem></itemizedlist> 9.2359 - 9.2360 -<para>If you can run <command role="hg-cmd">hg version</command> over an ssh connection, well done! 9.2361 -You've got the server and client sorted out. You should now be able 9.2362 -to use Mercurial to access repositories hosted by that username on 9.2363 -that server. If you run into problems with Mercurial and ssh at this 9.2364 -point, try using the <option role="hg-opt-global">--debug</option> option to get a clearer picture 9.2365 -of what's going on. 9.2366 -</para> 9.2367 - 9.2368 -</sect2> 9.2369 -<sect2> 9.2370 -<title>Using compression with ssh</title> 9.2371 - 9.2372 -<para>Mercurial does not compress data when it uses the ssh protocol, 9.2373 -because the ssh protocol can transparently compress data. However, 9.2374 -the default behaviour of ssh clients is <emphasis>not</emphasis> to request 9.2375 -compression. 9.2376 -</para> 9.2377 - 9.2378 -<para>Over any network other than a fast LAN (even a wireless network), 9.2379 -using compression is likely to significantly speed up Mercurial's 9.2380 -network operations. For example, over a WAN, someone measured 9.2381 -compression as reducing the amount of time required to clone a 9.2382 -particularly large repository from 51 minutes to 17 minutes. 9.2383 -</para> 9.2384 - 9.2385 -<para>Both <command>ssh</command> and <command>plink</command> accept a <option role="cmd-opt-ssh">-C</option> 9.2386 -option which turns on compression. You can easily edit your <filename role="special"> /.hgrc</filename>\ to 9.2387 -enable compression for all of Mercurial's uses of the ssh protocol. 9.2388 -</para> 9.2389 -<programlisting> 9.2390 -<para> [ui] 9.2391 - ssh = ssh -C 9.2392 -</para> 9.2393 -</programlisting> 9.2394 - 9.2395 -<para>If you use <command>ssh</command>, you can configure it to always use 9.2396 -compression when talking to your server. To do this, edit your 9.2397 -<filename role="special">.ssh/config</filename> file (which may not yet exist), as follows. 9.2398 -</para> 9.2399 -<programlisting> 9.2400 -<para> Host hg 9.2401 - Compression yes 9.2402 - HostName hg.example.com 9.2403 -</para> 9.2404 -</programlisting> 9.2405 -<para>This defines an alias, <literal>hg</literal>. When you use it on the 9.2406 -<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-protocol 9.2407 -URL, it will cause <command>ssh</command> to connect to <literal>hg.example.com</literal> 9.2408 -and use compression. This gives you both a shorter name to type and 9.2409 -compression, each of which is a good thing in its own right. 9.2410 -</para> 9.2411 - 9.2412 -</sect2> 9.2413 -</sect1> 9.2414 -<sect1> 9.2415 -<title>Serving over HTTP using CGI</title> 9.2416 -<para>\label{sec:collab:cgi} 9.2417 -</para> 9.2418 - 9.2419 -<para>Depending on how ambitious you are, configuring Mercurial's CGI 9.2420 -interface can take anything from a few moments to several hours. 9.2421 -</para> 9.2422 - 9.2423 -<para>We'll begin with the simplest of examples, and work our way towards a 9.2424 -more complex configuration. Even for the most basic case, you're 9.2425 -almost certainly going to need to read and modify your web server's 9.2426 -configuration. 9.2427 -</para> 9.2428 - 9.2429 -<note> 9.2430 -<para> Configuring a web server is a complex, fiddly, and highly 9.2431 - system-dependent activity. I can't possibly give you instructions 9.2432 - that will cover anything like all of the cases you will encounter. 9.2433 - Please use your discretion and judgment in following the sections 9.2434 - below. Be prepared to make plenty of mistakes, and to spend a lot 9.2435 - of time reading your server's error logs. 9.2436 -</para> 9.2437 -</note> 9.2438 - 9.2439 -<sect2> 9.2440 -<title>Web server configuration checklist</title> 9.2441 - 9.2442 -<para>Before you continue, do take a few moments to check a few aspects of 9.2443 -your system's setup. 9.2444 -</para> 9.2445 - 9.2446 -<orderedlist> 9.2447 -<listitem><para>Do you have a web server installed at all? Mac OS X ships with 9.2448 - Apache, but many other systems may not have a web server installed. 9.2449 -</para> 9.2450 -</listitem> 9.2451 -<listitem><para>If you have a web server installed, is it actually running? On 9.2452 - most systems, even if one is present, it will be disabled by 9.2453 - default. 9.2454 -</para> 9.2455 -</listitem> 9.2456 -<listitem><para>Is your server configured to allow you to run CGI programs in 9.2457 - the directory where you plan to do so? Most servers default to 9.2458 - explicitly disabling the ability to run CGI programs. 9.2459 -</para> 9.2460 -</listitem></orderedlist> 9.2461 - 9.2462 -<para>If you don't have a web server installed, and don't have substantial 9.2463 -experience configuring Apache, you should consider using the 9.2464 -<literal>lighttpd</literal> web server instead of Apache. Apache has a 9.2465 -well-deserved reputation for baroque and confusing configuration. 9.2466 -While <literal>lighttpd</literal> is less capable in some ways than Apache, most 9.2467 -of these capabilities are not relevant to serving Mercurial 9.2468 -repositories. And <literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier 9.2469 -to get started with than Apache. 9.2470 -</para> 9.2471 - 9.2472 -</sect2> 9.2473 -<sect2> 9.2474 -<title>Basic CGI configuration</title> 9.2475 - 9.2476 -<para>On Unix-like systems, it's common for users to have a subdirectory 9.2477 -named something like <filename class="directory">public_html</filename> in their home directory, 9.2478 -from which they can serve up web pages. A file named <filename>foo</filename> 9.2479 -in this directory will be accessible at a URL of the form 9.2480 -<literal>http://www.example.com/\ {</literal>username/foo}. 9.2481 -</para> 9.2482 - 9.2483 -<para>To get started, find the <filename role="special">hgweb.cgi</filename> script that should be 9.2484 -present in your Mercurial installation. If you can't quickly find a 9.2485 -local copy on your system, simply download one from the master 9.2486 -Mercurial repository at 9.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>. 9.2488 -</para> 9.2489 - 9.2490 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename> 9.2491 -directory, and ensure that it's executable. 9.2492 -</para> 9.2493 -<programlisting> 9.2494 -<para> cp .../hgweb.cgi /public_html 9.2495 - chmod 755 /public_html/hgweb.cgi 9.2496 -</para> 9.2497 -</programlisting> 9.2498 -<para>The <literal>755</literal> argument to <command>chmod</command> is a little more general 9.2499 -than just making the script executable: it ensures that the script is 9.2500 -executable by anyone, and that <quote>group</quote> and <quote>other</quote> write 9.2501 -permissions are <emphasis>not</emphasis> set. If you were to leave those write 9.2502 -permissions enabled, Apache's <literal>suexec</literal> subsystem would likely 9.2503 -refuse to execute the script. In fact, <literal>suexec</literal> also insists 9.2504 -that the <emphasis>directory</emphasis> in which the script resides must not be 9.2505 -writable by others. 9.2506 -</para> 9.2507 -<programlisting> 9.2508 -<para> chmod 755 /public_html 9.2509 -</para> 9.2510 -</programlisting> 9.2511 - 9.2512 -<sect3> 9.2513 -<title>What could <emphasis>possibly</emphasis> go wrong?</title> 9.2514 -<para>\label{sec:collab:wtf} 9.2515 -</para> 9.2516 - 9.2517 -<para>Once you've copied the CGI script into place, go into a web browser, 9.2518 -and try to open the URL <ulink url="http://myhostname/ myuser/hgweb.cgi">http://myhostname/ myuser/hgweb.cgi</ulink>, 9.2519 -<emphasis>but</emphasis> brace yourself for instant failure. There's a high 9.2520 -probability that trying to visit this URL will fail, and there are 9.2521 -many possible reasons for this. In fact, you're likely to stumble 9.2522 -over almost every one of the possible errors below, so please read 9.2523 -carefully. The following are all of the problems I ran into on a 9.2524 -system running Fedora 7, with a fresh installation of Apache, and a 9.2525 -user account that I created specially to perform this exercise. 9.2526 -</para> 9.2527 - 9.2528 -<para>Your web server may have per-user directories disabled. If you're 9.2529 -using Apache, search your config file for a <literal>UserDir</literal> 9.2530 -directive. If there's none present, per-user directories will be 9.2531 -disabled. If one exists, but its value is <literal>disabled</literal>, then 9.2532 -per-user directories will be disabled. Otherwise, the string after 9.2533 -<literal>UserDir</literal> gives the name of the subdirectory that Apache will 9.2534 -look in under your home directory, for example <filename class="directory">public_html</filename>. 9.2535 -</para> 9.2536 - 9.2537 -<para>Your file access permissions may be too restrictive. The web server 9.2538 -must be able to traverse your home directory and directories under 9.2539 -your <filename class="directory">public_html</filename> directory, and read files under the latter 9.2540 -too. Here's a quick recipe to help you to make your permissions more 9.2541 -appropriate. 9.2542 -</para> 9.2543 -<programlisting> 9.2544 -<para> chmod 755 9.2545 - find /public_html -type d -print0 | xargs -0r chmod 755 9.2546 - find /public_html -type f -print0 | xargs -0r chmod 644 9.2547 -</para> 9.2548 -</programlisting> 9.2549 - 9.2550 -<para>The other possibility with permissions is that you might get a 9.2551 -completely empty window when you try to load the script. In this 9.2552 -case, it's likely that your access permissions are \emph{too 9.2553 - permissive}. Apache's <literal>suexec</literal> subsystem won't execute a 9.2554 -script that's group- or world-writable, for example. 9.2555 -</para> 9.2556 - 9.2557 -<para>Your web server may be configured to disallow execution of CGI 9.2558 -programs in your per-user web directory. Here's Apache's 9.2559 -default per-user configuration from my Fedora system. 9.2560 -</para> 9.2561 -<programlisting> 9.2562 -<para> <Directory /home/*/public_html> 9.2563 - AllowOverride FileInfo AuthConfig Limit 9.2564 - Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 9.2565 - <Limit GET POST OPTIONS> 9.2566 - Order allow,deny 9.2567 - Allow from all 9.2568 - </Limit> 9.2569 - <LimitExcept GET POST OPTIONS> 9.2570 - Order deny,allow 9.2571 - Deny from all 9.2572 - </LimitExcept> 9.2573 - </Directory> 9.2574 -</para> 9.2575 -</programlisting> 9.2576 -<para>If you find a similar-looking <literal>Directory</literal> group in your Apache 9.2577 -configuration, the directive to look at inside it is <literal>Options</literal>. 9.2578 -Add <literal>ExecCGI</literal> to the end of this list if it's missing, and 9.2579 -restart the web server. 9.2580 -</para> 9.2581 - 9.2582 -<para>If you find that Apache serves you the text of the CGI script instead 9.2583 -of executing it, you may need to either uncomment (if already present) 9.2584 -or add a directive like this. 9.2585 -</para> 9.2586 -<programlisting> 9.2587 -<para> AddHandler cgi-script .cgi 9.2588 -</para> 9.2589 -</programlisting> 9.2590 - 9.2591 -<para>The next possibility is that you might be served with a colourful 9.2592 -Python backtrace claiming that it can't import a 9.2593 -<literal>mercurial</literal>-related module. This is actually progress! The 9.2594 -server is now capable of executing your CGI script. This error is 9.2595 -only likely to occur if you're running a private installation of 9.2596 -Mercurial, instead of a system-wide version. Remember that the web 9.2597 -server runs the CGI program without any of the environment variables 9.2598 -that you take for granted in an interactive session. If this error 9.2599 -happens to you, edit your copy of <filename role="special">hgweb.cgi</filename> and follow the 9.2600 -directions inside it to correctly set your <envar>PYTHONPATH</envar> 9.2601 -environment variable. 9.2602 -</para> 9.2603 - 9.2604 -<para>Finally, you are <emphasis>certain</emphasis> to by served with another colourful 9.2605 -Python backtrace: this one will complain that it can't find 9.2606 -<filename class="directory">/path/to/repository</filename>. Edit your <filename role="special">hgweb.cgi</filename> script 9.2607 -and replace the <filename class="directory">/path/to/repository</filename> string with the complete 9.2608 -path to the repository you want to serve up. 9.2609 -</para> 9.2610 - 9.2611 -<para>At this point, when you try to reload the page, you should be 9.2612 -presented with a nice HTML view of your repository's history. Whew! 9.2613 -</para> 9.2614 - 9.2615 -</sect3> 9.2616 -<sect3> 9.2617 -<title>Configuring lighttpd</title> 9.2618 - 9.2619 -<para>To be exhaustive in my experiments, I tried configuring the 9.2620 -increasingly popular <literal>lighttpd</literal> web server to serve the same 9.2621 -repository as I described with Apache above. I had already overcome 9.2622 -all of the problems I outlined with Apache, many of which are not 9.2623 -server-specific. As a result, I was fairly sure that my file and 9.2624 -directory permissions were good, and that my <filename role="special">hgweb.cgi</filename> 9.2625 -script was properly edited. 9.2626 -</para> 9.2627 - 9.2628 -<para>Once I had Apache running, getting <literal>lighttpd</literal> to serve the 9.2629 -repository was a snap (in other words, even if you're trying to use 9.2630 -<literal>lighttpd</literal>, you should read the Apache section). I first had 9.2631 -to edit the <literal>mod_access</literal> section of its config file to enable 9.2632 -<literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of which were 9.2633 -disabled by default on my system. I then added a few lines to the end 9.2634 -of the config file, to configure these modules. 9.2635 -</para> 9.2636 -<programlisting> 9.2637 -<para> userdir.path = "public_html" 9.2638 - cgi.assign = ( ".cgi" => "" ) 9.2639 -</para> 9.2640 -</programlisting> 9.2641 -<para>With this done, <literal>lighttpd</literal> ran immediately for me. If I had 9.2642 -configured <literal>lighttpd</literal> before Apache, I'd almost certainly have 9.2643 -run into many of the same system-level configuration problems as I did 9.2644 -with Apache. However, I found <literal>lighttpd</literal> to be noticeably 9.2645 -easier to configure than Apache, even though I've used Apache for over 9.2646 -a decade, and this was my first exposure to <literal>lighttpd</literal>. 9.2647 -</para> 9.2648 - 9.2649 -</sect3> 9.2650 -</sect2> 9.2651 -<sect2> 9.2652 -<title>Sharing multiple repositories with one CGI script</title> 9.2653 - 9.2654 -<para>The <filename role="special">hgweb.cgi</filename> script only lets you publish a single 9.2655 -repository, which is an annoying restriction. If you want to publish 9.2656 -more than one without wracking yourself with multiple copies of the 9.2657 -same script, each with different names, a better choice is to use the 9.2658 -<filename role="special">hgwebdir.cgi</filename> script. 9.2659 -</para> 9.2660 - 9.2661 -<para>The procedure to configure <filename role="special">hgwebdir.cgi</filename> is only a little 9.2662 -more involved than for <filename role="special">hgweb.cgi</filename>. First, you must obtain 9.2663 -a copy of the script. If you don't have one handy, you can download a 9.2664 -copy from the master Mercurial repository at 9.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>. 9.2666 -</para> 9.2667 - 9.2668 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename> 9.2669 -directory, and ensure that it's executable. 9.2670 -</para> 9.2671 -<programlisting> 9.2672 -<para> cp .../hgwebdir.cgi /public_html 9.2673 - chmod 755 /public_html /public_html/hgwebdir.cgi 9.2674 -</para> 9.2675 -</programlisting> 9.2676 -<para>With basic configuration out of the way, try to visit 9.2677 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink> in your browser. It 9.2678 -should display an empty list of repositories. If you get a blank 9.2679 -window or error message, try walking through the list of potential 9.2680 -problems in section <xref linkend="sec:collab:wtf"/>. 9.2681 -</para> 9.2682 - 9.2683 -<para>The <filename role="special">hgwebdir.cgi</filename> script relies on an external 9.2684 -configuration file. By default, it searches for a file named 9.2685 -<filename role="special">hgweb.config</filename> in the same directory as itself. You'll need 9.2686 -to create this file, and make it world-readable. The format of the 9.2687 -file is similar to a Windows <quote>ini</quote> file, as understood by Python's 9.2688 -<literal>ConfigParser</literal> <citation>web:configparser</citation> module. 9.2689 -</para> 9.2690 - 9.2691 -<para>The easiest way to configure <filename role="special">hgwebdir.cgi</filename> is with a 9.2692 -section named <literal>collections</literal>. This will automatically publish 9.2693 -<emphasis>every</emphasis> repository under the directories you name. The section 9.2694 -should look like this: 9.2695 -</para> 9.2696 -<programlisting> 9.2697 -<para> [collections] 9.2698 - /my/root = /my/root 9.2699 -</para> 9.2700 -</programlisting> 9.2701 -<para>Mercurial interprets this by looking at the directory name on the 9.2702 -<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></quote> sign; finding 9.2703 -repositories in that directory hierarchy; and using the text on the 9.2704 -<emphasis>left</emphasis> to strip off matching text from the names it will actually 9.2705 -list in the web interface. The remaining component of a path after 9.2706 -this stripping has occurred is called a <quote>virtual path</quote>. 9.2707 -</para> 9.2708 - 9.2709 -<para>Given the example above, if we have a repository whose local path is 9.2710 -<filename class="directory">/my/root/this/repo</filename>, the CGI script will strip the leading 9.2711 -<filename class="directory">/my/root</filename> from the name, and publish the repository with a 9.2712 -virtual path of <filename class="directory">this/repo</filename>. If the base URL for our CGI 9.2713 -script is <ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink>, the complete 9.2714 -URL for that repository will be 9.2715 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi/this/repo">http://myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>. 9.2716 -</para> 9.2717 - 9.2718 -<para>If we replace <filename class="directory">/my/root</filename> on the left hand side of this example 9.2719 -with <filename class="directory">/my</filename>, then <filename role="special">hgwebdir.cgi</filename> will only strip off 9.2720 -<filename class="directory">/my</filename> from the repository name, and will give us a virtual 9.2721 -path of <filename class="directory">root/this/repo</filename> instead of <filename class="directory">this/repo</filename>. 9.2722 -</para> 9.2723 - 9.2724 -<para>The <filename role="special">hgwebdir.cgi</filename> script will recursively search each 9.2725 -directory listed in the <literal>collections</literal> section of its 9.2726 -configuration file, but it will <literal>not</literal> recurse into the 9.2727 -repositories it finds. 9.2728 -</para> 9.2729 - 9.2730 -<para>The <literal>collections</literal> mechanism makes it easy to publish many 9.2731 -repositories in a <quote>fire and forget</quote> manner. You only need to set up 9.2732 -the CGI script and configuration file one time. Afterwards, you can 9.2733 -publish or unpublish a repository at any time by simply moving it 9.2734 -into, or out of, the directory hierarchy in which you've configured 9.2735 -<filename role="special">hgwebdir.cgi</filename> to look. 9.2736 -</para> 9.2737 - 9.2738 -<sect3> 9.2739 -<title>Explicitly specifying which repositories to publish</title> 9.2740 - 9.2741 -<para>In addition to the <literal>collections</literal> mechanism, the 9.2742 -<filename role="special">hgwebdir.cgi</filename> script allows you to publish a specific list 9.2743 -of repositories. To do so, create a <literal>paths</literal> section, with 9.2744 -contents of the following form. 9.2745 -</para> 9.2746 -<programlisting> 9.2747 -<para> [paths] 9.2748 - repo1 = /my/path/to/some/repo 9.2749 - repo2 = /some/path/to/another 9.2750 -</para> 9.2751 -</programlisting> 9.2752 -<para>In this case, the virtual path (the component that will appear in a 9.2753 -URL) is on the left hand side of each definition, while the path to 9.2754 -the repository is on the right. Notice that there does not need to be 9.2755 -any relationship between the virtual path you choose and the location 9.2756 -of a repository in your filesystem. 9.2757 -</para> 9.2758 - 9.2759 -<para>If you wish, you can use both the <literal>collections</literal> and 9.2760 -<literal>paths</literal> mechanisms simultaneously in a single configuration 9.2761 -file. 9.2762 -</para> 9.2763 - 9.2764 -<note> 9.2765 -<para> If multiple repositories have the same virtual path, 9.2766 - <filename role="special">hgwebdir.cgi</filename> will not report an error. Instead, it will 9.2767 - behave unpredictably. 9.2768 -</para> 9.2769 -</note> 9.2770 - 9.2771 -</sect3> 9.2772 -</sect2> 9.2773 -<sect2> 9.2774 -<title>Downloading source archives</title> 9.2775 - 9.2776 -<para>Mercurial's web interface lets users download an archive of any 9.2777 -revision. This archive will contain a snapshot of the working 9.2778 -directory as of that revision, but it will not contain a copy of the 9.2779 -repository data. 9.2780 -</para> 9.2781 - 9.2782 -<para>By default, this feature is not enabled. To enable it, you'll need to 9.2783 -add an <envar role="rc-item-web">allow_archive</envar> item to the <literal role="rc-web">web</literal> 9.2784 -section of your <filename role="special"> /.hgrc</filename>. 9.2785 -</para> 9.2786 - 9.2787 -</sect2> 9.2788 -<sect2> 9.2789 -<title>Web configuration options</title> 9.2790 - 9.2791 -<para>Mercurial's web interfaces (the <command role="hg-cmd">hg serve</command> command, and the 9.2792 -<filename role="special">hgweb.cgi</filename> and <filename role="special">hgwebdir.cgi</filename> scripts) have a 9.2793 -number of configuration options that you can set. These belong in a 9.2794 -section named <literal role="rc-web">web</literal>. 9.2795 -</para> 9.2796 -<itemizedlist> 9.2797 -<listitem><para><envar role="rc-item-web">allow_archive</envar>: Determines which (if any) archive 9.2798 - download mechanisms Mercurial supports. If you enable this 9.2799 - feature, users of the web interface will be able to download an 9.2800 - archive of whatever revision of a repository they are viewing. 9.2801 - To enable the archive feature, this item must take the form of a 9.2802 - sequence of words drawn from the list below. 9.2803 -</para> 9.2804 -</listitem><itemizedlist> 9.2805 -<listitem><para> \item <literal>bz2</literal>: A <command>tar</command> archive, compressed using 9.2806 - <literal>bzip2</literal> compression. This has the best compression ratio, 9.2807 - but uses the most CPU time on the server. 9.2808 - \item <literal>gz</literal>: A <command>tar</command> archive, compressed using 9.2809 - <literal>gzip</literal> compression. 9.2810 - \item <literal>zip</literal>: A <command>zip</command> archive, compressed using LZW 9.2811 - compression. This format has the worst compression ratio, but is 9.2812 - widely used in the Windows world. 9.2813 -</para> 9.2814 -</listitem></itemizedlist> 9.2815 -<para> If you provide an empty list, or don't have an 9.2816 - <envar role="rc-item-web">allow_archive</envar> entry at all, this feature will be 9.2817 - disabled. Here is an example of how to enable all three supported 9.2818 - formats. 9.2819 -</para> 9.2820 -<programlisting> 9.2821 -<para> [web] 9.2822 - allow_archive = bz2 gz zip 9.2823 -</para> 9.2824 -</programlisting> 9.2825 -<listitem><para><envar role="rc-item-web">allowpull</envar>: Boolean. Determines whether the web 9.2826 - interface allows remote users to <command role="hg-cmd">hg pull</command> and <command role="hg-cmd">hg clone</command> this 9.2827 - repository over HTTP. If set to <literal>no</literal> or <literal>false</literal>, only 9.2828 - the <quote>human-oriented</quote> portion of the web interface is available. 9.2829 -</para> 9.2830 -</listitem> 9.2831 -<listitem><para><envar role="rc-item-web">contact</envar>: String. A free-form (but preferably 9.2832 - brief) string identifying the person or group in charge of the 9.2833 - repository. This often contains the name and email address of a 9.2834 - person or mailing list. It often makes sense to place this entry in 9.2835 - a repository's own <filename role="special">.hg/hgrc</filename> file, but it can make sense 9.2836 - to use in a global <filename role="special"> /.hgrc</filename>\ if every repository has a single 9.2837 - maintainer. 9.2838 -</para> 9.2839 -</listitem> 9.2840 -<listitem><para><envar role="rc-item-web">maxchanges</envar>: Integer. The default maximum number 9.2841 - of changesets to display in a single page of output. 9.2842 -</para> 9.2843 -</listitem> 9.2844 -<listitem><para><envar role="rc-item-web">maxfiles</envar>: Integer. The default maximum number 9.2845 - of modified files to display in a single page of output. 9.2846 -</para> 9.2847 -</listitem> 9.2848 -<listitem><para><envar role="rc-item-web">stripes</envar>: Integer. If the web interface displays 9.2849 - alternating <quote>stripes</quote> to make it easier to visually align rows 9.2850 - when you are looking at a table, this number controls the number of 9.2851 - rows in each stripe. 9.2852 -</para> 9.2853 -</listitem> 9.2854 -<listitem><para><envar role="rc-item-web">style</envar>: Controls the template Mercurial uses to 9.2855 - display the web interface. Mercurial ships with two web templates, 9.2856 - named <literal>default</literal> and <literal>gitweb</literal> (the latter is much more 9.2857 - visually attractive). You can also specify a custom template of 9.2858 - your own; see chapter <xref linkend="chap:template"/> for details. Here, you 9.2859 - can see how to enable the <literal>gitweb</literal> style. 9.2860 -</para> 9.2861 -</listitem><programlisting> 9.2862 -<listitem><para> [web] 9.2863 - style = gitweb 9.2864 -</para> 9.2865 -</listitem></programlisting> 9.2866 -</para> 9.2867 -</listitem> 9.2868 -<listitem><para><envar role="rc-item-web">templates</envar>: Path. The directory in which to search 9.2869 - for template files. By default, Mercurial searches in the directory 9.2870 - in which it was installed. 9.2871 -</para> 9.2872 -</listitem></itemizedlist> 9.2873 -<para>If you are using <filename role="special">hgwebdir.cgi</filename>, you can place a few 9.2874 -configuration items in a <literal role="rc-web">web</literal> section of the 9.2875 -<filename role="special">hgweb.config</filename> file instead of a <filename role="special"> /.hgrc</filename>\ file, for 9.2876 -convenience. These items are <envar role="rc-item-web">motd</envar> and 9.2877 -<envar role="rc-item-web">style</envar>. 9.2878 -</para> 9.2879 - 9.2880 -<sect3> 9.2881 -<title>Options specific to an individual repository</title> 9.2882 - 9.2883 -<para>A few <literal role="rc-web">web</literal> configuration items ought to be placed in a 9.2884 -repository's local <filename role="special">.hg/hgrc</filename>, rather than a user's or 9.2885 -global <filename role="special"> /.hgrc</filename>. 9.2886 -</para> 9.2887 -<itemizedlist> 9.2888 -<listitem><para><envar role="rc-item-web">description</envar>: String. A free-form (but preferably 9.2889 - brief) string that describes the contents or purpose of the 9.2890 - repository. 9.2891 -</para> 9.2892 -</listitem> 9.2893 -<listitem><para><envar role="rc-item-web">name</envar>: String. The name to use for the repository 9.2894 - in the web interface. This overrides the default name, which is the 9.2895 - last component of the repository's path. 9.2896 -</para> 9.2897 -</listitem></itemizedlist> 9.2898 - 9.2899 -</sect3> 9.2900 -<sect3> 9.2901 -<title>Options specific to the <command role="hg-cmd">hg serve</command> command</title> 9.2902 - 9.2903 -<para>Some of the items in the <literal role="rc-web">web</literal> section of a <filename role="special"> /.hgrc</filename>\ file are 9.2904 -only for use with the <command role="hg-cmd">hg serve</command> command. 9.2905 -</para> 9.2906 -<itemizedlist> 9.2907 -<listitem><para><envar role="rc-item-web">accesslog</envar>: Path. The name of a file into which to 9.2908 - write an access log. By default, the <command role="hg-cmd">hg serve</command> command writes 9.2909 - this information to standard output, not to a file. Log entries are 9.2910 - written in the standard <quote>combined</quote> file format used by almost all 9.2911 - web servers. 9.2912 -</para> 9.2913 -</listitem> 9.2914 -<listitem><para><envar role="rc-item-web">address</envar>: String. The local address on which the 9.2915 - server should listen for incoming connections. By default, the 9.2916 - server listens on all addresses. 9.2917 -</para> 9.2918 -</listitem> 9.2919 -<listitem><para><envar role="rc-item-web">errorlog</envar>: Path. The name of a file into which to 9.2920 - write an error log. By default, the <command role="hg-cmd">hg serve</command> command writes this 9.2921 - information to standard error, not to a file. 9.2922 -</para> 9.2923 -</listitem> 9.2924 -<listitem><para><envar role="rc-item-web">ipv6</envar>: Boolean. Whether to use the IPv6 protocol. 9.2925 - By default, IPv6 is not used. 9.2926 -</para> 9.2927 -</listitem> 9.2928 -<listitem><para><envar role="rc-item-web">port</envar>: Integer. The TCP port number on which the 9.2929 - server should listen. The default port number used is 8000. 9.2930 -</para> 9.2931 -</listitem></itemizedlist> 9.2932 - 9.2933 -<para>\subsubsection{Choosing the right <filename role="special"> /.hgrc</filename>\ file to add <literal role="rc-web">web</literal> 9.2934 - items to} 9.2935 -</para> 9.2936 - 9.2937 -<para>It is important to remember that a web server like Apache or 9.2938 -<literal>lighttpd</literal> will run under a user ID that is different to yours. 9.2939 -CGI scripts run by your server, such as <filename role="special">hgweb.cgi</filename>, will 9.2940 -usually also run under that user ID. 9.2941 -</para> 9.2942 - 9.2943 -<para>If you add <literal role="rc-web">web</literal> items to your own personal <filename role="special"> /.hgrc</filename>\ file, CGI 9.2944 -scripts won't read that <filename role="special"> /.hgrc</filename>\ file. Those settings will thus only 9.2945 -affect the behaviour of the <command role="hg-cmd">hg serve</command> command when you run it. To 9.2946 -cause CGI scripts to see your settings, either create a <filename role="special"> /.hgrc</filename>\ file in 9.2947 -the home directory of the user ID that runs your web server, or add 9.2948 -those settings to a system-wide <filename role="special"> /.hgrc</filename>\ file. 9.2949 -</para> 9.2950 - 9.2951 - 9.2952 -</sect3> 9.2953 -</sect2> 9.2954 -</sect1> 9.2955 + </sect2> 9.2956 + </sect1> 9.2957 </chapter> 9.2958 9.2959 <!-- 9.2960 local variables: 9.2961 sgml-parent-document: ("00book.xml" "book" "chapter") 9.2962 end: 9.2963 ---> 9.2964 \ No newline at end of file 9.2965 +-->
10.1 --- a/fr/ch07-filenames.xml Sat Sep 12 17:58:26 2009 +0200 10.2 +++ b/fr/ch07-filenames.xml Sat Sep 12 17:58:56 2009 +0200 10.3 @@ -1,388 +1,451 @@ 10.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 10.5 10.6 -<chapter> 10.7 -<title>File names and pattern matching</title> 10.8 -<para>\label{chap:names}</para> 10.9 - 10.10 -<para>Mercurial provides mechanisms that let you work with file names in a 10.11 -consistent and expressive way.</para> 10.12 - 10.13 -<sect1> 10.14 -<title>Simple file naming</title> 10.15 - 10.16 -<para>Mercurial uses a unified piece of machinery <quote>under the hood</quote> to 10.17 -handle file names. Every command behaves uniformly with respect to 10.18 -file names. The way in which commands work with file names is as 10.19 -follows.</para> 10.20 - 10.21 -<para>If you explicitly name real files on the command line, Mercurial works 10.22 -with exactly those files, as you would expect. 10.23 -<!-- &interaction.filenames.files; --></para> 10.24 - 10.25 -<para>When you provide a directory name, Mercurial will interpret this as 10.26 -<quote>operate on every file in this directory and its subdirectories</quote>. 10.27 -Mercurial traverses the files and subdirectories in a directory in 10.28 -alphabetical order. When it encounters a subdirectory, it will 10.29 -traverse that subdirectory before continuing with the current 10.30 -directory. 10.31 -<!-- &interaction.filenames.dirs; --></para> 10.32 - 10.33 -</sect1> 10.34 -<sect1> 10.35 -<title>Running commands without any file names</title> 10.36 - 10.37 -<para>Mercurial's commands that work with file names have useful default 10.38 -behaviours when you invoke them without providing any file names or 10.39 -patterns. What kind of behaviour you should expect depends on what 10.40 -the command does. Here are a few rules of thumb you can use to 10.41 -predict what a command is likely to do if you don't give it any names 10.42 -to work with.</para> 10.43 -<itemizedlist> 10.44 -<listitem><para>Most commands will operate on the entire working directory. 10.45 - This is what the <command role="hg-cmd">hg add</command> command does, for example.</para> 10.46 -</listitem> 10.47 -<listitem><para>If the command has effects that are difficult or impossible to 10.48 - reverse, it will force you to explicitly provide at least one name 10.49 - or pattern (see below). This protects you from accidentally 10.50 - deleting files by running <command role="hg-cmd">hg remove</command> with no arguments, for 10.51 - example.</para> 10.52 -</listitem></itemizedlist> 10.53 - 10.54 -<para>It's easy to work around these default behaviours if they don't suit 10.55 -you. If a command normally operates on the whole working directory, 10.56 -you can invoke it on just the current directory and its subdirectories 10.57 -by giving it the name <quote><filename class="directory">.</filename></quote>. 10.58 -<!-- &interaction.filenames.wdir-subdir; --> 10.59 -</para> 10.60 - 10.61 -<para>Along the same lines, some commands normally print file names relative 10.62 -to the root of the repository, even if you're invoking them from a 10.63 -subdirectory. Such a command will print file names relative to your 10.64 -subdirectory if you give it explicit names. Here, we're going to run 10.65 -<command role="hg-cmd">hg status</command> from a subdirectory, and get it to operate on the 10.66 -entire working directory while printing file names relative to our 10.67 -subdirectory, by passing it the output of the <command role="hg-cmd">hg root</command> command. 10.68 -<!-- &interaction.filenames.wdir-relname; --> 10.69 -</para> 10.70 - 10.71 -</sect1> 10.72 -<sect1> 10.73 -<title>Telling you what's going on</title> 10.74 - 10.75 -<para>The <command role="hg-cmd">hg add</command> example in the preceding section illustrates something 10.76 -else that's helpful about Mercurial commands. If a command operates 10.77 -on a file that you didn't name explicitly on the command line, it will 10.78 -usually print the name of the file, so that you will not be surprised 10.79 -what's going on. 10.80 -</para> 10.81 - 10.82 -<para>The principle here is of <emphasis>least surprise</emphasis>. If you've exactly 10.83 -named a file on the command line, there's no point in repeating it 10.84 -back at you. If Mercurial is acting on a file <emphasis>implicitly</emphasis>, 10.85 -because you provided no names, or a directory, or a pattern (see 10.86 -below), it's safest to tell you what it's doing. 10.87 -</para> 10.88 - 10.89 -<para>For commands that behave this way, you can silence them using the 10.90 -<option role="hg-opt-global">-q</option> option. You can also get them to print the name of every 10.91 -file, even those you've named explicitly, using the <option role="hg-opt-global">-v</option> 10.92 -option. 10.93 -</para> 10.94 - 10.95 -</sect1> 10.96 -<sect1> 10.97 -<title>Using patterns to identify files</title> 10.98 - 10.99 -<para>In addition to working with file and directory names, Mercurial lets 10.100 -you use <emphasis>patterns</emphasis> to identify files. Mercurial's pattern 10.101 -handling is expressive. 10.102 -</para> 10.103 - 10.104 -<para>On Unix-like systems (Linux, MacOS, etc.), the job of matching file 10.105 -names to patterns normally falls to the shell. On these systems, you 10.106 -must explicitly tell Mercurial that a name is a pattern. On Windows, 10.107 -the shell does not expand patterns, so Mercurial will automatically 10.108 -identify names that are patterns, and expand them for you. 10.109 -</para> 10.110 - 10.111 -<para>To provide a pattern in place of a regular name on the command line, 10.112 -the mechanism is simple: 10.113 -</para> 10.114 -<programlisting> 10.115 -<para> syntax:patternbody 10.116 -</para> 10.117 +<chapter id="chap:names"> 10.118 + <?dbhtml filename="file-names-and-pattern-matching.html"?> 10.119 + <title>File names and pattern matching</title> 10.120 + 10.121 + <para id="x_543">Mercurial provides mechanisms that let you work with file 10.122 + names in a consistent and expressive way.</para> 10.123 + 10.124 + <sect1> 10.125 + <title>Simple file naming</title> 10.126 + 10.127 + <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the 10.128 + hood</quote> to handle file names. Every command behaves 10.129 + uniformly with respect to file names. The way in which commands 10.130 + work with file names is as follows.</para> 10.131 + 10.132 + <para id="x_545">If you explicitly name real files on the command line, 10.133 + Mercurial works with exactly those files, as you would expect. 10.134 + &interaction.filenames.files;</para> 10.135 + 10.136 + <para id="x_546">When you provide a directory name, Mercurial will interpret 10.137 + this as <quote>operate on every file in this directory and its 10.138 + subdirectories</quote>. Mercurial traverses the files and 10.139 + subdirectories in a directory in alphabetical order. When it 10.140 + encounters a subdirectory, it will traverse that subdirectory 10.141 + before continuing with the current directory.</para> 10.142 + 10.143 + &interaction.filenames.dirs; 10.144 + </sect1> 10.145 + 10.146 + <sect1> 10.147 + <title>Running commands without any file names</title> 10.148 + 10.149 + <para id="x_547">Mercurial's commands that work with file names have useful 10.150 + default behaviors when you invoke them without providing any 10.151 + file names or patterns. What kind of behavior you should 10.152 + expect depends on what the command does. Here are a few rules 10.153 + of thumb you can use to predict what a command is likely to do 10.154 + if you don't give it any names to work with.</para> 10.155 + <itemizedlist> 10.156 + <listitem><para id="x_548">Most commands will operate on the entire working 10.157 + directory. This is what the <command role="hg-cmd">hg 10.158 + add</command> command does, for example.</para> 10.159 + </listitem> 10.160 + <listitem><para id="x_549">If the command has effects that are difficult or 10.161 + impossible to reverse, it will force you to explicitly 10.162 + provide at least one name or pattern (see below). This 10.163 + protects you from accidentally deleting files by running 10.164 + <command role="hg-cmd">hg remove</command> with no 10.165 + arguments, for example.</para> 10.166 + </listitem></itemizedlist> 10.167 + 10.168 + <para id="x_54a">It's easy to work around these default behaviors if they 10.169 + don't suit you. If a command normally operates on the whole 10.170 + working directory, you can invoke it on just the current 10.171 + directory and its subdirectories by giving it the name 10.172 + <quote><filename class="directory">.</filename></quote>.</para> 10.173 + 10.174 + &interaction.filenames.wdir-subdir; 10.175 + 10.176 + <para id="x_54b">Along the same lines, some commands normally print file 10.177 + names relative to the root of the repository, even if you're 10.178 + invoking them from a subdirectory. Such a command will print 10.179 + file names relative to your subdirectory if you give it explicit 10.180 + names. Here, we're going to run <command role="hg-cmd">hg 10.181 + status</command> from a subdirectory, and get it to operate on 10.182 + the entire working directory while printing file names relative 10.183 + to our subdirectory, by passing it the output of the <command 10.184 + role="hg-cmd">hg root</command> command.</para> 10.185 + 10.186 + &interaction.filenames.wdir-relname; 10.187 + </sect1> 10.188 + 10.189 + <sect1> 10.190 + <title>Telling you what's going on</title> 10.191 + 10.192 + <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the 10.193 + preceding section illustrates something else that's helpful 10.194 + about Mercurial commands. If a command operates on a file that 10.195 + you didn't name explicitly on the command line, it will usually 10.196 + print the name of the file, so that you will not be surprised 10.197 + what's going on.</para> 10.198 + 10.199 + <para id="x_54d">The principle here is of <emphasis>least 10.200 + surprise</emphasis>. If you've exactly named a file on the 10.201 + command line, there's no point in repeating it back at you. If 10.202 + Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g. 10.203 + because you provided no names, or a directory, or a pattern (see 10.204 + below), it is safest to tell you what files it's operating on.</para> 10.205 + 10.206 + <para id="x_54e">For commands that behave this way, you can silence them 10.207 + using the <option role="hg-opt-global">-q</option> option. You 10.208 + can also get them to print the name of every file, even those 10.209 + you've named explicitly, using the <option 10.210 + role="hg-opt-global">-v</option> option.</para> 10.211 + </sect1> 10.212 + 10.213 + <sect1> 10.214 + <title>Using patterns to identify files</title> 10.215 + 10.216 + <para id="x_54f">In addition to working with file and directory names, 10.217 + Mercurial lets you use <emphasis>patterns</emphasis> to identify 10.218 + files. Mercurial's pattern handling is expressive.</para> 10.219 + 10.220 + <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of 10.221 + matching file names to patterns normally falls to the shell. On 10.222 + these systems, you must explicitly tell Mercurial that a name is 10.223 + a pattern. On Windows, the shell does not expand patterns, so 10.224 + Mercurial will automatically identify names that are patterns, 10.225 + and expand them for you.</para> 10.226 + 10.227 + <para id="x_551">To provide a pattern in place of a regular name on the 10.228 + command line, the mechanism is simple:</para> 10.229 + <programlisting>syntax:patternbody</programlisting> 10.230 + <para id="x_552">That is, a pattern is identified by a short text string that 10.231 + says what kind of pattern this is, followed by a colon, followed 10.232 + by the actual pattern.</para> 10.233 + 10.234 + <para id="x_553">Mercurial supports two kinds of pattern syntax. The most 10.235 + frequently used is called <literal>glob</literal>; this is the 10.236 + same kind of pattern matching used by the Unix shell, and should 10.237 + be familiar to Windows command prompt users, too.</para> 10.238 + 10.239 + <para id="x_554">When Mercurial does automatic pattern matching on Windows, 10.240 + it uses <literal>glob</literal> syntax. You can thus omit the 10.241 + <quote><literal>glob:</literal></quote> prefix on Windows, but 10.242 + it's safe to use it, too.</para> 10.243 + 10.244 + <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets 10.245 + you specify patterns using regular expressions, also known as 10.246 + regexps.</para> 10.247 + 10.248 + <para id="x_556">By the way, in the examples that follow, notice that I'm 10.249 + careful to wrap all of my patterns in quote characters, so that 10.250 + they won't get expanded by the shell before Mercurial sees 10.251 + them.</para> 10.252 + 10.253 + <sect2> 10.254 + <title>Shell-style <literal>glob</literal> patterns</title> 10.255 + 10.256 + <para id="x_557">This is an overview of the kinds of patterns you can use 10.257 + when you're matching on glob patterns.</para> 10.258 + 10.259 + <para id="x_558">The <quote><literal>*</literal></quote> character matches 10.260 + any string, within a single directory.</para> 10.261 + 10.262 + &interaction.filenames.glob.star; 10.263 + 10.264 + <para id="x_559">The <quote><literal>**</literal></quote> pattern matches 10.265 + any string, and crosses directory boundaries. It's not a 10.266 + standard Unix glob token, but it's accepted by several popular 10.267 + Unix shells, and is very useful.</para> 10.268 + 10.269 + &interaction.filenames.glob.starstar; 10.270 + 10.271 + <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches 10.272 + any single character.</para> 10.273 + 10.274 + &interaction.filenames.glob.question; 10.275 + 10.276 + <para id="x_55b">The <quote><literal>[</literal></quote> character begins a 10.277 + <emphasis>character class</emphasis>. This matches any single 10.278 + character within the class. The class ends with a 10.279 + <quote><literal>]</literal></quote> character. A class may 10.280 + contain multiple <emphasis>range</emphasis>s of the form 10.281 + <quote><literal>a-f</literal></quote>, which is shorthand for 10.282 + <quote><literal>abcdef</literal></quote>.</para> 10.283 + 10.284 + &interaction.filenames.glob.range; 10.285 + 10.286 + <para id="x_55c">If the first character after the 10.287 + <quote><literal>[</literal></quote> in a character class is a 10.288 + <quote><literal>!</literal></quote>, it 10.289 + <emphasis>negates</emphasis> the class, making it match any 10.290 + single character not in the class.</para> 10.291 + 10.292 + <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of 10.293 + subpatterns, where the whole group matches if any subpattern 10.294 + in the group matches. The <quote><literal>,</literal></quote> 10.295 + character separates subpatterns, and 10.296 + <quote><literal>}</literal></quote> ends the group.</para> 10.297 + 10.298 + &interaction.filenames.glob.group; 10.299 + 10.300 + <sect3> 10.301 + <title>Watch out!</title> 10.302 + 10.303 + <para id="x_55e">Don't forget that if you want to match a pattern in any 10.304 + directory, you should not be using the 10.305 + <quote><literal>*</literal></quote> match-any token, as this 10.306 + will only match within one directory. Instead, use the 10.307 + <quote><literal>**</literal></quote> token. This small 10.308 + example illustrates the difference between the two.</para> 10.309 + 10.310 + &interaction.filenames.glob.star-starstar; 10.311 + </sect3> 10.312 + </sect2> 10.313 + 10.314 + <sect2> 10.315 + <title>Regular expression matching with <literal>re</literal> 10.316 + patterns</title> 10.317 + 10.318 + <para id="x_55f">Mercurial accepts the same regular expression syntax as 10.319 + the Python programming language (it uses Python's regexp 10.320 + engine internally). This is based on the Perl language's 10.321 + regexp syntax, which is the most popular dialect in use (it's 10.322 + also used in Java, for example).</para> 10.323 + 10.324 + <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail 10.325 + here, as regexps are not often used. Perl-style regexps are 10.326 + in any case already exhaustively documented on a multitude of 10.327 + web sites, and in many books. Instead, I will focus here on a 10.328 + few things you should know if you find yourself needing to use 10.329 + regexps with Mercurial.</para> 10.330 + 10.331 + <para id="x_561">A regexp is matched against an entire file name, relative 10.332 + to the root of the repository. In other words, even if you're 10.333 + already in subbdirectory <filename 10.334 + class="directory">foo</filename>, if you want to match files 10.335 + under this directory, your pattern must start with 10.336 + <quote><literal>foo/</literal></quote>.</para> 10.337 + 10.338 + <para id="x_562">One thing to note, if you're familiar with Perl-style 10.339 + regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 10.340 + That is, a regexp starts matching against the beginning of a 10.341 + string; it doesn't look for a match anywhere within the 10.342 + string. To match anywhere in a string, start your pattern 10.343 + with <quote><literal>.*</literal></quote>.</para> 10.344 + </sect2> 10.345 + </sect1> 10.346 + 10.347 + <sect1> 10.348 + <title>Filtering files</title> 10.349 + 10.350 + <para id="x_563">Not only does Mercurial give you a variety of ways to 10.351 + specify files; it lets you further winnow those files using 10.352 + <emphasis>filters</emphasis>. Commands that work with file 10.353 + names accept two filtering options.</para> 10.354 + <itemizedlist> 10.355 + <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or 10.356 + <option role="hg-opt-global">--include</option>, lets you 10.357 + specify a pattern that file names must match in order to be 10.358 + processed.</para> 10.359 + </listitem> 10.360 + <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or 10.361 + <option role="hg-opt-global">--exclude</option>, gives you a 10.362 + way to <emphasis>avoid</emphasis> processing files, if they 10.363 + match this pattern.</para> 10.364 + </listitem></itemizedlist> 10.365 + <para id="x_566">You can provide multiple <option 10.366 + role="hg-opt-global">-I</option> and <option 10.367 + role="hg-opt-global">-X</option> options on the command line, 10.368 + and intermix them as you please. Mercurial interprets the 10.369 + patterns you provide using glob syntax by default (but you can 10.370 + use regexps if you need to).</para> 10.371 + 10.372 + <para id="x_567">You can read a <option role="hg-opt-global">-I</option> 10.373 + filter as <quote>process only the files that match this 10.374 + filter</quote>.</para> 10.375 + 10.376 + &interaction.filenames.filter.include; 10.377 + 10.378 + <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best 10.379 + read as <quote>process only the files that don't match this 10.380 + pattern</quote>.</para> 10.381 + 10.382 + &interaction.filenames.filter.exclude; 10.383 + </sect1> 10.384 + 10.385 + <sect1> 10.386 + <title>Permanently ignoring unwanted files and directories</title> 10.387 + 10.388 + <para id="x_569">When you create a new repository, the chances are 10.389 + that over time it will grow to contain files that ought to 10.390 + <emphasis>not</emphasis> be managed by Mercurial, but which you 10.391 + don't want to see listed every time you run <command>hg 10.392 + status</command>. For instance, <quote>build products</quote> 10.393 + are files that are created as part of a build but which should 10.394 + not be managed by a revision control system. The most common 10.395 + build products are output files produced by software tools such 10.396 + as compilers. As another example, many text editors litter a 10.397 + directory with lock files, temporary working files, and backup 10.398 + files, which it also makes no sense to manage.</para> 10.399 + 10.400 + <para id="x_6b4">To have Mercurial permanently ignore such files, create a 10.401 + file named <filename>.hgignore</filename> in the root of your 10.402 + repository. You <emphasis>should</emphasis> <command>hg 10.403 + add</command> this file so that it gets tracked with the rest of 10.404 + your repository contents, since your collaborators will probably 10.405 + find it useful too.</para> 10.406 + 10.407 + <para id="x_6b5">By default, the <filename>.hgignore</filename> file should 10.408 + contain a list of regular expressions, one per line. Empty 10.409 + lines are skipped. Most people prefer to describe the files they 10.410 + want to ignore using the <quote>glob</quote> syntax that we 10.411 + described above, so a typical <filename>.hgignore</filename> 10.412 + file will start with this directive:</para> 10.413 + 10.414 + <programlisting>syntax: glob</programlisting> 10.415 + 10.416 + <para id="x_6b6">This tells Mercurial to interpret the lines that follow as 10.417 + glob patterns, not regular expressions.</para> 10.418 + 10.419 + <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename> 10.420 + file.</para> 10.421 + 10.422 + <programlisting>syntax: glob 10.423 +# This line is a comment, and will be skipped. 10.424 +# Empty lines are skipped too. 10.425 + 10.426 +# Backup files left behind by the Emacs editor. 10.427 +*~ 10.428 + 10.429 +# Lock files used by the Emacs editor. 10.430 +# Notice that the "#" character is quoted with a backslash. 10.431 +# This prevents it from being interpreted as starting a comment. 10.432 +.\#* 10.433 + 10.434 +# Temporary files used by the vim editor. 10.435 +.*.swp 10.436 + 10.437 +# A hidden file created by the Mac OS X Finder. 10.438 +.DS_Store 10.439 </programlisting> 10.440 -<para>That is, a pattern is identified by a short text string that says what 10.441 -kind of pattern this is, followed by a colon, followed by the actual 10.442 -pattern. 10.443 -</para> 10.444 - 10.445 -<para>Mercurial supports two kinds of pattern syntax. The most frequently 10.446 -used is called <literal>glob</literal>; this is the same kind of pattern 10.447 -matching used by the Unix shell, and should be familiar to Windows 10.448 -command prompt users, too. 10.449 -</para> 10.450 - 10.451 -<para>When Mercurial does automatic pattern matching on Windows, it uses 10.452 -<literal>glob</literal> syntax. You can thus omit the <quote><literal>glob:</literal></quote> prefix 10.453 -on Windows, but it's safe to use it, too. 10.454 -</para> 10.455 - 10.456 -<para>The <literal>re</literal> syntax is more powerful; it lets you specify patterns 10.457 -using regular expressions, also known as regexps. 10.458 -</para> 10.459 - 10.460 -<para>By the way, in the examples that follow, notice that I'm careful to 10.461 -wrap all of my patterns in quote characters, so that they won't get 10.462 -expanded by the shell before Mercurial sees them. 10.463 -</para> 10.464 - 10.465 -<sect2> 10.466 -<title>Shell-style <literal>glob</literal> patterns</title> 10.467 - 10.468 -<para>This is an overview of the kinds of patterns you can use when you're 10.469 -matching on glob patterns. 10.470 -</para> 10.471 - 10.472 -<para>The <quote><literal>*</literal></quote> character matches any string, within a single 10.473 -directory. 10.474 -<!-- &interaction.filenames.glob.star; --> 10.475 -</para> 10.476 - 10.477 -<para>The <quote><literal>**</literal></quote> pattern matches any string, and crosses directory 10.478 -boundaries. It's not a standard Unix glob token, but it's accepted by 10.479 -several popular Unix shells, and is very useful. 10.480 -<!-- &interaction.filenames.glob.starstar; --> 10.481 -</para> 10.482 - 10.483 -<para>The <quote><literal>?</literal></quote> pattern matches any single character. 10.484 -<!-- &interaction.filenames.glob.question; --> 10.485 -</para> 10.486 - 10.487 -<para>The <quote><literal>[</literal></quote> character begins a <emphasis>character class</emphasis>. This 10.488 -matches any single character within the class. The class ends with a 10.489 -<quote><literal>]</literal></quote> character. A class may contain multiple <emphasis>range</emphasis>s 10.490 -of the form <quote><literal>a-f</literal></quote>, which is shorthand for 10.491 -<quote><literal>abcdef</literal></quote>. 10.492 -<!-- &interaction.filenames.glob.range; --> 10.493 -If the first character after the <quote><literal>[</literal></quote> in a character class 10.494 -is a <quote><literal>!</literal></quote>, it <emphasis>negates</emphasis> the class, making it match any 10.495 -single character not in the class. 10.496 -</para> 10.497 - 10.498 -<para>A <quote><literal>{</literal></quote> begins a group of subpatterns, where the whole group 10.499 -matches if any subpattern in the group matches. The <quote><literal>,</literal></quote> 10.500 -character separates subpatterns, and <quote>\texttt{}}</quote> ends the group. 10.501 -<!-- &interaction.filenames.glob.group; --> 10.502 -</para> 10.503 - 10.504 -<sect3> 10.505 -<title>Watch out!</title> 10.506 - 10.507 -<para>Don't forget that if you want to match a pattern in any directory, you 10.508 -should not be using the <quote><literal>*</literal></quote> match-any token, as this will 10.509 -only match within one directory. Instead, use the <quote><literal>**</literal></quote> 10.510 -token. This small example illustrates the difference between the two. 10.511 -<!-- &interaction.filenames.glob.star-starstar; --> 10.512 -</para> 10.513 - 10.514 -</sect3> 10.515 -</sect2> 10.516 -<sect2> 10.517 -<title>Regular expression matching with <literal>re</literal> patterns</title> 10.518 - 10.519 -<para>Mercurial accepts the same regular expression syntax as the Python 10.520 -programming language (it uses Python's regexp engine internally). 10.521 -This is based on the Perl language's regexp syntax, which is the most 10.522 -popular dialect in use (it's also used in Java, for example). 10.523 -</para> 10.524 - 10.525 -<para>I won't discuss Mercurial's regexp dialect in any detail here, as 10.526 -regexps are not often used. Perl-style regexps are in any case 10.527 -already exhaustively documented on a multitude of web sites, and in 10.528 -many books. Instead, I will focus here on a few things you should 10.529 -know if you find yourself needing to use regexps with Mercurial. 10.530 -</para> 10.531 - 10.532 -<para>A regexp is matched against an entire file name, relative to the root 10.533 -of the repository. In other words, even if you're already in 10.534 -subbdirectory <filename class="directory">foo</filename>, if you want to match files under this 10.535 -directory, your pattern must start with <quote><literal>foo/</literal></quote>. 10.536 -</para> 10.537 - 10.538 -<para>One thing to note, if you're familiar with Perl-style regexps, is that 10.539 -Mercurial's are <emphasis>rooted</emphasis>. That is, a regexp starts matching 10.540 -against the beginning of a string; it doesn't look for a match 10.541 -anywhere within the string. To match anywhere in a string, start 10.542 -your pattern with <quote><literal>.*</literal></quote>. 10.543 -</para> 10.544 - 10.545 -</sect2> 10.546 -</sect1> 10.547 -<sect1> 10.548 -<title>Filtering files</title> 10.549 - 10.550 -<para>Not only does Mercurial give you a variety of ways to specify files; 10.551 -it lets you further winnow those files using <emphasis>filters</emphasis>. Commands 10.552 -that work with file names accept two filtering options. 10.553 -</para> 10.554 -<itemizedlist> 10.555 -<listitem><para><option role="hg-opt-global">-I</option>, or <option role="hg-opt-global">--include</option>, lets you specify a pattern 10.556 - that file names must match in order to be processed. 10.557 -</para> 10.558 -</listitem> 10.559 -<listitem><para><option role="hg-opt-global">-X</option>, or <option role="hg-opt-global">--exclude</option>, gives you a way to 10.560 - <emphasis>avoid</emphasis> processing files, if they match this pattern. 10.561 -</para> 10.562 -</listitem></itemizedlist> 10.563 -<para>You can provide multiple <option role="hg-opt-global">-I</option> and <option role="hg-opt-global">-X</option> options on the 10.564 -command line, and intermix them as you please. Mercurial interprets 10.565 -the patterns you provide using glob syntax by default (but you can use 10.566 -regexps if you need to). 10.567 -</para> 10.568 - 10.569 -<para>You can read a <option role="hg-opt-global">-I</option> filter as <quote>process only the files that 10.570 -match this filter</quote>. 10.571 -<!-- &interaction.filenames.filter.include; --> 10.572 -The <option role="hg-opt-global">-X</option> filter is best read as <quote>process only the files that 10.573 -don't match this pattern</quote>. 10.574 -<!-- &interaction.filenames.filter.exclude; --> 10.575 -</para> 10.576 - 10.577 -</sect1> 10.578 -<sect1> 10.579 -<title>Ignoring unwanted files and directories</title> 10.580 - 10.581 -<para>XXX. 10.582 -</para> 10.583 - 10.584 -</sect1> 10.585 -<sect1> 10.586 -<title>Case sensitivity</title> 10.587 -<para>\label{sec:names:case} 10.588 -</para> 10.589 - 10.590 -<para>If you're working in a mixed development environment that contains 10.591 -both Linux (or other Unix) systems and Macs or Windows systems, you 10.592 -should keep in the back of your mind the knowledge that they treat the 10.593 -case (<quote>N</quote> versus <quote>n</quote>) of file names in incompatible ways. This is 10.594 -not very likely to affect you, and it's easy to deal with if it does, 10.595 -but it could surprise you if you don't know about it. 10.596 -</para> 10.597 - 10.598 -<para>Operating systems and filesystems differ in the way they handle the 10.599 -<emphasis>case</emphasis> of characters in file and directory names. There are 10.600 -three common ways to handle case in names. 10.601 -</para> 10.602 -<itemizedlist> 10.603 -<listitem><para>Completely case insensitive. Uppercase and lowercase versions 10.604 - of a letter are treated as identical, both when creating a file and 10.605 - during subsequent accesses. This is common on older DOS-based 10.606 - systems. 10.607 -</para> 10.608 -</listitem> 10.609 -<listitem><para>Case preserving, but insensitive. When a file or directory is 10.610 - created, the case of its name is stored, and can be retrieved and 10.611 - displayed by the operating system. When an existing file is being 10.612 - looked up, its case is ignored. This is the standard arrangement on 10.613 - Windows and MacOS. The names <filename>foo</filename> and <filename>FoO</filename> 10.614 - identify the same file. This treatment of uppercase and lowercase 10.615 - letters as interchangeable is also referred to as \emph{case 10.616 - folding}. 10.617 -</para> 10.618 -</listitem> 10.619 -<listitem><para>Case sensitive. The case of a name is significant at all times. 10.620 - The names <filename>foo</filename> and {FoO} identify different files. This 10.621 - is the way Linux and Unix systems normally work. 10.622 -</para> 10.623 -</listitem></itemizedlist> 10.624 - 10.625 -<para>On Unix-like systems, it is possible to have any or all of the above 10.626 -ways of handling case in action at once. For example, if you use a 10.627 -USB thumb drive formatted with a FAT32 filesystem on a Linux system, 10.628 -Linux will handle names on that filesystem in a case preserving, but 10.629 -insensitive, way. 10.630 -</para> 10.631 - 10.632 -<sect2> 10.633 -<title>Safe, portable repository storage</title> 10.634 - 10.635 -<para>Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>. It 10.636 -translates file names so that they can be safely stored on both case 10.637 -sensitive and case insensitive filesystems. This means that you can 10.638 -use normal file copying tools to transfer a Mercurial repository onto, 10.639 -for example, a USB thumb drive, and safely move that drive and 10.640 -repository back and forth between a Mac, a PC running Windows, and a 10.641 -Linux box. 10.642 -</para> 10.643 - 10.644 -</sect2> 10.645 -<sect2> 10.646 -<title>Detecting case conflicts</title> 10.647 - 10.648 -<para>When operating in the working directory, Mercurial honours the naming 10.649 -policy of the filesystem where the working directory is located. If 10.650 -the filesystem is case preserving, but insensitive, Mercurial will 10.651 -treat names that differ only in case as the same. 10.652 -</para> 10.653 - 10.654 -<para>An important aspect of this approach is that it is possible to commit 10.655 -a changeset on a case sensitive (typically Linux or Unix) filesystem 10.656 -that will cause trouble for users on case insensitive (usually Windows 10.657 -and MacOS) users. If a Linux user commits changes to two files, one 10.658 -named <filename>myfile.c</filename> and the other named <filename>MyFile.C</filename>, 10.659 -they will be stored correctly in the repository. And in the working 10.660 -directories of other Linux users, they will be correctly represented 10.661 -as separate files. 10.662 -</para> 10.663 - 10.664 -<para>If a Windows or Mac user pulls this change, they will not initially 10.665 -have a problem, because Mercurial's repository storage mechanism is 10.666 -case safe. However, once they try to <command role="hg-cmd">hg update</command> the working 10.667 -directory to that changeset, or <command role="hg-cmd">hg merge</command> with that changeset, 10.668 -Mercurial will spot the conflict between the two file names that the 10.669 -filesystem would treat as the same, and forbid the update or merge 10.670 -from occurring. 10.671 -</para> 10.672 - 10.673 -</sect2> 10.674 -<sect2> 10.675 -<title>Fixing a case conflict</title> 10.676 - 10.677 -<para>If you are using Windows or a Mac in a mixed environment where some of 10.678 -your collaborators are using Linux or Unix, and Mercurial reports a 10.679 -case folding conflict when you try to <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg merge</command>, 10.680 -the procedure to fix the problem is simple. 10.681 -</para> 10.682 - 10.683 -<para>Just find a nearby Linux or Unix box, clone the problem repository 10.684 -onto it, and use Mercurial's <command role="hg-cmd">hg rename</command> command to change the 10.685 -names of any offending files or directories so that they will no 10.686 -longer cause case folding conflicts. Commit this change, <command role="hg-cmd">hg pull</command> 10.687 -or <command role="hg-cmd">hg push</command> it across to your Windows or MacOS system, and 10.688 -<command role="hg-cmd">hg update</command> to the revision with the non-conflicting names. 10.689 -</para> 10.690 - 10.691 -<para>The changeset with case-conflicting names will remain in your 10.692 -project's history, and you still won't be able to <command role="hg-cmd">hg update</command> your 10.693 -working directory to that changeset on a Windows or MacOS system, but 10.694 -you can continue development unimpeded. 10.695 -</para> 10.696 - 10.697 -<note> 10.698 -<para> Prior to version 0.9.3, Mercurial did not use a case safe repository 10.699 - storage mechanism, and did not detect case folding conflicts. If 10.700 - you are using an older version of Mercurial on Windows or MacOS, I 10.701 - strongly recommend that you upgrade. 10.702 -</para> 10.703 -</note> 10.704 - 10.705 -</sect2> 10.706 -</sect1> 10.707 + </sect1> 10.708 + 10.709 + <sect1 id="sec:names:case"> 10.710 + <title>Case sensitivity</title> 10.711 + 10.712 + <para id="x_56a">If you're working in a mixed development environment that 10.713 + contains both Linux (or other Unix) systems and Macs or Windows 10.714 + systems, you should keep in the back of your mind the knowledge 10.715 + that they treat the case (<quote>N</quote> versus 10.716 + <quote>n</quote>) of file names in incompatible ways. This is 10.717 + not very likely to affect you, and it's easy to deal with if it 10.718 + does, but it could surprise you if you don't know about 10.719 + it.</para> 10.720 + 10.721 + <para id="x_56b">Operating systems and filesystems differ in the way they 10.722 + handle the <emphasis>case</emphasis> of characters in file and 10.723 + directory names. There are three common ways to handle case in 10.724 + names.</para> 10.725 + <itemizedlist> 10.726 + <listitem><para id="x_56c">Completely case insensitive. Uppercase and 10.727 + lowercase versions of a letter are treated as identical, 10.728 + both when creating a file and during subsequent accesses. 10.729 + This is common on older DOS-based systems.</para> 10.730 + </listitem> 10.731 + <listitem><para id="x_56d">Case preserving, but insensitive. When a file 10.732 + or directory is created, the case of its name is stored, and 10.733 + can be retrieved and displayed by the operating system. 10.734 + When an existing file is being looked up, its case is 10.735 + ignored. This is the standard arrangement on Windows and 10.736 + MacOS. The names <filename>foo</filename> and 10.737 + <filename>FoO</filename> identify the same file. This 10.738 + treatment of uppercase and lowercase letters as 10.739 + interchangeable is also referred to as <emphasis>case 10.740 + folding</emphasis>.</para> 10.741 + </listitem> 10.742 + <listitem><para id="x_56e">Case sensitive. The case of a name 10.743 + is significant at all times. The names 10.744 + <filename>foo</filename> and <filename>FoO</filename> 10.745 + identify different files. This is the way Linux and Unix 10.746 + systems normally work.</para> 10.747 + </listitem></itemizedlist> 10.748 + 10.749 + <para id="x_56f">On Unix-like systems, it is possible to have any or all of 10.750 + the above ways of handling case in action at once. For example, 10.751 + if you use a USB thumb drive formatted with a FAT32 filesystem 10.752 + on a Linux system, Linux will handle names on that filesystem in 10.753 + a case preserving, but insensitive, way.</para> 10.754 + 10.755 + <sect2> 10.756 + <title>Safe, portable repository storage</title> 10.757 + 10.758 + <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case 10.759 + safe</emphasis>. It translates file names so that they can 10.760 + be safely stored on both case sensitive and case insensitive 10.761 + filesystems. This means that you can use normal file copying 10.762 + tools to transfer a Mercurial repository onto, for example, a 10.763 + USB thumb drive, and safely move that drive and repository 10.764 + back and forth between a Mac, a PC running Windows, and a 10.765 + Linux box.</para> 10.766 + 10.767 + </sect2> 10.768 + <sect2> 10.769 + <title>Detecting case conflicts</title> 10.770 + 10.771 + <para id="x_571">When operating in the working directory, Mercurial honours 10.772 + the naming policy of the filesystem where the working 10.773 + directory is located. If the filesystem is case preserving, 10.774 + but insensitive, Mercurial will treat names that differ only 10.775 + in case as the same.</para> 10.776 + 10.777 + <para id="x_572">An important aspect of this approach is that it is 10.778 + possible to commit a changeset on a case sensitive (typically 10.779 + Linux or Unix) filesystem that will cause trouble for users on 10.780 + case insensitive (usually Windows and MacOS) users. If a 10.781 + Linux user commits changes to two files, one named 10.782 + <filename>myfile.c</filename> and the other named 10.783 + <filename>MyFile.C</filename>, they will be stored correctly 10.784 + in the repository. And in the working directories of other 10.785 + Linux users, they will be correctly represented as separate 10.786 + files.</para> 10.787 + 10.788 + <para id="x_573">If a Windows or Mac user pulls this change, they will not 10.789 + initially have a problem, because Mercurial's repository 10.790 + storage mechanism is case safe. However, once they try to 10.791 + <command role="hg-cmd">hg update</command> the working 10.792 + directory to that changeset, or <command role="hg-cmd">hg 10.793 + merge</command> with that changeset, Mercurial will spot the 10.794 + conflict between the two file names that the filesystem would 10.795 + treat as the same, and forbid the update or merge from 10.796 + occurring.</para> 10.797 + </sect2> 10.798 + 10.799 + <sect2> 10.800 + <title>Fixing a case conflict</title> 10.801 + 10.802 + <para id="x_574">If you are using Windows or a Mac in a mixed environment 10.803 + where some of your collaborators are using Linux or Unix, and 10.804 + Mercurial reports a case folding conflict when you try to 10.805 + <command role="hg-cmd">hg update</command> or <command 10.806 + role="hg-cmd">hg merge</command>, the procedure to fix the 10.807 + problem is simple.</para> 10.808 + 10.809 + <para id="x_575">Just find a nearby Linux or Unix box, clone the problem 10.810 + repository onto it, and use Mercurial's <command 10.811 + role="hg-cmd">hg rename</command> command to change the 10.812 + names of any offending files or directories so that they will 10.813 + no longer cause case folding conflicts. Commit this change, 10.814 + <command role="hg-cmd">hg pull</command> or <command 10.815 + role="hg-cmd">hg push</command> it across to your Windows or 10.816 + MacOS system, and <command role="hg-cmd">hg update</command> 10.817 + to the revision with the non-conflicting names.</para> 10.818 + 10.819 + <para id="x_576">The changeset with case-conflicting names will remain in 10.820 + your project's history, and you still won't be able to 10.821 + <command role="hg-cmd">hg update</command> your working 10.822 + directory to that changeset on a Windows or MacOS system, but 10.823 + you can continue development unimpeded.</para> 10.824 + </sect2> 10.825 + </sect1> 10.826 </chapter> 10.827 10.828 <!-- 10.829 local variables: 10.830 sgml-parent-document: ("00book.xml" "book" "chapter") 10.831 end: 10.832 ---> 10.833 \ No newline at end of file 10.834 +-->
11.1 --- a/fr/ch08-branch.xml Sat Sep 12 17:58:26 2009 +0200 11.2 +++ b/fr/ch08-branch.xml Sat Sep 12 17:58:56 2009 +0200 11.3 @@ -1,473 +1,533 @@ 11.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 11.5 11.6 -<chapter> 11.7 -<title>Managing releases and branchy development</title> 11.8 -<para>\label{chap:branch}</para> 11.9 - 11.10 -<para>Mercurial provides several mechanisms for you to manage a project that 11.11 -is making progress on multiple fronts at once. To understand these 11.12 -mechanisms, let's first take a brief look at a fairly normal software 11.13 -project structure.</para> 11.14 - 11.15 -<para>Many software projects issue periodic <quote>major</quote> releases that contain 11.16 -substantial new features. In parallel, they may issue <quote>minor</quote> 11.17 -releases. These are usually identical to the major releases off which 11.18 -they're based, but with a few bugs fixed.</para> 11.19 - 11.20 -<para>In this chapter, we'll start by talking about how to keep records of 11.21 -project milestones such as releases. We'll then continue on to talk 11.22 -about the flow of work between different phases of a project, and how 11.23 -Mercurial can help you to isolate and manage this work.</para> 11.24 - 11.25 -<sect1> 11.26 -<title>Giving a persistent name to a revision</title> 11.27 - 11.28 -<para>Once you decide that you'd like to call a particular revision a 11.29 -<quote>release</quote>, it's a good idea to record the identity of that revision. 11.30 -This will let you reproduce that release at a later date, for whatever 11.31 -purpose you might need at the time (reproducing a bug, porting to a 11.32 -new platform, etc). 11.33 -<!-- &interaction.tag.init; --></para> 11.34 - 11.35 -<para>Mercurial lets you give a permanent name to any revision using the 11.36 -<command role="hg-cmd">hg tag</command> command. Not surprisingly, these names are called 11.37 -<quote>tags</quote>. 11.38 -<!-- &interaction.tag.tag; --></para> 11.39 - 11.40 -<para>A tag is nothing more than a <quote>symbolic name</quote> for a revision. Tags 11.41 -exist purely for your convenience, so that you have a handy permanent 11.42 -way to refer to a revision; Mercurial doesn't interpret the tag names 11.43 -you use in any way. Neither does Mercurial place any restrictions on 11.44 -the name of a tag, beyond a few that are necessary to ensure that a 11.45 -tag can be parsed unambiguously. A tag name cannot contain any of the 11.46 -following characters:</para> 11.47 -<itemizedlist> 11.48 -<listitem><para>Colon (ASCII 58, <quote><literal>:</literal></quote>)</para> 11.49 -</listitem> 11.50 -<listitem><para>Carriage return (ASCII 13, <quote><literal>\r</literal></quote>) 11.51 -</para> 11.52 -</listitem> 11.53 -<listitem><para>Newline (ASCII 10, <quote><literal>\n</literal></quote>) 11.54 -</para> 11.55 -</listitem></itemizedlist> 11.56 - 11.57 -<para>You can use the <command role="hg-cmd">hg tags</command> command to display the tags present in 11.58 -your repository. In the output, each tagged revision is identified 11.59 -first by its name, then by revision number, and finally by the unique 11.60 -hash of the revision. 11.61 -<!-- &interaction.tag.tags; --> 11.62 -Notice that <literal>tip</literal> is listed in the output of <command role="hg-cmd">hg tags</command>. The 11.63 -<literal>tip</literal> tag is a special <quote>floating</quote> tag, which always 11.64 -identifies the newest revision in the repository. 11.65 -</para> 11.66 - 11.67 -<para>In the output of the <command role="hg-cmd">hg tags</command> command, tags are listed in reverse 11.68 -order, by revision number. This usually means that recent tags are 11.69 -listed before older tags. It also means that <literal>tip</literal> is always 11.70 -going to be the first tag listed in the output of <command role="hg-cmd">hg tags</command>. 11.71 -</para> 11.72 - 11.73 -<para>When you run <command role="hg-cmd">hg log</command>, if it displays a revision that has tags 11.74 -associated with it, it will print those tags. 11.75 -<!-- &interaction.tag.log; --> 11.76 -</para> 11.77 - 11.78 -<para>Any time you need to provide a revision ID to a Mercurial command, the 11.79 -command will accept a tag name in its place. Internally, Mercurial 11.80 -will translate your tag name into the corresponding revision ID, then 11.81 -use that. 11.82 -<!-- &interaction.tag.log.v1.0; --> 11.83 -</para> 11.84 - 11.85 -<para>There's no limit on the number of tags you can have in a repository, 11.86 -or on the number of tags that a single revision can have. As a 11.87 -practical matter, it's not a great idea to have <quote>too many</quote> (a number 11.88 -which will vary from project to project), simply because tags are 11.89 -supposed to help you to find revisions. If you have lots of tags, the 11.90 -ease of using them to identify revisions diminishes rapidly. 11.91 -</para> 11.92 - 11.93 -<para>For example, if your project has milestones as frequent as every few 11.94 -days, it's perfectly reasonable to tag each one of those. But if you 11.95 -have a continuous build system that makes sure every revision can be 11.96 -built cleanly, you'd be introducing a lot of noise if you were to tag 11.97 -every clean build. Instead, you could tag failed builds (on the 11.98 -assumption that they're rare!), or simply not use tags to track 11.99 -buildability. 11.100 -</para> 11.101 - 11.102 -<para>If you want to remove a tag that you no longer want, use 11.103 -<command role="hg-cmd">hg tag --remove</command>. 11.104 -<!-- &interaction.tag.remove; --> 11.105 -You can also modify a tag at any time, so that it identifies a 11.106 -different revision, by simply issuing a new <command role="hg-cmd">hg tag</command> command. 11.107 -You'll have to use the <option role="hg-opt-tag">-f</option> option to tell Mercurial that 11.108 -you <emphasis>really</emphasis> want to update the tag. 11.109 -<!-- &interaction.tag.replace; --> 11.110 -There will still be a permanent record of the previous identity of the 11.111 -tag, but Mercurial will no longer use it. There's thus no penalty to 11.112 -tagging the wrong revision; all you have to do is turn around and tag 11.113 -the correct revision once you discover your error. 11.114 -</para> 11.115 - 11.116 -<para>Mercurial stores tags in a normal revision-controlled file in your 11.117 -repository. If you've created any tags, you'll find them in a file 11.118 -named <filename role="special">.hgtags</filename>. When you run the <command role="hg-cmd">hg tag</command> command, 11.119 -Mercurial modifies this file, then automatically commits the change to 11.120 -it. This means that every time you run <command role="hg-cmd">hg tag</command>, you'll see a 11.121 -corresponding changeset in the output of <command role="hg-cmd">hg log</command>. 11.122 -<!-- &interaction.tag.tip; --> 11.123 -</para> 11.124 - 11.125 -<sect2> 11.126 -<title>Handling tag conflicts during a merge</title> 11.127 - 11.128 -<para>You won't often need to care about the <filename role="special">.hgtags</filename> file, but 11.129 -it sometimes makes its presence known during a merge. The format of 11.130 -the file is simple: it consists of a series of lines. Each line 11.131 -starts with a changeset hash, followed by a space, followed by the 11.132 -name of a tag. 11.133 -</para> 11.134 - 11.135 -<para>If you're resolving a conflict in the <filename role="special">.hgtags</filename> file during 11.136 -a merge, there's one twist to modifying the <filename role="special">.hgtags</filename> file: 11.137 -when Mercurial is parsing the tags in a repository, it <emphasis>never</emphasis> 11.138 -reads the working copy of the <filename role="special">.hgtags</filename> file. Instead, it 11.139 -reads the <emphasis>most recently committed</emphasis> revision of the file. 11.140 -</para> 11.141 - 11.142 -<para>An unfortunate consequence of this design is that you can't actually 11.143 -verify that your merged <filename role="special">.hgtags</filename> file is correct until 11.144 -<emphasis>after</emphasis> you've committed a change. So if you find yourself 11.145 -resolving a conflict on <filename role="special">.hgtags</filename> during a merge, be sure to 11.146 -run <command role="hg-cmd">hg tags</command> after you commit. If it finds an error in the 11.147 -<filename role="special">.hgtags</filename> file, it will report the location of the error, 11.148 -which you can then fix and commit. You should then run <command role="hg-cmd">hg tags</command> 11.149 -again, just to be sure that your fix is correct. 11.150 -</para> 11.151 - 11.152 -</sect2> 11.153 -<sect2> 11.154 -<title>Tags and cloning</title> 11.155 - 11.156 -<para>You may have noticed that the <command role="hg-cmd">hg clone</command> command has a 11.157 -<option role="hg-opt-clone">-r</option> option that lets you clone an exact copy of the 11.158 -repository as of a particular changeset. The new clone will not 11.159 -contain any project history that comes after the revision you 11.160 -specified. This has an interaction with tags that can surprise the 11.161 -unwary. 11.162 -</para> 11.163 - 11.164 -<para>Recall that a tag is stored as a revision to the <filename role="special">.hgtags</filename> 11.165 -file, so that when you create a tag, the changeset in which it's 11.166 -recorded necessarily refers to an older changeset. When you run 11.167 -<command role="hg-cmd">hg clone -r foo</command> to clone a repository as of tag 11.168 -<literal>foo</literal>, the new clone \emph{will not contain the history that 11.169 - created the tag} that you used to clone the repository. The result 11.170 -is that you'll get exactly the right subset of the project's history 11.171 -in the new repository, but <emphasis>not</emphasis> the tag you might have expected. 11.172 -</para> 11.173 - 11.174 -</sect2> 11.175 -<sect2> 11.176 -<title>When permanent tags are too much</title> 11.177 - 11.178 -<para>Since Mercurial's tags are revision controlled and carried around with 11.179 -a project's history, everyone you work with will see the tags you 11.180 -create. But giving names to revisions has uses beyond simply noting 11.181 -that revision <literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>. If 11.182 -you're trying to track down a subtle bug, you might want a tag to 11.183 -remind you of something like <quote>Anne saw the symptoms with this 11.184 -revision</quote>. 11.185 -</para> 11.186 - 11.187 -<para>For cases like this, what you might want to use are <emphasis>local</emphasis> tags. 11.188 -You can create a local tag with the <option role="hg-opt-tag">-l</option> option to the 11.189 -<command role="hg-cmd">hg tag</command> command. This will store the tag in a file called 11.190 -<filename role="special">.hg/localtags</filename>. Unlike <filename role="special">.hgtags</filename>, 11.191 -<filename role="special">.hg/localtags</filename> is not revision controlled. Any tags you 11.192 -create using <option role="hg-opt-tag">-l</option> remain strictly local to the repository 11.193 -you're currently working in. 11.194 -</para> 11.195 - 11.196 -</sect2> 11.197 -</sect1> 11.198 -<sect1> 11.199 -<title>The flow of changes&emdash;big picture vs. little</title> 11.200 - 11.201 -<para>To return to the outline I sketched at the beginning of a chapter, 11.202 -let's think about a project that has multiple concurrent pieces of 11.203 -work under development at once. 11.204 -</para> 11.205 - 11.206 -<para>There might be a push for a new <quote>main</quote> release; a new minor bugfix 11.207 -release to the last main release; and an unexpected <quote>hot fix</quote> to an 11.208 -old release that is now in maintenance mode. 11.209 -</para> 11.210 - 11.211 -<para>The usual way people refer to these different concurrent directions of 11.212 -development is as <quote>branches</quote>. However, we've already seen numerous 11.213 -times that Mercurial treats <emphasis>all of history</emphasis> as a series of 11.214 -branches and merges. Really, what we have here is two ideas that are 11.215 -peripherally related, but which happen to share a name. 11.216 -</para> 11.217 -<itemizedlist> 11.218 -<listitem><para><quote>Big picture</quote> branches represent the sweep of a project's 11.219 - evolution; people give them names, and talk about them in 11.220 - conversation. 11.221 -</para> 11.222 -</listitem> 11.223 -<listitem><para><quote>Little picture</quote> branches are artefacts of the day-to-day 11.224 - activity of developing and merging changes. They expose the 11.225 - narrative of how the code was developed. 11.226 -</para> 11.227 -</listitem></itemizedlist> 11.228 - 11.229 -</sect1> 11.230 -<sect1> 11.231 -<title>Managing big-picture branches in repositories</title> 11.232 - 11.233 -<para>The easiest way to isolate a <quote>big picture</quote> branch in Mercurial is in 11.234 -a dedicated repository. If you have an existing shared 11.235 -repository&emdash;let's call it <literal>myproject</literal>&emdash;that reaches a <quote>1.0</quote> 11.236 -milestone, you can start to prepare for future maintenance releases on 11.237 -top of version 1.0 by tagging the revision from which you prepared 11.238 -the 1.0 release. 11.239 -<!-- &interaction.branch-repo.tag; --> 11.240 -You can then clone a new shared <literal>myproject-1.0.1</literal> repository as 11.241 -of that tag. 11.242 -<!-- &interaction.branch-repo.clone; --> 11.243 -</para> 11.244 - 11.245 -<para>Afterwards, if someone needs to work on a bug fix that ought to go 11.246 -into an upcoming 1.0.1 minor release, they clone the 11.247 -<literal>myproject-1.0.1</literal> repository, make their changes, and push them 11.248 -back. 11.249 -<!-- &interaction.branch-repo.bugfix; --> 11.250 -Meanwhile, development for the next major release can continue, 11.251 -isolated and unabated, in the <literal>myproject</literal> repository. 11.252 -<!-- &interaction.branch-repo.new; --> 11.253 -</para> 11.254 - 11.255 -</sect1> 11.256 -<sect1> 11.257 -<title>Don't repeat yourself: merging across branches</title> 11.258 - 11.259 -<para>In many cases, if you have a bug to fix on a maintenance branch, the 11.260 -chances are good that the bug exists on your project's main branch 11.261 -(and possibly other maintenance branches, too). It's a rare developer 11.262 -who wants to fix the same bug multiple times, so let's look at a few 11.263 -ways that Mercurial can help you to manage these bugfixes without 11.264 -duplicating your work. 11.265 -</para> 11.266 - 11.267 -<para>In the simplest instance, all you need to do is pull changes from your 11.268 -maintenance branch into your local clone of the target branch. 11.269 -<!-- &interaction.branch-repo.pull; --> 11.270 -You'll then need to merge the heads of the two branches, and push back 11.271 -to the main branch. 11.272 -<!-- &interaction.branch-repo.merge; --> 11.273 -</para> 11.274 - 11.275 -</sect1> 11.276 -<sect1> 11.277 -<title>Naming branches within one repository</title> 11.278 - 11.279 -<para>In most instances, isolating branches in repositories is the right 11.280 -approach. Its simplicity makes it easy to understand; and so it's 11.281 -hard to make mistakes. There's a one-to-one relationship between 11.282 -branches you're working in and directories on your system. This lets 11.283 -you use normal (non-Mercurial-aware) tools to work on files within a 11.284 -branch/repository. 11.285 -</para> 11.286 - 11.287 -<para>If you're more in the <quote>power user</quote> category (<emphasis>and</emphasis> your 11.288 -collaborators are too), there is an alternative way of handling 11.289 -branches that you can consider. I've already mentioned the 11.290 -human-level distinction between <quote>small picture</quote> and <quote>big picture</quote> 11.291 -branches. While Mercurial works with multiple <quote>small picture</quote> 11.292 -branches in a repository all the time (for example after you pull 11.293 -changes in, but before you merge them), it can <emphasis>also</emphasis> work with 11.294 -multiple <quote>big picture</quote> branches. 11.295 -</para> 11.296 - 11.297 -<para>The key to working this way is that Mercurial lets you assign a 11.298 -persistent <emphasis>name</emphasis> to a branch. There always exists a branch 11.299 -named <literal>default</literal>. Even before you start naming branches 11.300 -yourself, you can find traces of the <literal>default</literal> branch if you 11.301 -look for them. 11.302 -</para> 11.303 - 11.304 -<para>As an example, when you run the <command role="hg-cmd">hg commit</command> command, and it pops up 11.305 -your editor so that you can enter a commit message, look for a line 11.306 -that contains the text <quote><literal>HG: branch default</literal></quote> at the bottom. 11.307 -This is telling you that your commit will occur on the branch named 11.308 -<literal>default</literal>. 11.309 -</para> 11.310 - 11.311 -<para>To start working with named branches, use the <command role="hg-cmd">hg branches</command> 11.312 -command. This command lists the named branches already present in 11.313 -your repository, telling you which changeset is the tip of each. 11.314 -<!-- &interaction.branch-named.branches; --> 11.315 -Since you haven't created any named branches yet, the only one that 11.316 -exists is <literal>default</literal>. 11.317 -</para> 11.318 - 11.319 -<para>To find out what the <quote>current</quote> branch is, run the <command role="hg-cmd">hg branch</command> 11.320 -command, giving it no arguments. This tells you what branch the 11.321 -parent of the current changeset is on. 11.322 -<!-- &interaction.branch-named.branch; --> 11.323 -</para> 11.324 - 11.325 -<para>To create a new branch, run the <command role="hg-cmd">hg branch</command> command again. This 11.326 -time, give it one argument: the name of the branch you want to create. 11.327 -<!-- &interaction.branch-named.create; --> 11.328 -</para> 11.329 - 11.330 -<para>After you've created a branch, you might wonder what effect the 11.331 -<command role="hg-cmd">hg branch</command> command has had. What do the <command role="hg-cmd">hg status</command> and 11.332 -<command role="hg-cmd">hg tip</command> commands report? 11.333 -<!-- &interaction.branch-named.status; --> 11.334 -Nothing has changed in the working directory, and there's been no new 11.335 -history created. As this suggests, running the <command role="hg-cmd">hg branch</command> command 11.336 -has no permanent effect; it only tells Mercurial what branch name to 11.337 -use the <emphasis>next</emphasis> time you commit a changeset. 11.338 -</para> 11.339 - 11.340 -<para>When you commit a change, Mercurial records the name of the branch on 11.341 -which you committed. Once you've switched from the <literal>default</literal> 11.342 -branch to another and committed, you'll see the name of the new branch 11.343 -show up in the output of <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg tip</command>, and other commands 11.344 -that display the same kind of output. 11.345 -<!-- &interaction.branch-named.commit; --> 11.346 -The <command role="hg-cmd">hg log</command>-like commands will print the branch name of every 11.347 -changeset that's not on the <literal>default</literal> branch. As a result, if 11.348 -you never use named branches, you'll never see this information. 11.349 -</para> 11.350 - 11.351 -<para>Once you've named a branch and committed a change with that name, 11.352 -every subsequent commit that descends from that change will inherit 11.353 -the same branch name. You can change the name of a branch at any 11.354 -time, using the <command role="hg-cmd">hg branch</command> command. 11.355 -<!-- &interaction.branch-named.rebranch; --> 11.356 -In practice, this is something you won't do very often, as branch 11.357 -names tend to have fairly long lifetimes. (This isn't a rule, just an 11.358 -observation.) 11.359 -</para> 11.360 - 11.361 -</sect1> 11.362 -<sect1> 11.363 -<title>Dealing with multiple named branches in a repository</title> 11.364 - 11.365 -<para>If you have more than one named branch in a repository, Mercurial will 11.366 -remember the branch that your working directory on when you start a 11.367 -command like <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg pull -u</command>. It will update 11.368 -the working directory to the tip of this branch, no matter what the 11.369 -<quote>repo-wide</quote> tip is. To update to a revision that's on a different 11.370 -named branch, you may need to use the <option role="hg-opt-update">-C</option> option to 11.371 -<command role="hg-cmd">hg update</command>. 11.372 -</para> 11.373 - 11.374 -<para>This behaviour is a little subtle, so let's see it in action. First, 11.375 -let's remind ourselves what branch we're currently on, and what 11.376 -branches are in our repository. 11.377 -<!-- &interaction.branch-named.parents; --> 11.378 -We're on the <literal>bar</literal> branch, but there also exists an older 11.379 -<command role="hg-cmd">hg foo</command> branch. 11.380 -</para> 11.381 - 11.382 -<para>We can <command role="hg-cmd">hg update</command> back and forth between the tips of the 11.383 -<literal>foo</literal> and <literal>bar</literal> branches without needing to use the 11.384 -<option role="hg-opt-update">-C</option> option, because this only involves going backwards 11.385 -and forwards linearly through our change history. 11.386 -<!-- &interaction.branch-named.update-switchy; --> 11.387 -</para> 11.388 - 11.389 -<para>If we go back to the <literal>foo</literal> branch and then run <command role="hg-cmd">hg update</command>, 11.390 -it will keep us on <literal>foo</literal>, not move us to the tip of 11.391 -<literal>bar</literal>. 11.392 -<!-- &interaction.branch-named.update-nothing; --> 11.393 -</para> 11.394 - 11.395 -<para>Committing a new change on the <literal>foo</literal> branch introduces a new 11.396 -head. 11.397 -<!-- &interaction.branch-named.foo-commit; --> 11.398 -</para> 11.399 - 11.400 -</sect1> 11.401 -<sect1> 11.402 -<title>Branch names and merging</title> 11.403 - 11.404 -<para>As you've probably noticed, merges in Mercurial are not symmetrical. 11.405 -Let's say our repository has two heads, 17 and 23. If I 11.406 -<command role="hg-cmd">hg update</command> to 17 and then <command role="hg-cmd">hg merge</command> with 23, Mercurial records 11.407 -17 as the first parent of the merge, and 23 as the second. Whereas if 11.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 11.409 -as the first parent, and 17 as the second. 11.410 -</para> 11.411 - 11.412 -<para>This affects Mercurial's choice of branch name when you merge. After 11.413 -a merge, Mercurial will retain the branch name of the first parent 11.414 -when you commit the result of the merge. If your first parent's 11.415 -branch name is <literal>foo</literal>, and you merge with <literal>bar</literal>, the 11.416 -branch name will still be <literal>foo</literal> after you merge. 11.417 -</para> 11.418 - 11.419 -<para>It's not unusual for a repository to contain multiple heads, each with 11.420 -the same branch name. Let's say I'm working on the <literal>foo</literal> 11.421 -branch, and so are you. We commit different changes; I pull your 11.422 -changes; I now have two heads, each claiming to be on the <literal>foo</literal> 11.423 -branch. The result of a merge will be a single head on the 11.424 -<literal>foo</literal> branch, as you might hope. 11.425 -</para> 11.426 - 11.427 -<para>But if I'm working on the <literal>bar</literal> branch, and I merge work from 11.428 -the <literal>foo</literal> branch, the result will remain on the <literal>bar</literal> 11.429 -branch. 11.430 -<!-- &interaction.branch-named.merge; --> 11.431 -</para> 11.432 - 11.433 -<para>To give a more concrete example, if I'm working on the 11.434 -<literal>bleeding-edge</literal> branch, and I want to bring in the latest fixes 11.435 -from the <literal>stable</literal> branch, Mercurial will choose the <quote>right</quote> 11.436 -(<literal>bleeding-edge</literal>) branch name when I pull and merge from 11.437 -<literal>stable</literal>. 11.438 -</para> 11.439 - 11.440 -</sect1> 11.441 -<sect1> 11.442 -<title>Branch naming is generally useful</title> 11.443 - 11.444 -<para>You shouldn't think of named branches as applicable only to situations 11.445 -where you have multiple long-lived branches cohabiting in a single 11.446 -repository. They're very useful even in the one-branch-per-repository 11.447 -case. 11.448 -</para> 11.449 - 11.450 -<para>In the simplest case, giving a name to each branch gives you a 11.451 -permanent record of which branch a changeset originated on. This 11.452 -gives you more context when you're trying to follow the history of a 11.453 -long-lived branchy project. 11.454 -</para> 11.455 - 11.456 -<para>If you're working with shared repositories, you can set up a 11.457 -<literal role="hook">pretxnchangegroup</literal> hook on each that will block incoming changes 11.458 -that have the <quote>wrong</quote> branch name. This provides a simple, but 11.459 -effective, defence against people accidentally pushing changes from a 11.460 -<quote>bleeding edge</quote> branch to a <quote>stable</quote> branch. Such a hook might 11.461 -look like this inside the shared repo's <filename role="special"> /.hgrc</filename>. 11.462 -</para> 11.463 -<programlisting> 11.464 -<para> [hooks] 11.465 - pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch 11.466 -</para> 11.467 -</programlisting> 11.468 - 11.469 -</sect1> 11.470 +<chapter id="chap:branch"> 11.471 + <?dbhtml filename="managing-releases-and-branchy-development.html"?> 11.472 + <title>Managing releases and branchy development</title> 11.473 + 11.474 + <para id="x_369">Mercurial provides several mechanisms for you to manage a 11.475 + project that is making progress on multiple fronts at once. To 11.476 + understand these mechanisms, let's first take a brief look at a 11.477 + fairly normal software project structure.</para> 11.478 + 11.479 + <para id="x_36a">Many software projects issue periodic <quote>major</quote> 11.480 + releases that contain substantial new features. In parallel, they 11.481 + may issue <quote>minor</quote> releases. These are usually 11.482 + identical to the major releases off which they're based, but with 11.483 + a few bugs fixed.</para> 11.484 + 11.485 + <para id="x_36b">In this chapter, we'll start by talking about how to keep 11.486 + records of project milestones such as releases. We'll then 11.487 + continue on to talk about the flow of work between different 11.488 + phases of a project, and how Mercurial can help you to isolate and 11.489 + manage this work.</para> 11.490 + 11.491 + <sect1> 11.492 + <title>Giving a persistent name to a revision</title> 11.493 + 11.494 + <para id="x_36c">Once you decide that you'd like to call a particular 11.495 + revision a <quote>release</quote>, it's a good idea to record 11.496 + the identity of that revision. This will let you reproduce that 11.497 + release at a later date, for whatever purpose you might need at 11.498 + the time (reproducing a bug, porting to a new platform, etc). 11.499 + &interaction.tag.init;</para> 11.500 + 11.501 + <para id="x_36d">Mercurial lets you give a permanent name to any revision 11.502 + using the <command role="hg-cmd">hg tag</command> command. Not 11.503 + surprisingly, these names are called <quote>tags</quote>.</para> 11.504 + 11.505 + &interaction.tag.tag; 11.506 + 11.507 + <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote> 11.508 + for a revision. Tags exist purely for your convenience, so that 11.509 + you have a handy permanent way to refer to a revision; Mercurial 11.510 + doesn't interpret the tag names you use in any way. Neither 11.511 + does Mercurial place any restrictions on the name of a tag, 11.512 + beyond a few that are necessary to ensure that a tag can be 11.513 + parsed unambiguously. A tag name cannot contain any of the 11.514 + following characters:</para> 11.515 + <itemizedlist> 11.516 + <listitem><para id="x_36f">Colon (ASCII 58, 11.517 + <quote><literal>:</literal></quote>)</para> 11.518 + </listitem> 11.519 + <listitem><para id="x_370">Carriage return (ASCII 13, 11.520 + <quote><literal>\r</literal></quote>)</para> 11.521 + </listitem> 11.522 + <listitem><para id="x_371">Newline (ASCII 10, 11.523 + <quote><literal>\n</literal></quote>)</para> 11.524 + </listitem></itemizedlist> 11.525 + 11.526 + <para id="x_372">You can use the <command role="hg-cmd">hg tags</command> 11.527 + command to display the tags present in your repository. In the 11.528 + output, each tagged revision is identified first by its name, 11.529 + then by revision number, and finally by the unique hash of the 11.530 + revision.</para> 11.531 + 11.532 + &interaction.tag.tags; 11.533 + 11.534 + <para id="x_373">Notice that <literal>tip</literal> is listed in the output 11.535 + of <command role="hg-cmd">hg tags</command>. The 11.536 + <literal>tip</literal> tag is a special <quote>floating</quote> 11.537 + tag, which always identifies the newest revision in the 11.538 + repository.</para> 11.539 + 11.540 + <para id="x_374">In the output of the <command role="hg-cmd">hg 11.541 + tags</command> command, tags are listed in reverse order, by 11.542 + revision number. This usually means that recent tags are listed 11.543 + before older tags. It also means that <literal>tip</literal> is 11.544 + always going to be the first tag listed in the output of 11.545 + <command role="hg-cmd">hg tags</command>.</para> 11.546 + 11.547 + <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it 11.548 + displays a revision that has tags associated with it, it will 11.549 + print those tags.</para> 11.550 + 11.551 + &interaction.tag.log; 11.552 + 11.553 + <para id="x_376">Any time you need to provide a revision ID to a Mercurial 11.554 + command, the command will accept a tag name in its place. 11.555 + Internally, Mercurial will translate your tag name into the 11.556 + corresponding revision ID, then use that.</para> 11.557 + 11.558 + &interaction.tag.log.v1.0; 11.559 + 11.560 + <para id="x_377">There's no limit on the number of tags you can have in a 11.561 + repository, or on the number of tags that a single revision can 11.562 + have. As a practical matter, it's not a great idea to have 11.563 + <quote>too many</quote> (a number which will vary from project 11.564 + to project), simply because tags are supposed to help you to 11.565 + find revisions. If you have lots of tags, the ease of using 11.566 + them to identify revisions diminishes rapidly.</para> 11.567 + 11.568 + <para id="x_378">For example, if your project has milestones as frequent as 11.569 + every few days, it's perfectly reasonable to tag each one of 11.570 + those. But if you have a continuous build system that makes 11.571 + sure every revision can be built cleanly, you'd be introducing a 11.572 + lot of noise if you were to tag every clean build. Instead, you 11.573 + could tag failed builds (on the assumption that they're rare!), 11.574 + or simply not use tags to track buildability.</para> 11.575 + 11.576 + <para id="x_379">If you want to remove a tag that you no longer want, use 11.577 + <command role="hg-cmd">hg tag --remove</command>.</para> 11.578 + 11.579 + &interaction.tag.remove; 11.580 + 11.581 + <para id="x_37a">You can also modify a tag at any time, so that it identifies 11.582 + a different revision, by simply issuing a new <command 11.583 + role="hg-cmd">hg tag</command> command. You'll have to use the 11.584 + <option role="hg-opt-tag">-f</option> option to tell Mercurial 11.585 + that you <emphasis>really</emphasis> want to update the 11.586 + tag.</para> 11.587 + 11.588 + &interaction.tag.replace; 11.589 + 11.590 + <para id="x_37b">There will still be a permanent record of the previous 11.591 + identity of the tag, but Mercurial will no longer use it. 11.592 + There's thus no penalty to tagging the wrong revision; all you 11.593 + have to do is turn around and tag the correct revision once you 11.594 + discover your error.</para> 11.595 + 11.596 + <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 11.597 + in your repository. If you've created any tags, you'll find 11.598 + them in a file in the root of your repository named <filename 11.599 + role="special">.hgtags</filename>. When you run the <command 11.600 + role="hg-cmd">hg tag</command> command, Mercurial modifies 11.601 + this file, then automatically commits the change to it. This 11.602 + means that every time you run <command role="hg-cmd">hg 11.603 + tag</command>, you'll see a corresponding changeset in the 11.604 + output of <command role="hg-cmd">hg log</command>.</para> 11.605 + 11.606 + &interaction.tag.tip; 11.607 + 11.608 + <sect2> 11.609 + <title>Handling tag conflicts during a merge</title> 11.610 + 11.611 + <para id="x_37d">You won't often need to care about the <filename 11.612 + role="special">.hgtags</filename> file, but it sometimes 11.613 + makes its presence known during a merge. The format of the 11.614 + file is simple: it consists of a series of lines. Each line 11.615 + starts with a changeset hash, followed by a space, followed by 11.616 + the name of a tag.</para> 11.617 + 11.618 + <para id="x_37e">If you're resolving a conflict in the <filename 11.619 + role="special">.hgtags</filename> file during a merge, 11.620 + there's one twist to modifying the <filename 11.621 + role="special">.hgtags</filename> file: when Mercurial is 11.622 + parsing the tags in a repository, it 11.623 + <emphasis>never</emphasis> reads the working copy of the 11.624 + <filename role="special">.hgtags</filename> file. Instead, it 11.625 + reads the <emphasis>most recently committed</emphasis> 11.626 + revision of the file.</para> 11.627 + 11.628 + <para id="x_37f">An unfortunate consequence of this design is that you 11.629 + can't actually verify that your merged <filename 11.630 + role="special">.hgtags</filename> file is correct until 11.631 + <emphasis>after</emphasis> you've committed a change. So if 11.632 + you find yourself resolving a conflict on <filename 11.633 + role="special">.hgtags</filename> during a merge, be sure to 11.634 + run <command role="hg-cmd">hg tags</command> after you commit. 11.635 + If it finds an error in the <filename 11.636 + role="special">.hgtags</filename> file, it will report the 11.637 + location of the error, which you can then fix and commit. You 11.638 + should then run <command role="hg-cmd">hg tags</command> 11.639 + again, just to be sure that your fix is correct.</para> 11.640 + </sect2> 11.641 + 11.642 + <sect2> 11.643 + <title>Tags and cloning</title> 11.644 + 11.645 + <para id="x_380">You may have noticed that the <command role="hg-cmd">hg 11.646 + clone</command> command has a <option 11.647 + role="hg-opt-clone">-r</option> option that lets you clone 11.648 + an exact copy of the repository as of a particular changeset. 11.649 + The new clone will not contain any project history that comes 11.650 + after the revision you specified. This has an interaction 11.651 + with tags that can surprise the unwary.</para> 11.652 + 11.653 + <para id="x_381">Recall that a tag is stored as a revision to 11.654 + the <filename role="special">.hgtags</filename> file. When you 11.655 + create a tag, the changeset in which its recorded refers to an 11.656 + older changeset. When you run <command role="hg-cmd">hg clone 11.657 + -r foo</command> to clone a repository as of tag 11.658 + <literal>foo</literal>, the new clone <emphasis>will not 11.659 + contain any revision newer than the one the tag refers to, 11.660 + including the revision where the tag was created</emphasis>. 11.661 + The result is that you'll get exactly the right subset of the 11.662 + project's history in the new repository, but 11.663 + <emphasis>not</emphasis> the tag you might have 11.664 + expected.</para> 11.665 + </sect2> 11.666 + 11.667 + <sect2> 11.668 + <title>When permanent tags are too much</title> 11.669 + 11.670 + <para id="x_382">Since Mercurial's tags are revision controlled and carried 11.671 + around with a project's history, everyone you work with will 11.672 + see the tags you create. But giving names to revisions has 11.673 + uses beyond simply noting that revision 11.674 + <literal>4237e45506ee</literal> is really 11.675 + <literal>v2.0.2</literal>. If you're trying to track down a 11.676 + subtle bug, you might want a tag to remind you of something 11.677 + like <quote>Anne saw the symptoms with this 11.678 + revision</quote>.</para> 11.679 + 11.680 + <para id="x_383">For cases like this, what you might want to use are 11.681 + <emphasis>local</emphasis> tags. You can create a local tag 11.682 + with the <option role="hg-opt-tag">-l</option> option to the 11.683 + <command role="hg-cmd">hg tag</command> command. This will 11.684 + store the tag in a file called <filename 11.685 + role="special">.hg/localtags</filename>. Unlike <filename 11.686 + role="special">.hgtags</filename>, <filename 11.687 + role="special">.hg/localtags</filename> is not revision 11.688 + controlled. Any tags you create using <option 11.689 + role="hg-opt-tag">-l</option> remain strictly local to the 11.690 + repository you're currently working in.</para> 11.691 + </sect2> 11.692 + </sect1> 11.693 + 11.694 + <sect1> 11.695 + <title>The flow of changes&emdash;big picture vs. little</title> 11.696 + 11.697 + <para id="x_384">To return to the outline I sketched at the 11.698 + beginning of the chapter, let's think about a project that has 11.699 + multiple concurrent pieces of work under development at 11.700 + once.</para> 11.701 + 11.702 + <para id="x_385">There might be a push for a new <quote>main</quote> release; 11.703 + a new minor bugfix release to the last main release; and an 11.704 + unexpected <quote>hot fix</quote> to an old release that is now 11.705 + in maintenance mode.</para> 11.706 + 11.707 + <para id="x_386">The usual way people refer to these different concurrent 11.708 + directions of development is as <quote>branches</quote>. 11.709 + However, we've already seen numerous times that Mercurial treats 11.710 + <emphasis>all of history</emphasis> as a series of branches and 11.711 + merges. Really, what we have here is two ideas that are 11.712 + peripherally related, but which happen to share a name.</para> 11.713 + <itemizedlist> 11.714 + <listitem><para id="x_387"><quote>Big picture</quote> branches represent 11.715 + the sweep of a project's evolution; people give them names, 11.716 + and talk about them in conversation.</para> 11.717 + </listitem> 11.718 + <listitem><para id="x_388"><quote>Little picture</quote> branches are 11.719 + artefacts of the day-to-day activity of developing and 11.720 + merging changes. They expose the narrative of how the code 11.721 + was developed.</para> 11.722 + </listitem></itemizedlist> 11.723 + </sect1> 11.724 + 11.725 + <sect1> 11.726 + <title>Managing big-picture branches in repositories</title> 11.727 + 11.728 + <para id="x_389">The easiest way to isolate a <quote>big picture</quote> 11.729 + branch in Mercurial is in a dedicated repository. If you have 11.730 + an existing shared repository&emdash;let's call it 11.731 + <literal>myproject</literal>&emdash;that reaches a 11.732 + <quote>1.0</quote> milestone, you can start to prepare for 11.733 + future maintenance releases on top of version 1.0 by tagging the 11.734 + revision from which you prepared the 1.0 release.</para> 11.735 + 11.736 + &interaction.branch-repo.tag; 11.737 + 11.738 + <para id="x_38a">You can then clone a new shared 11.739 + <literal>myproject-1.0.1</literal> repository as of that 11.740 + tag.</para> 11.741 + 11.742 + &interaction.branch-repo.clone; 11.743 + 11.744 + <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought 11.745 + to go into an upcoming 1.0.1 minor release, they clone the 11.746 + <literal>myproject-1.0.1</literal> repository, make their 11.747 + changes, and push them back.</para> 11.748 + 11.749 + &interaction.branch-repo.bugfix; 11.750 + 11.751 + <para id="x_38c">Meanwhile, development for 11.752 + the next major release can continue, isolated and unabated, in 11.753 + the <literal>myproject</literal> repository.</para> 11.754 + 11.755 + &interaction.branch-repo.new; 11.756 + </sect1> 11.757 + 11.758 + <sect1> 11.759 + <title>Don't repeat yourself: merging across branches</title> 11.760 + 11.761 + <para id="x_38d">In many cases, if you have a bug to fix on a maintenance 11.762 + branch, the chances are good that the bug exists on your 11.763 + project's main branch (and possibly other maintenance branches, 11.764 + too). It's a rare developer who wants to fix the same bug 11.765 + multiple times, so let's look at a few ways that Mercurial can 11.766 + help you to manage these bugfixes without duplicating your 11.767 + work.</para> 11.768 + 11.769 + <para id="x_38e">In the simplest instance, all you need to do is pull changes 11.770 + from your maintenance branch into your local clone of the target 11.771 + branch.</para> 11.772 + 11.773 + &interaction.branch-repo.pull; 11.774 + 11.775 + <para id="x_38f">You'll then need to merge the heads of the two branches, and 11.776 + push back to the main branch.</para> 11.777 + 11.778 + &interaction.branch-repo.merge; 11.779 + </sect1> 11.780 + 11.781 + <sect1> 11.782 + <title>Naming branches within one repository</title> 11.783 + 11.784 + <para id="x_390">In most instances, isolating branches in repositories is the 11.785 + right approach. Its simplicity makes it easy to understand; and 11.786 + so it's hard to make mistakes. There's a one-to-one 11.787 + relationship between branches you're working in and directories 11.788 + on your system. This lets you use normal (non-Mercurial-aware) 11.789 + tools to work on files within a branch/repository.</para> 11.790 + 11.791 + <para id="x_391">If you're more in the <quote>power user</quote> category 11.792 + (<emphasis>and</emphasis> your collaborators are too), there is 11.793 + an alternative way of handling branches that you can consider. 11.794 + I've already mentioned the human-level distinction between 11.795 + <quote>small picture</quote> and <quote>big picture</quote> 11.796 + branches. While Mercurial works with multiple <quote>small 11.797 + picture</quote> branches in a repository all the time (for 11.798 + example after you pull changes in, but before you merge them), 11.799 + it can <emphasis>also</emphasis> work with multiple <quote>big 11.800 + picture</quote> branches.</para> 11.801 + 11.802 + <para id="x_392">The key to working this way is that Mercurial lets you 11.803 + assign a persistent <emphasis>name</emphasis> to a branch. 11.804 + There always exists a branch named <literal>default</literal>. 11.805 + Even before you start naming branches yourself, you can find 11.806 + traces of the <literal>default</literal> branch if you look for 11.807 + them.</para> 11.808 + 11.809 + <para id="x_393">As an example, when you run the <command role="hg-cmd">hg 11.810 + commit</command> command, and it pops up your editor so that 11.811 + you can enter a commit message, look for a line that contains 11.812 + the text <quote><literal>HG: branch default</literal></quote> at 11.813 + the bottom. This is telling you that your commit will occur on 11.814 + the branch named <literal>default</literal>.</para> 11.815 + 11.816 + <para id="x_394">To start working with named branches, use the <command 11.817 + role="hg-cmd">hg branches</command> command. This command 11.818 + lists the named branches already present in your repository, 11.819 + telling you which changeset is the tip of each.</para> 11.820 + 11.821 + &interaction.branch-named.branches; 11.822 + 11.823 + <para id="x_395">Since you haven't created any named branches yet, the only 11.824 + one that exists is <literal>default</literal>.</para> 11.825 + 11.826 + <para id="x_396">To find out what the <quote>current</quote> branch is, run 11.827 + the <command role="hg-cmd">hg branch</command> command, giving 11.828 + it no arguments. This tells you what branch the parent of the 11.829 + current changeset is on.</para> 11.830 + 11.831 + &interaction.branch-named.branch; 11.832 + 11.833 + <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg 11.834 + branch</command> command again. This time, give it one 11.835 + argument: the name of the branch you want to create.</para> 11.836 + 11.837 + &interaction.branch-named.create; 11.838 + 11.839 + <para id="x_398">After you've created a branch, you might wonder what effect 11.840 + the <command role="hg-cmd">hg branch</command> command has had. 11.841 + What do the <command role="hg-cmd">hg status</command> and 11.842 + <command role="hg-cmd">hg tip</command> commands report?</para> 11.843 + 11.844 + &interaction.branch-named.status; 11.845 + 11.846 + <para id="x_399">Nothing has changed in the 11.847 + working directory, and there's been no new history created. As 11.848 + this suggests, running the <command role="hg-cmd">hg 11.849 + branch</command> command has no permanent effect; it only 11.850 + tells Mercurial what branch name to use the 11.851 + <emphasis>next</emphasis> time you commit a changeset.</para> 11.852 + 11.853 + <para id="x_39a">When you commit a change, Mercurial records the name of the 11.854 + branch on which you committed. Once you've switched from the 11.855 + <literal>default</literal> branch to another and committed, 11.856 + you'll see the name of the new branch show up in the output of 11.857 + <command role="hg-cmd">hg log</command>, <command 11.858 + role="hg-cmd">hg tip</command>, and other commands that 11.859 + display the same kind of output.</para> 11.860 + 11.861 + &interaction.branch-named.commit; 11.862 + 11.863 + <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands 11.864 + will print the branch name of every changeset that's not on the 11.865 + <literal>default</literal> branch. As a result, if you never 11.866 + use named branches, you'll never see this information.</para> 11.867 + 11.868 + <para id="x_39c">Once you've named a branch and committed a change with that 11.869 + name, every subsequent commit that descends from that change 11.870 + will inherit the same branch name. You can change the name of a 11.871 + branch at any time, using the <command role="hg-cmd">hg 11.872 + branch</command> command.</para> 11.873 + 11.874 + &interaction.branch-named.rebranch; 11.875 + 11.876 + <para id="x_39d">In practice, this is something you won't do very often, as 11.877 + branch names tend to have fairly long lifetimes. (This isn't a 11.878 + rule, just an observation.)</para> 11.879 + </sect1> 11.880 + 11.881 + <sect1> 11.882 + <title>Dealing with multiple named branches in a 11.883 + repository</title> 11.884 + 11.885 + <para id="x_39e">If you have more than one named branch in a repository, 11.886 + Mercurial will remember the branch that your working directory 11.887 + is on when you start a command like <command role="hg-cmd">hg 11.888 + update</command> or <command role="hg-cmd">hg pull 11.889 + -u</command>. It will update the working directory to the tip 11.890 + of this branch, no matter what the <quote>repo-wide</quote> tip 11.891 + is. To update to a revision that's on a different named branch, 11.892 + you may need to use the <option role="hg-opt-update">-C</option> 11.893 + option to <command role="hg-cmd">hg update</command>.</para> 11.894 + 11.895 + <para id="x_39f">This behavior is a little subtle, so let's see it in 11.896 + action. First, let's remind ourselves what branch we're 11.897 + currently on, and what branches are in our repository.</para> 11.898 + 11.899 + &interaction.branch-named.parents; 11.900 + 11.901 + <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also 11.902 + exists an older <command role="hg-cmd">hg foo</command> 11.903 + branch.</para> 11.904 + 11.905 + <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and 11.906 + forth between the tips of the <literal>foo</literal> and 11.907 + <literal>bar</literal> branches without needing to use the 11.908 + <option role="hg-opt-update">-C</option> option, because this 11.909 + only involves going backwards and forwards linearly through our 11.910 + change history.</para> 11.911 + 11.912 + &interaction.branch-named.update-switchy; 11.913 + 11.914 + <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then 11.915 + run <command role="hg-cmd">hg update</command>, it will keep us 11.916 + on <literal>foo</literal>, not move us to the tip of 11.917 + <literal>bar</literal>.</para> 11.918 + 11.919 + &interaction.branch-named.update-nothing; 11.920 + 11.921 + <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch 11.922 + introduces a new head.</para> 11.923 + 11.924 + &interaction.branch-named.foo-commit; 11.925 + </sect1> 11.926 + 11.927 + <sect1> 11.928 + <title>Branch names and merging</title> 11.929 + 11.930 + <para id="x_3a4">As you've probably noticed, merges in Mercurial are not 11.931 + symmetrical. Let's say our repository has two heads, 17 and 23. 11.932 + If I <command role="hg-cmd">hg update</command> to 17 and then 11.933 + <command role="hg-cmd">hg merge</command> with 23, Mercurial 11.934 + records 17 as the first parent of the merge, and 23 as the 11.935 + second. Whereas if I <command role="hg-cmd">hg update</command> 11.936 + to 23 and then <command role="hg-cmd">hg merge</command> with 11.937 + 17, it records 23 as the first parent, and 17 as the 11.938 + second.</para> 11.939 + 11.940 + <para id="x_3a5">This affects Mercurial's choice of branch name when you 11.941 + merge. After a merge, Mercurial will retain the branch name of 11.942 + the first parent when you commit the result of the merge. If 11.943 + your first parent's branch name is <literal>foo</literal>, and 11.944 + you merge with <literal>bar</literal>, the branch name will 11.945 + still be <literal>foo</literal> after you merge.</para> 11.946 + 11.947 + <para id="x_3a6">It's not unusual for a repository to contain multiple heads, 11.948 + each with the same branch name. Let's say I'm working on the 11.949 + <literal>foo</literal> branch, and so are you. We commit 11.950 + different changes; I pull your changes; I now have two heads, 11.951 + each claiming to be on the <literal>foo</literal> branch. The 11.952 + result of a merge will be a single head on the 11.953 + <literal>foo</literal> branch, as you might hope.</para> 11.954 + 11.955 + <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and 11.956 + I merge work from the <literal>foo</literal> branch, the result 11.957 + will remain on the <literal>bar</literal> branch.</para> 11.958 + 11.959 + &interaction.branch-named.merge; 11.960 + 11.961 + <para id="x_3a8">To give a more concrete example, if I'm working on the 11.962 + <literal>bleeding-edge</literal> branch, and I want to bring in 11.963 + the latest fixes from the <literal>stable</literal> branch, 11.964 + Mercurial will choose the <quote>right</quote> 11.965 + (<literal>bleeding-edge</literal>) branch name when I pull and 11.966 + merge from <literal>stable</literal>.</para> 11.967 + </sect1> 11.968 + 11.969 + <sect1> 11.970 + <title>Branch naming is generally useful</title> 11.971 + 11.972 + <para id="x_3a9">You shouldn't think of named branches as applicable only to 11.973 + situations where you have multiple long-lived branches 11.974 + cohabiting in a single repository. They're very useful even in 11.975 + the one-branch-per-repository case.</para> 11.976 + 11.977 + <para id="x_3aa">In the simplest case, giving a name to each branch gives you 11.978 + a permanent record of which branch a changeset originated on. 11.979 + This gives you more context when you're trying to follow the 11.980 + history of a long-lived branchy project.</para> 11.981 + 11.982 + <para id="x_3ab">If you're working with shared repositories, you can set up a 11.983 + <literal role="hook">pretxnchangegroup</literal> hook on each 11.984 + that will block incoming changes that have the 11.985 + <quote>wrong</quote> branch name. This provides a simple, but 11.986 + effective, defence against people accidentally pushing changes 11.987 + from a <quote>bleeding edge</quote> branch to a 11.988 + <quote>stable</quote> branch. Such a hook might look like this 11.989 + inside the shared repo's <filename role="special"> 11.990 + /.hgrc</filename>.</para> 11.991 + <programlisting>[hooks] 11.992 +pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 11.993 + </sect1> 11.994 </chapter> 11.995 11.996 <!-- 11.997 local variables: 11.998 sgml-parent-document: ("00book.xml" "book" "chapter") 11.999 end: 11.1000 ---> 11.1001 \ No newline at end of file 11.1002 +-->
12.1 --- a/fr/ch09-undo.xml Sat Sep 12 17:58:26 2009 +0200 12.2 +++ b/fr/ch09-undo.xml Sat Sep 12 17:58:56 2009 +0200 12.3 @@ -1,963 +1,1201 @@ 12.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 12.5 12.6 -<chapter> 12.7 -<title>Finding and fixing your mistakes</title> 12.8 -<para>\label{chap:undo}</para> 12.9 - 12.10 -<para>To err might be human, but to really handle the consequences well 12.11 -takes a top-notch revision control system. In this chapter, we'll 12.12 -discuss some of the techniques you can use when you find that a 12.13 -problem has crept into your project. Mercurial has some highly 12.14 -capable features that will help you to isolate the sources of 12.15 -problems, and to handle them appropriately.</para> 12.16 - 12.17 -<sect1> 12.18 -<title>Erasing local history</title> 12.19 - 12.20 -<sect2> 12.21 -<title>The accidental commit</title> 12.22 - 12.23 -<para>I have the occasional but persistent problem of typing rather more 12.24 -quickly than I can think, which sometimes results in me committing a 12.25 -changeset that is either incomplete or plain wrong. In my case, the 12.26 -usual kind of incomplete changeset is one in which I've created a new 12.27 -source file, but forgotten to <command role="hg-cmd">hg add</command> it. A <quote>plain wrong</quote> 12.28 -changeset is not as common, but no less annoying.</para> 12.29 - 12.30 -</sect2> 12.31 -<sect2> 12.32 -<title>Rolling back a transaction</title> 12.33 -<para>\label{sec:undo:rollback}</para> 12.34 - 12.35 -<para>In section <xref linkend="sec:concepts:txn"/>, I mentioned that Mercurial treats 12.36 -each modification of a repository as a <emphasis>transaction</emphasis>. Every time 12.37 -you commit a changeset or pull changes from another repository, 12.38 -Mercurial remembers what you did. You can undo, or <emphasis>roll back</emphasis>, 12.39 -exactly one of these actions using the <command role="hg-cmd">hg rollback</command> command. (See 12.40 -section <xref linkend="sec:undo:rollback-after-push"/> for an important caveat 12.41 -about the use of this command.)</para> 12.42 - 12.43 -<para>Here's a mistake that I often find myself making: committing a change 12.44 -in which I've created a new file, but forgotten to <command role="hg-cmd">hg add</command> it. 12.45 -<!-- &interaction.rollback.commit; --> 12.46 -Looking at the output of <command role="hg-cmd">hg status</command> after the commit immediately 12.47 -confirms the error. 12.48 -<!-- &interaction.rollback.status; --> 12.49 -The commit captured the changes to the file <filename>a</filename>, but not the 12.50 -new file <filename>b</filename>. If I were to push this changeset to a 12.51 -repository that I shared with a colleague, the chances are high that 12.52 -something in <filename>a</filename> would refer to <filename>b</filename>, which would not 12.53 -be present in their repository when they pulled my changes. I would 12.54 -thus become the object of some indignation.</para> 12.55 - 12.56 -<para>However, luck is with me&emdash;I've caught my error before I pushed the 12.57 -changeset. I use the <command role="hg-cmd">hg rollback</command> command, and Mercurial makes 12.58 -that last changeset vanish. 12.59 -<!-- &interaction.rollback.rollback; --> 12.60 -Notice that the changeset is no longer present in the repository's 12.61 -history, and the working directory once again thinks that the file 12.62 -<filename>a</filename> is modified. The commit and rollback have left the 12.63 -working directory exactly as it was prior to the commit; the changeset 12.64 -has been completely erased. I can now safely <command role="hg-cmd">hg add</command> the file 12.65 -<filename>b</filename>, and rerun my commit. 12.66 -<!-- &interaction.rollback.add; --></para> 12.67 - 12.68 -</sect2> 12.69 -<sect2> 12.70 -<title>The erroneous pull</title> 12.71 - 12.72 -<para>It's common practice with Mercurial to maintain separate development 12.73 -branches of a project in different repositories. Your development 12.74 -team might have one shared repository for your project's <quote>0.9</quote> 12.75 -release, and another, containing different changes, for the <quote>1.0</quote> 12.76 -release.</para> 12.77 - 12.78 -<para>Given this, you can imagine that the consequences could be messy if 12.79 -you had a local <quote>0.9</quote> repository, and accidentally pulled changes 12.80 -from the shared <quote>1.0</quote> repository into it. At worst, you could be 12.81 -paying insufficient attention, and push those changes into the shared 12.82 -<quote>0.9</quote> tree, confusing your entire team (but don't worry, we'll 12.83 -return to this horror scenario later). However, it's more likely that 12.84 -you'll notice immediately, because Mercurial will display the URL it's 12.85 -pulling from, or you will see it pull a suspiciously large number of 12.86 -changes into the repository. 12.87 -</para> 12.88 - 12.89 -<para>The <command role="hg-cmd">hg rollback</command> command will work nicely to expunge all of the 12.90 -changesets that you just pulled. Mercurial groups all changes from 12.91 -one <command role="hg-cmd">hg pull</command> into a single transaction, so one <command role="hg-cmd">hg rollback</command> is 12.92 -all you need to undo this mistake. 12.93 -</para> 12.94 - 12.95 -</sect2> 12.96 -<sect2> 12.97 -<title>Rolling back is useless once you've pushed</title> 12.98 -<para>\label{sec:undo:rollback-after-push} 12.99 -</para> 12.100 - 12.101 -<para>The value of the <command role="hg-cmd">hg rollback</command> command drops to zero once you've 12.102 -pushed your changes to another repository. Rolling back a change 12.103 -makes it disappear entirely, but <emphasis>only</emphasis> in the repository in 12.104 -which you perform the <command role="hg-cmd">hg rollback</command>. Because a rollback eliminates 12.105 -history, there's no way for the disappearance of a change to propagate 12.106 -between repositories. 12.107 -</para> 12.108 - 12.109 -<para>If you've pushed a change to another repository&emdash;particularly if it's 12.110 -a shared repository&emdash;it has essentially <quote>escaped into the wild,</quote> 12.111 -and you'll have to recover from your mistake in a different way. What 12.112 -will happen if you push a changeset somewhere, then roll it back, then 12.113 -pull from the repository you pushed to, is that the changeset will 12.114 -reappear in your repository. 12.115 -</para> 12.116 - 12.117 -<para>(If you absolutely know for sure that the change you want to roll back 12.118 -is the most recent change in the repository that you pushed to, 12.119 -<emphasis>and</emphasis> you know that nobody else could have pulled it from that 12.120 -repository, you can roll back the changeset there, too, but you really 12.121 -should really not rely on this working reliably. If you do this, 12.122 -sooner or later a change really will make it into a repository that 12.123 -you don't directly control (or have forgotten about), and come back to 12.124 -bite you.) 12.125 -</para> 12.126 - 12.127 -</sect2> 12.128 -<sect2> 12.129 -<title>You can only roll back once</title> 12.130 - 12.131 -<para>Mercurial stores exactly one transaction in its transaction log; that 12.132 -transaction is the most recent one that occurred in the repository. 12.133 -This means that you can only roll back one transaction. If you expect 12.134 -to be able to roll back one transaction, then its predecessor, this is 12.135 -not the behaviour you will get. 12.136 -<!-- &interaction.rollback.twice; --> 12.137 -Once you've rolled back one transaction in a repository, you can't 12.138 -roll back again in that repository until you perform another commit or 12.139 -pull. 12.140 -</para> 12.141 - 12.142 -</sect2> 12.143 -</sect1> 12.144 -<sect1> 12.145 -<title>Reverting the mistaken change</title> 12.146 - 12.147 -<para>If you make a modification to a file, and decide that you really 12.148 -didn't want to change the file at all, and you haven't yet committed 12.149 -your changes, the <command role="hg-cmd">hg revert</command> command is the one you'll need. It 12.150 -looks at the changeset that's the parent of the working directory, and 12.151 -restores the contents of the file to their state as of that changeset. 12.152 -(That's a long-winded way of saying that, in the normal case, it 12.153 -undoes your modifications.) 12.154 -</para> 12.155 - 12.156 -<para>Let's illustrate how the <command role="hg-cmd">hg revert</command> command works with yet another 12.157 -small example. We'll begin by modifying a file that Mercurial is 12.158 -already tracking. 12.159 -<!-- &interaction.daily.revert.modify; --> 12.160 -If we don't want that change, we can simply <command role="hg-cmd">hg revert</command> the file. 12.161 -<!-- &interaction.daily.revert.unmodify; --> 12.162 -The <command role="hg-cmd">hg revert</command> command provides us with an extra degree of safety 12.163 -by saving our modified file with a <filename>.orig</filename> extension. 12.164 -<!-- &interaction.daily.revert.status; --> 12.165 -</para> 12.166 - 12.167 -<para>Here is a summary of the cases that the <command role="hg-cmd">hg revert</command> command can 12.168 -deal with. We will describe each of these in more detail in the 12.169 -section that follows. 12.170 -</para> 12.171 -<itemizedlist> 12.172 -<listitem><para>If you modify a file, it will restore the file to its unmodified 12.173 - state. 12.174 -</para> 12.175 -</listitem> 12.176 -<listitem><para>If you <command role="hg-cmd">hg add</command> a file, it will undo the <quote>added</quote> state of 12.177 - the file, but leave the file itself untouched. 12.178 -</para> 12.179 -</listitem> 12.180 -<listitem><para>If you delete a file without telling Mercurial, it will restore 12.181 - the file to its unmodified contents. 12.182 -</para> 12.183 -</listitem> 12.184 -<listitem><para>If you use the <command role="hg-cmd">hg remove</command> command to remove a file, it will 12.185 - undo the <quote>removed</quote> state of the file, and restore the file to its 12.186 - unmodified contents. 12.187 -</para> 12.188 -</listitem></itemizedlist> 12.189 - 12.190 -<sect2> 12.191 -<title>File management errors</title> 12.192 -<para>\label{sec:undo:mgmt} 12.193 -</para> 12.194 - 12.195 -<para>The <command role="hg-cmd">hg revert</command> command is useful for more than just modified 12.196 -files. It lets you reverse the results of all of Mercurial's file 12.197 -management commands&emdash;<command role="hg-cmd">hg add</command>, <command role="hg-cmd">hg remove</command>, and so on. 12.198 -</para> 12.199 - 12.200 -<para>If you <command role="hg-cmd">hg add</command> a file, then decide that in fact you don't want 12.201 -Mercurial to track it, use <command role="hg-cmd">hg revert</command> to undo the add. Don't 12.202 -worry; Mercurial will not modify the file in any way. It will just 12.203 -<quote>unmark</quote> the file. 12.204 -<!-- &interaction.daily.revert.add; --> 12.205 -</para> 12.206 - 12.207 -<para>Similarly, if you ask Mercurial to <command role="hg-cmd">hg remove</command> a file, you can use 12.208 -<command role="hg-cmd">hg revert</command> to restore it to the contents it had as of the parent 12.209 -of the working directory. 12.210 -<!-- &interaction.daily.revert.remove; --> 12.211 -This works just as well for a file that you deleted by hand, without 12.212 -telling Mercurial (recall that in Mercurial terminology, this kind of 12.213 -file is called <quote>missing</quote>). 12.214 -<!-- &interaction.daily.revert.missing; --> 12.215 -</para> 12.216 - 12.217 -<para>If you revert a <command role="hg-cmd">hg copy</command>, the copied-to file remains in your 12.218 -working directory afterwards, untracked. Since a copy doesn't affect 12.219 -the copied-from file in any way, Mercurial doesn't do anything with 12.220 -the copied-from file. 12.221 -<!-- &interaction.daily.revert.copy; --> 12.222 -</para> 12.223 - 12.224 -<sect3> 12.225 -<title>A slightly special case: reverting a rename</title> 12.226 - 12.227 -<para>If you <command role="hg-cmd">hg rename</command> a file, there is one small detail that 12.228 -you should remember. When you <command role="hg-cmd">hg revert</command> a rename, it's not 12.229 -enough to provide the name of the renamed-to file, as you can see 12.230 -here. 12.231 -<!-- &interaction.daily.revert.rename; --> 12.232 -As you can see from the output of <command role="hg-cmd">hg status</command>, the renamed-to file 12.233 -is no longer identified as added, but the renamed-<emphasis>from</emphasis> file is 12.234 -still removed! This is counter-intuitive (at least to me), but at 12.235 -least it's easy to deal with. 12.236 -<!-- &interaction.daily.revert.rename-orig; --> 12.237 -So remember, to revert a <command role="hg-cmd">hg rename</command>, you must provide <emphasis>both</emphasis> 12.238 -the source and destination names. 12.239 -</para> 12.240 - 12.241 -<para>% TODO: the output doesn't look like it will be removed! 12.242 -</para> 12.243 - 12.244 -<para>(By the way, if you rename a file, then modify the renamed-to file, 12.245 -then revert both components of the rename, when Mercurial restores the 12.246 -file that was removed as part of the rename, it will be unmodified. 12.247 -If you need the modifications in the renamed-to file to show up in the 12.248 -renamed-from file, don't forget to copy them over.) 12.249 -</para> 12.250 - 12.251 -<para>These fiddly aspects of reverting a rename arguably constitute a small 12.252 -bug in Mercurial. 12.253 -</para> 12.254 - 12.255 -</sect3> 12.256 -</sect2> 12.257 -</sect1> 12.258 -<sect1> 12.259 -<title>Dealing with committed changes</title> 12.260 - 12.261 -<para>Consider a case where you have committed a change $a$, and another 12.262 -change $b$ on top of it; you then realise that change $a$ was 12.263 -incorrect. Mercurial lets you <quote>back out</quote> an entire changeset 12.264 -automatically, and building blocks that let you reverse part of a 12.265 -changeset by hand. 12.266 -</para> 12.267 - 12.268 -<para>Before you read this section, here's something to keep in mind: the 12.269 -<command role="hg-cmd">hg backout</command> command undoes changes by <emphasis>adding</emphasis> history, not 12.270 -by modifying or erasing it. It's the right tool to use if you're 12.271 -fixing bugs, but not if you're trying to undo some change that has 12.272 -catastrophic consequences. To deal with those, see 12.273 -section <xref linkend="sec:undo:aaaiiieee"/>. 12.274 -</para> 12.275 - 12.276 -<sect2> 12.277 -<title>Backing out a changeset</title> 12.278 - 12.279 -<para>The <command role="hg-cmd">hg backout</command> command lets you <quote>undo</quote> the effects of an entire 12.280 -changeset in an automated fashion. Because Mercurial's history is 12.281 -immutable, this command <emphasis>does not</emphasis> get rid of the changeset you 12.282 -want to undo. Instead, it creates a new changeset that 12.283 -<emphasis>reverses</emphasis> the effect of the to-be-undone changeset. 12.284 -</para> 12.285 - 12.286 -<para>The operation of the <command role="hg-cmd">hg backout</command> command is a little intricate, so 12.287 -let's illustrate it with some examples. First, we'll create a 12.288 -repository with some simple changes. 12.289 -<!-- &interaction.backout.init; --> 12.290 -</para> 12.291 - 12.292 -<para>The <command role="hg-cmd">hg backout</command> command takes a single changeset ID as its 12.293 -argument; this is the changeset to back out. Normally, 12.294 -<command role="hg-cmd">hg backout</command> will drop you into a text editor to write a commit 12.295 -message, so you can record why you're backing the change out. In this 12.296 -example, we provide a commit message on the command line using the 12.297 -<option role="hg-opt-backout">-m</option> option. 12.298 -</para> 12.299 - 12.300 -</sect2> 12.301 -<sect2> 12.302 -<title>Backing out the tip changeset</title> 12.303 - 12.304 -<para>We're going to start by backing out the last changeset we committed. 12.305 -<!-- &interaction.backout.simple; --> 12.306 -You can see that the second line from <filename>myfile</filename> is no longer 12.307 -present. Taking a look at the output of <command role="hg-cmd">hg log</command> gives us an idea 12.308 -of what the <command role="hg-cmd">hg backout</command> command has done. 12.309 -<!-- &interaction.backout.simple.log; --> 12.310 -Notice that the new changeset that <command role="hg-cmd">hg backout</command> has created is a 12.311 -child of the changeset we backed out. It's easier to see this in 12.312 -figure <xref linkend="fig:undo:backout"/>, which presents a graphical view of the 12.313 -change history. As you can see, the history is nice and linear. 12.314 -</para> 12.315 - 12.316 -<informalfigure> 12.317 - 12.318 -<para> <mediaobject><imageobject><imagedata fileref="undo-simple"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 12.319 - <caption><para>Backing out a change using the <command role="hg-cmd">hg backout</command> command</para></caption> 12.320 - \label{fig:undo:backout} 12.321 -</para> 12.322 -</informalfigure> 12.323 - 12.324 -</sect2> 12.325 -<sect2> 12.326 -<title>Backing out a non-tip change</title> 12.327 - 12.328 -<para>If you want to back out a change other than the last one you 12.329 -committed, pass the <option role="hg-opt-backout">--merge</option> option to the 12.330 -<command role="hg-cmd">hg backout</command> command. 12.331 -<!-- &interaction.backout.non-tip.clone; --> 12.332 -This makes backing out any changeset a <quote>one-shot</quote> operation that's 12.333 -usually simple and fast. 12.334 -<!-- &interaction.backout.non-tip.backout; --> 12.335 -</para> 12.336 - 12.337 -<para>If you take a look at the contents of <filename>myfile</filename> after the 12.338 -backout finishes, you'll see that the first and third changes are 12.339 -present, but not the second. 12.340 -<!-- &interaction.backout.non-tip.cat; --> 12.341 -</para> 12.342 - 12.343 -<para>As the graphical history in figure <xref linkend="fig:undo:backout-non-tip"/> 12.344 -illustrates, Mercurial actually commits <emphasis>two</emphasis> changes in this 12.345 -kind of situation (the box-shaped nodes are the ones that Mercurial 12.346 -commits automatically). Before Mercurial begins the backout process, 12.347 -it first remembers what the current parent of the working directory 12.348 -is. It then backs out the target changeset, and commits that as a 12.349 -changeset. Finally, it merges back to the previous parent of the 12.350 -working directory, and commits the result of the merge. 12.351 -</para> 12.352 - 12.353 -<para>% TODO: to me it looks like mercurial doesn't commit the second merge automatically! 12.354 -</para> 12.355 - 12.356 -<informalfigure> 12.357 - 12.358 -<para> <mediaobject><imageobject><imagedata fileref="undo-non-tip"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 12.359 - <caption><para>Automated backout of a non-tip change using the <command role="hg-cmd">hg backout</command> command</para></caption> 12.360 - \label{fig:undo:backout-non-tip} 12.361 -</para> 12.362 -</informalfigure> 12.363 - 12.364 -<para>The result is that you end up <quote>back where you were</quote>, only with some 12.365 -extra history that undoes the effect of the changeset you wanted to 12.366 -back out. 12.367 -</para> 12.368 - 12.369 -<sect3> 12.370 -<title>Always use the <option role="hg-opt-backout">--merge</option> option</title> 12.371 - 12.372 -<para>In fact, since the <option role="hg-opt-backout">--merge</option> option will do the <quote>right 12.373 -thing</quote> whether or not the changeset you're backing out is the tip 12.374 -(i.e. it won't try to merge if it's backing out the tip, since there's 12.375 -no need), you should <emphasis>always</emphasis> use this option when you run the 12.376 -<command role="hg-cmd">hg backout</command> command. 12.377 -</para> 12.378 - 12.379 -</sect3> 12.380 -</sect2> 12.381 -<sect2> 12.382 -<title>Gaining more control of the backout process</title> 12.383 - 12.384 -<para>While I've recommended that you always use the 12.385 -<option role="hg-opt-backout">--merge</option> option when backing out a change, the 12.386 -<command role="hg-cmd">hg backout</command> command lets you decide how to merge a backout 12.387 -changeset. Taking control of the backout process by hand is something 12.388 -you will rarely need to do, but it can be useful to understand what 12.389 -the <command role="hg-cmd">hg backout</command> command is doing for you automatically. To 12.390 -illustrate this, let's clone our first repository, but omit the 12.391 -backout change that it contains. 12.392 -</para> 12.393 - 12.394 -<para><!-- &interaction.backout.manual.clone; --> 12.395 -As with our earlier example, We'll commit a third changeset, then back 12.396 -out its parent, and see what happens. 12.397 -<!-- &interaction.backout.manual.backout; --> 12.398 -Our new changeset is again a descendant of the changeset we backout 12.399 -out; it's thus a new head, <emphasis>not</emphasis> a descendant of the changeset 12.400 -that was the tip. The <command role="hg-cmd">hg backout</command> command was quite explicit in 12.401 -telling us this. 12.402 -<!-- &interaction.backout.manual.log; --> 12.403 -</para> 12.404 - 12.405 -<para>Again, it's easier to see what has happened by looking at a graph of 12.406 -the revision history, in figure <xref linkend="fig:undo:backout-manual"/>. This 12.407 -makes it clear that when we use <command role="hg-cmd">hg backout</command> to back out a change 12.408 -other than the tip, Mercurial adds a new head to the repository (the 12.409 -change it committed is box-shaped). 12.410 -</para> 12.411 - 12.412 -<informalfigure> 12.413 - 12.414 -<para> <mediaobject><imageobject><imagedata fileref="undo-manual"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 12.415 - <caption><para>Backing out a change using the <command role="hg-cmd">hg backout</command> command</para></caption> 12.416 - \label{fig:undo:backout-manual} 12.417 -</para> 12.418 -</informalfigure> 12.419 - 12.420 -<para>After the <command role="hg-cmd">hg backout</command> command has completed, it leaves the new 12.421 -<quote>backout</quote> changeset as the parent of the working directory. 12.422 -<!-- &interaction.backout.manual.parents; --> 12.423 -Now we have two isolated sets of changes. 12.424 -<!-- &interaction.backout.manual.heads; --> 12.425 -</para> 12.426 - 12.427 -<para>Let's think about what we expect to see as the contents of 12.428 -<filename>myfile</filename> now. The first change should be present, because 12.429 -we've never backed it out. The second change should be missing, as 12.430 -that's the change we backed out. Since the history graph shows the 12.431 -third change as a separate head, we <emphasis>don't</emphasis> expect to see the 12.432 -third change present in <filename>myfile</filename>. 12.433 -<!-- &interaction.backout.manual.cat; --> 12.434 -To get the third change back into the file, we just do a normal merge 12.435 -of our two heads. 12.436 -<!-- &interaction.backout.manual.merge; --> 12.437 -Afterwards, the graphical history of our repository looks like 12.438 -figure <xref linkend="fig:undo:backout-manual-merge"/>. 12.439 -</para> 12.440 - 12.441 -<informalfigure> 12.442 - 12.443 -<para> <mediaobject><imageobject><imagedata fileref="undo-manual-merge"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 12.444 - <caption><para>Manually merging a backout change</para></caption> 12.445 - \label{fig:undo:backout-manual-merge} 12.446 -</para> 12.447 -</informalfigure> 12.448 - 12.449 -</sect2> 12.450 -<sect2> 12.451 -<title>Why <command role="hg-cmd">hg backout</command> works as it does</title> 12.452 - 12.453 -<para>Here's a brief description of how the <command role="hg-cmd">hg backout</command> command works. 12.454 -</para> 12.455 -<orderedlist> 12.456 -<listitem><para>It ensures that the working directory is <quote>clean</quote>, i.e. that 12.457 - the output of <command role="hg-cmd">hg status</command> would be empty. 12.458 -</para> 12.459 -</listitem> 12.460 -<listitem><para>It remembers the current parent of the working directory. Let's 12.461 - call this changeset <literal>orig</literal> 12.462 -</para> 12.463 -</listitem> 12.464 -<listitem><para>It does the equivalent of a <command role="hg-cmd">hg update</command> to sync the working 12.465 - directory to the changeset you want to back out. Let's call this 12.466 - changeset <literal>backout</literal> 12.467 -</para> 12.468 -</listitem> 12.469 -<listitem><para>It finds the parent of that changeset. Let's call that 12.470 - changeset <literal>parent</literal>. 12.471 -</para> 12.472 -</listitem> 12.473 -<listitem><para>For each file that the <literal>backout</literal> changeset affected, it 12.474 - does the equivalent of a <command role="hg-cmd">hg revert -r parent</command> on that file, 12.475 - to restore it to the contents it had before that changeset was 12.476 - committed. 12.477 -</para> 12.478 -</listitem> 12.479 -<listitem><para>It commits the result as a new changeset. This changeset has 12.480 - <literal>backout</literal> as its parent. 12.481 -</para> 12.482 -</listitem> 12.483 -<listitem><para>If you specify <option role="hg-opt-backout">--merge</option> on the command line, it 12.484 - merges with <literal>orig</literal>, and commits the result of the merge. 12.485 -</para> 12.486 -</listitem></orderedlist> 12.487 - 12.488 -<para>An alternative way to implement the <command role="hg-cmd">hg backout</command> command would be 12.489 -to <command role="hg-cmd">hg export</command> the to-be-backed-out changeset as a diff, then use 12.490 -the <option role="cmd-opt-patch">--reverse</option> option to the <command>patch</command> command to 12.491 -reverse the effect of the change without fiddling with the working 12.492 -directory. This sounds much simpler, but it would not work nearly as 12.493 -well. 12.494 -</para> 12.495 - 12.496 -<para>The reason that <command role="hg-cmd">hg backout</command> does an update, a commit, a merge, and 12.497 -another commit is to give the merge machinery the best chance to do a 12.498 -good job when dealing with all the changes <emphasis>between</emphasis> the change 12.499 -you're backing out and the current tip. 12.500 -</para> 12.501 - 12.502 -<para>If you're backing out a changeset that's 100 revisions back in your 12.503 -project's history, the chances that the <command>patch</command> command will 12.504 -be able to apply a reverse diff cleanly are not good, because 12.505 -intervening changes are likely to have <quote>broken the context</quote> that 12.506 -<command>patch</command> uses to determine whether it can apply a patch (if 12.507 -this sounds like gibberish, see <xref linkend="sec:mq:patch"/> for a 12.508 -discussion of the <command>patch</command> command). Also, Mercurial's merge 12.509 -machinery will handle files and directories being renamed, permission 12.510 -changes, and modifications to binary files, none of which 12.511 -<command>patch</command> can deal with. 12.512 -</para> 12.513 - 12.514 -</sect2> 12.515 -</sect1> 12.516 -<sect1> 12.517 -<title>Changes that should never have been</title> 12.518 -<para>\label{sec:undo:aaaiiieee} 12.519 -</para> 12.520 - 12.521 -<para>Most of the time, the <command role="hg-cmd">hg backout</command> command is exactly what you need 12.522 -if you want to undo the effects of a change. It leaves a permanent 12.523 -record of exactly what you did, both when committing the original 12.524 -changeset and when you cleaned up after it. 12.525 -</para> 12.526 - 12.527 -<para>On rare occasions, though, you may find that you've committed a change 12.528 -that really should not be present in the repository at all. For 12.529 -example, it would be very unusual, and usually considered a mistake, 12.530 -to commit a software project's object files as well as its source 12.531 -files. Object files have almost no intrinsic value, and they're 12.532 -<emphasis>big</emphasis>, so they increase the size of the repository and the amount 12.533 -of time it takes to clone or pull changes. 12.534 -</para> 12.535 - 12.536 -<para>Before I discuss the options that you have if you commit a <quote>brown 12.537 -paper bag</quote> change (the kind that's so bad that you want to pull a 12.538 -brown paper bag over your head), let me first discuss some approaches 12.539 -that probably won't work. 12.540 -</para> 12.541 - 12.542 -<para>Since Mercurial treats history as accumulative&emdash;every change builds 12.543 -on top of all changes that preceded it&emdash;you generally can't just make 12.544 -disastrous changes disappear. The one exception is when you've just 12.545 -committed a change, and it hasn't been pushed or pulled into another 12.546 -repository. That's when you can safely use the <command role="hg-cmd">hg rollback</command> 12.547 -command, as I detailed in section <xref linkend="sec:undo:rollback"/>. 12.548 -</para> 12.549 - 12.550 -<para>After you've pushed a bad change to another repository, you 12.551 -<emphasis>could</emphasis> still use <command role="hg-cmd">hg rollback</command> to make your local copy of the 12.552 -change disappear, but it won't have the consequences you want. The 12.553 -change will still be present in the remote repository, so it will 12.554 -reappear in your local repository the next time you pull. 12.555 -</para> 12.556 - 12.557 -<para>If a situation like this arises, and you know which repositories your 12.558 -bad change has propagated into, you can <emphasis>try</emphasis> to get rid of the 12.559 -changeefrom <emphasis>every</emphasis> one of those repositories. This is, of 12.560 -course, not a satisfactory solution: if you miss even a single 12.561 -repository while you're expunging, the change is still <quote>in the 12.562 -wild</quote>, and could propagate further. 12.563 -</para> 12.564 - 12.565 -<para>If you've committed one or more changes <emphasis>after</emphasis> the change that 12.566 -you'd like to see disappear, your options are further reduced. 12.567 -Mercurial doesn't provide a way to <quote>punch a hole</quote> in history, 12.568 -leaving changesets intact. 12.569 -</para> 12.570 - 12.571 -<para>XXX This needs filling out. The <literal>hg-replay</literal> script in the 12.572 -<literal>examples</literal> directory works, but doesn't handle merge 12.573 -changesets. Kind of an important omission. 12.574 -</para> 12.575 - 12.576 -<sect2> 12.577 -<title>Protect yourself from <quote>escaped</quote> changes</title> 12.578 - 12.579 -<para>If you've committed some changes to your local repository and they've 12.580 -been pushed or pulled somewhere else, this isn't necessarily a 12.581 -disaster. You can protect yourself ahead of time against some classes 12.582 -of bad changeset. This is particularly easy if your team usually 12.583 -pulls changes from a central repository. 12.584 -</para> 12.585 - 12.586 -<para>By configuring some hooks on that repository to validate incoming 12.587 -changesets (see chapter <xref linkend="chap:hook"/>), you can automatically 12.588 -prevent some kinds of bad changeset from being pushed to the central 12.589 -repository at all. With such a configuration in place, some kinds of 12.590 -bad changeset will naturally tend to <quote>die out</quote> because they can't 12.591 -propagate into the central repository. Better yet, this happens 12.592 -without any need for explicit intervention. 12.593 -</para> 12.594 - 12.595 -<para>For instance, an incoming change hook that verifies that a changeset 12.596 -will actually compile can prevent people from inadvertantly <quote>breaking 12.597 -the build</quote>. 12.598 -</para> 12.599 - 12.600 -</sect2> 12.601 -</sect1> 12.602 -<sect1> 12.603 -<title>Finding the source of a bug</title> 12.604 -<para>\label{sec:undo:bisect} 12.605 -</para> 12.606 - 12.607 -<para>While it's all very well to be able to back out a changeset that 12.608 -introduced a bug, this requires that you know which changeset to back 12.609 -out. Mercurial provides an invaluable command, called 12.610 -<command role="hg-cmd">hg bisect</command>, that helps you to automate this process and accomplish 12.611 -it very efficiently. 12.612 -</para> 12.613 - 12.614 -<para>The idea behind the <command role="hg-cmd">hg bisect</command> command is that a changeset has 12.615 -introduced some change of behaviour that you can identify with a 12.616 -simple binary test. You don't know which piece of code introduced the 12.617 -change, but you know how to test for the presence of the bug. The 12.618 -<command role="hg-cmd">hg bisect</command> command uses your test to direct its search for the 12.619 -changeset that introduced the code that caused the bug. 12.620 -</para> 12.621 - 12.622 -<para>Here are a few scenarios to help you understand how you might apply 12.623 -this command. 12.624 -</para> 12.625 -<itemizedlist> 12.626 -<listitem><para>The most recent version of your software has a bug that you 12.627 - remember wasn't present a few weeks ago, but you don't know when it 12.628 - was introduced. Here, your binary test checks for the presence of 12.629 - that bug. 12.630 -</para> 12.631 -</listitem> 12.632 -<listitem><para>You fixed a bug in a rush, and now it's time to close the entry 12.633 - in your team's bug database. The bug database requires a changeset 12.634 - ID when you close an entry, but you don't remember which changeset 12.635 - you fixed the bug in. Once again, your binary test checks for the 12.636 - presence of the bug. 12.637 -</para> 12.638 -</listitem> 12.639 -<listitem><para>Your software works correctly, but runs 15% slower than the 12.640 - last time you measured it. You want to know which changeset 12.641 - introduced the performance regression. In this case, your binary 12.642 - test measures the performance of your software, to see whether it's 12.643 - <quote>fast</quote> or <quote>slow</quote>. 12.644 -</para> 12.645 -</listitem> 12.646 -<listitem><para>The sizes of the components of your project that you ship 12.647 - exploded recently, and you suspect that something changed in the way 12.648 - you build your project. 12.649 -</para> 12.650 -</listitem></itemizedlist> 12.651 - 12.652 -<para>From these examples, it should be clear that the <command role="hg-cmd">hg bisect</command> 12.653 -command is not useful only for finding the sources of bugs. You can 12.654 -use it to find any <quote>emergent property</quote> of a repository (anything 12.655 -that you can't find from a simple text search of the files in the 12.656 -tree) for which you can write a binary test. 12.657 -</para> 12.658 - 12.659 -<para>We'll introduce a little bit of terminology here, just to make it 12.660 -clear which parts of the search process are your responsibility, and 12.661 -which are Mercurial's. A <emphasis>test</emphasis> is something that <emphasis>you</emphasis> run 12.662 -when <command role="hg-cmd">hg bisect</command> chooses a changeset. A <emphasis>probe</emphasis> is what 12.663 -<command role="hg-cmd">hg bisect</command> runs to tell whether a revision is good. Finally, 12.664 -we'll use the word <quote>bisect</quote>, as both a noun and a verb, to stand in 12.665 -for the phrase <quote>search using the <command role="hg-cmd">hg bisect</command> command. 12.666 -</para> 12.667 - 12.668 -<para>One simple way to automate the searching process would be simply to 12.669 -probe every changeset. However, this scales poorly. If it took ten 12.670 -minutes to test a single changeset, and you had 10,000 changesets in 12.671 -your repository, the exhaustive approach would take on average 35 12.672 -<emphasis>days</emphasis> to find the changeset that introduced a bug. Even if you 12.673 -knew that the bug was introduced by one of the last 500 changesets, 12.674 -and limited your search to those, you'd still be looking at over 40 12.675 -hours to find the changeset that introduced your bug. 12.676 -</para> 12.677 - 12.678 -<para>What the <command role="hg-cmd">hg bisect</command> command does is use its knowledge of the 12.679 -<quote>shape</quote> of your project's revision history to perform a search in 12.680 -time proportional to the <emphasis>logarithm</emphasis> of the number of changesets 12.681 -to check (the kind of search it performs is called a dichotomic 12.682 -search). With this approach, searching through 10,000 changesets will 12.683 -take less than three hours, even at ten minutes per test (the search 12.684 -will require about 14 tests). Limit your search to the last hundred 12.685 -changesets, and it will take only about an hour (roughly seven tests). 12.686 -</para> 12.687 - 12.688 -<para>The <command role="hg-cmd">hg bisect</command> command is aware of the <quote>branchy</quote> nature of a 12.689 -Mercurial project's revision history, so it has no problems dealing 12.690 -with branches, merges, or multiple heads in a repository. It can 12.691 -prune entire branches of history with a single probe, which is how it 12.692 -operates so efficiently. 12.693 -</para> 12.694 - 12.695 -<sect2> 12.696 -<title>Using the <command role="hg-cmd">hg bisect</command> command</title> 12.697 - 12.698 -<para>Here's an example of <command role="hg-cmd">hg bisect</command> in action. 12.699 -</para> 12.700 - 12.701 -<note> 12.702 -<para> In versions 0.9.5 and earlier of Mercurial, <command role="hg-cmd">hg bisect</command> was not a 12.703 - core command: it was distributed with Mercurial as an extension. 12.704 - This section describes the built-in command, not the old extension. 12.705 -</para> 12.706 -</note> 12.707 - 12.708 -<para>Now let's create a repository, so that we can try out the 12.709 -<command role="hg-cmd">hg bisect</command> command in isolation. 12.710 -<!-- &interaction.bisect.init; --> 12.711 -We'll simulate a project that has a bug in it in a simple-minded way: 12.712 -create trivial changes in a loop, and nominate one specific change 12.713 -that will have the <quote>bug</quote>. This loop creates 35 changesets, each 12.714 -adding a single file to the repository. We'll represent our <quote>bug</quote> 12.715 -with a file that contains the text <quote>i have a gub</quote>. 12.716 -<!-- &interaction.bisect.commits; --> 12.717 -</para> 12.718 - 12.719 -<para>The next thing that we'd like to do is figure out how to use the 12.720 -<command role="hg-cmd">hg bisect</command> command. We can use Mercurial's normal built-in help 12.721 -mechanism for this. 12.722 -<!-- &interaction.bisect.help; --> 12.723 -</para> 12.724 - 12.725 -<para>The <command role="hg-cmd">hg bisect</command> command works in steps. Each step proceeds as follows. 12.726 -</para> 12.727 -<orderedlist> 12.728 -<listitem><para>You run your binary test. 12.729 -</para> 12.730 -</listitem><itemizedlist> 12.731 -<listitem><para> \item If the test succeeded, you tell <command role="hg-cmd">hg bisect</command> by running the 12.732 - <command role="hg-cmd">hg bisect good</command> command. 12.733 - \item If it failed, run the <command role="hg-cmd">hg bisect --bad</command> command. 12.734 -</para> 12.735 -</listitem></itemizedlist> 12.736 -<listitem><para>The command uses your information to decide which changeset to 12.737 - test next. 12.738 -</para> 12.739 -</listitem> 12.740 -<listitem><para>It updates the working directory to that changeset, and the 12.741 - process begins again. 12.742 -</para> 12.743 -</listitem></orderedlist> 12.744 -<para>The process ends when <command role="hg-cmd">hg bisect</command> identifies a unique changeset 12.745 -that marks the point where your test transitioned from <quote>succeeding</quote> 12.746 -to <quote>failing</quote>. 12.747 -</para> 12.748 - 12.749 -<para>To start the search, we must run the <command role="hg-cmd">hg bisect --reset</command> command. 12.750 -<!-- &interaction.bisect.search.init; --> 12.751 -</para> 12.752 - 12.753 -<para>In our case, the binary test we use is simple: we check to see if any 12.754 -file in the repository contains the string <quote>i have a gub</quote>. If it 12.755 -does, this changeset contains the change that <quote>caused the bug</quote>. By 12.756 -convention, a changeset that has the property we're searching for is 12.757 -<quote>bad</quote>, while one that doesn't is <quote>good</quote>. 12.758 -</para> 12.759 - 12.760 -<para>Most of the time, the revision to which the working directory is 12.761 -synced (usually the tip) already exhibits the problem introduced by 12.762 -the buggy change, so we'll mark it as <quote>bad</quote>. 12.763 -<!-- &interaction.bisect.search.bad-init; --> 12.764 -</para> 12.765 - 12.766 -<para>Our next task is to nominate a changeset that we know <emphasis>doesn't</emphasis> 12.767 -have the bug; the <command role="hg-cmd">hg bisect</command> command will <quote>bracket</quote> its search 12.768 -between the first pair of good and bad changesets. In our case, we 12.769 -know that revision 10 didn't have the bug. (I'll have more words 12.770 -about choosing the first <quote>good</quote> changeset later.) 12.771 -<!-- &interaction.bisect.search.good-init; --> 12.772 -</para> 12.773 - 12.774 -<para>Notice that this command printed some output. 12.775 -</para> 12.776 -<itemizedlist> 12.777 -<listitem><para>It told us how many changesets it must consider before it can 12.778 - identify the one that introduced the bug, and how many tests that 12.779 - will require. 12.780 -</para> 12.781 -</listitem> 12.782 -<listitem><para>It updated the working directory to the next changeset to test, 12.783 - and told us which changeset it's testing. 12.784 -</para> 12.785 -</listitem></itemizedlist> 12.786 - 12.787 -<para>We now run our test in the working directory. We use the 12.788 -<command>grep</command> command to see if our <quote>bad</quote> file is present in the 12.789 -working directory. If it is, this revision is bad; if not, this 12.790 -revision is good. 12.791 -<!-- &interaction.bisect.search.step1; --> 12.792 -</para> 12.793 - 12.794 -<para>This test looks like a perfect candidate for automation, so let's turn 12.795 -it into a shell function. 12.796 -<!-- &interaction.bisect.search.mytest; --> 12.797 -We can now run an entire test step with a single command, 12.798 -<literal>mytest</literal>. 12.799 -<!-- &interaction.bisect.search.step2; --> 12.800 -A few more invocations of our canned test step command, and we're 12.801 -done. 12.802 -<!-- &interaction.bisect.search.rest; --> 12.803 -</para> 12.804 - 12.805 -<para>Even though we had 40 changesets to search through, the <command role="hg-cmd">hg bisect</command> 12.806 -command let us find the changeset that introduced our <quote>bug</quote> with 12.807 -only five tests. Because the number of tests that the <command role="hg-cmd">hg bisect</command> 12.808 -command performs grows logarithmically with the number of changesets to 12.809 -search, the advantage that it has over the <quote>brute force</quote> search 12.810 -approach increases with every changeset you add. 12.811 -</para> 12.812 - 12.813 -</sect2> 12.814 -<sect2> 12.815 -<title>Cleaning up after your search</title> 12.816 - 12.817 -<para>When you're finished using the <command role="hg-cmd">hg bisect</command> command in a 12.818 -repository, you can use the <command role="hg-cmd">hg bisect reset</command> command to drop 12.819 -the information it was using to drive your search. The command 12.820 -doesn't use much space, so it doesn't matter if you forget to run this 12.821 -command. However, <command role="hg-cmd">hg bisect</command> won't let you start a new search in 12.822 -that repository until you do a <command role="hg-cmd">hg bisect reset</command>. 12.823 -<!-- &interaction.bisect.search.reset; --> 12.824 -</para> 12.825 - 12.826 -</sect2> 12.827 -</sect1> 12.828 -<sect1> 12.829 -<title>Tips for finding bugs effectively</title> 12.830 - 12.831 -<sect2> 12.832 -<title>Give consistent input</title> 12.833 - 12.834 -<para>The <command role="hg-cmd">hg bisect</command> command requires that you correctly report the 12.835 -result of every test you perform. If you tell it that a test failed 12.836 -when it really succeeded, it <emphasis>might</emphasis> be able to detect the 12.837 -inconsistency. If it can identify an inconsistency in your reports, 12.838 -it will tell you that a particular changeset is both good and bad. 12.839 -However, it can't do this perfectly; it's about as likely to report 12.840 -the wrong changeset as the source of the bug. 12.841 -</para> 12.842 - 12.843 -</sect2> 12.844 -<sect2> 12.845 -<title>Automate as much as possible</title> 12.846 - 12.847 -<para>When I started using the <command role="hg-cmd">hg bisect</command> command, I tried a few times 12.848 -to run my tests by hand, on the command line. This is an approach 12.849 -that I, at least, am not suited to. After a few tries, I found that I 12.850 -was making enough mistakes that I was having to restart my searches 12.851 -several times before finally getting correct results. 12.852 -</para> 12.853 - 12.854 -<para>My initial problems with driving the <command role="hg-cmd">hg bisect</command> command by hand 12.855 -occurred even with simple searches on small repositories; if the 12.856 -problem you're looking for is more subtle, or the number of tests that 12.857 -<command role="hg-cmd">hg bisect</command> must perform increases, the likelihood of operator 12.858 -error ruining the search is much higher. Once I started automating my 12.859 -tests, I had much better results. 12.860 -</para> 12.861 - 12.862 -<para>The key to automated testing is twofold: 12.863 -</para> 12.864 -<itemizedlist> 12.865 -<listitem><para>always test for the same symptom, and 12.866 -</para> 12.867 -</listitem> 12.868 -<listitem><para>always feed consistent input to the <command role="hg-cmd">hg bisect</command> command. 12.869 -</para> 12.870 -</listitem></itemizedlist> 12.871 -<para>In my tutorial example above, the <command>grep</command> command tests for the 12.872 -symptom, and the <literal>if</literal> statement takes the result of this check 12.873 -and ensures that we always feed the same input to the <command role="hg-cmd">hg bisect</command> 12.874 -command. The <literal>mytest</literal> function marries these together in a 12.875 -reproducible way, so that every test is uniform and consistent. 12.876 -</para> 12.877 - 12.878 -</sect2> 12.879 -<sect2> 12.880 -<title>Check your results</title> 12.881 - 12.882 -<para>Because the output of a <command role="hg-cmd">hg bisect</command> search is only as good as the 12.883 -input you give it, don't take the changeset it reports as the 12.884 -absolute truth. A simple way to cross-check its report is to manually 12.885 -run your test at each of the following changesets: 12.886 -</para> 12.887 -<itemizedlist> 12.888 -<listitem><para>The changeset that it reports as the first bad revision. Your 12.889 - test should still report this as bad. 12.890 -</para> 12.891 -</listitem> 12.892 -<listitem><para>The parent of that changeset (either parent, if it's a merge). 12.893 - Your test should report this changeset as good. 12.894 -</para> 12.895 -</listitem> 12.896 -<listitem><para>A child of that changeset. Your test should report this 12.897 - changeset as bad. 12.898 -</para> 12.899 -</listitem></itemizedlist> 12.900 - 12.901 -</sect2> 12.902 -<sect2> 12.903 -<title>Beware interference between bugs</title> 12.904 - 12.905 -<para>It's possible that your search for one bug could be disrupted by the 12.906 -presence of another. For example, let's say your software crashes at 12.907 -revision 100, and worked correctly at revision 50. Unknown to you, 12.908 -someone else introduced a different crashing bug at revision 60, and 12.909 -fixed it at revision 80. This could distort your results in one of 12.910 -several ways. 12.911 -</para> 12.912 - 12.913 -<para>It is possible that this other bug completely <quote>masks</quote> yours, which 12.914 -is to say that it occurs before your bug has a chance to manifest 12.915 -itself. If you can't avoid that other bug (for example, it prevents 12.916 -your project from building), and so can't tell whether your bug is 12.917 -present in a particular changeset, the <command role="hg-cmd">hg bisect</command> command cannot 12.918 -help you directly. Instead, you can mark a changeset as untested by 12.919 -running <command role="hg-cmd">hg bisect --skip</command>. 12.920 -</para> 12.921 - 12.922 -<para>A different problem could arise if your test for a bug's presence is 12.923 -not specific enough. If you check for <quote>my program crashes</quote>, then 12.924 -both your crashing bug and an unrelated crashing bug that masks it 12.925 -will look like the same thing, and mislead <command role="hg-cmd">hg bisect</command>. 12.926 -</para> 12.927 - 12.928 -<para>Another useful situation in which to use <command role="hg-cmd">hg bisect --skip</command> is 12.929 -if you can't test a revision because your project was in a broken and 12.930 -hence untestable state at that revision, perhaps because someone 12.931 -checked in a change that prevented the project from building. 12.932 -</para> 12.933 - 12.934 -</sect2> 12.935 -<sect2> 12.936 -<title>Bracket your search lazily</title> 12.937 - 12.938 -<para>Choosing the first <quote>good</quote> and <quote>bad</quote> changesets that will mark the 12.939 -end points of your search is often easy, but it bears a little 12.940 -discussion nevertheless. From the perspective of <command role="hg-cmd">hg bisect</command>, the 12.941 -<quote>newest</quote> changeset is conventionally <quote>bad</quote>, and the older 12.942 -changeset is <quote>good</quote>. 12.943 -</para> 12.944 - 12.945 -<para>If you're having trouble remembering when a suitable <quote>good</quote> change 12.946 -was, so that you can tell <command role="hg-cmd">hg bisect</command>, you could do worse than 12.947 -testing changesets at random. Just remember to eliminate contenders 12.948 -that can't possibly exhibit the bug (perhaps because the feature with 12.949 -the bug isn't present yet) and those where another problem masks the 12.950 -bug (as I discussed above). 12.951 -</para> 12.952 - 12.953 -<para>Even if you end up <quote>early</quote> by thousands of changesets or months of 12.954 -history, you will only add a handful of tests to the total number that 12.955 -<command role="hg-cmd">hg bisect</command> must perform, thanks to its logarithmic behaviour. 12.956 -</para> 12.957 - 12.958 -</sect2> 12.959 -</sect1> 12.960 +<chapter id="chap:undo"> 12.961 + <?dbhtml filename="finding-and-fixing-mistakes.html"?> 12.962 + <title>Finding and fixing mistakes</title> 12.963 + 12.964 + <para id="x_d2">To err might be human, but to really handle the consequences 12.965 + well takes a top-notch revision control system. In this chapter, 12.966 + we'll discuss some of the techniques you can use when you find 12.967 + that a problem has crept into your project. Mercurial has some 12.968 + highly capable features that will help you to isolate the sources 12.969 + of problems, and to handle them appropriately.</para> 12.970 + 12.971 + <sect1> 12.972 + <title>Erasing local history</title> 12.973 + 12.974 + <sect2> 12.975 + <title>The accidental commit</title> 12.976 + 12.977 + <para id="x_d3">I have the occasional but persistent problem of typing 12.978 + rather more quickly than I can think, which sometimes results 12.979 + in me committing a changeset that is either incomplete or 12.980 + plain wrong. In my case, the usual kind of incomplete 12.981 + changeset is one in which I've created a new source file, but 12.982 + forgotten to <command role="hg-cmd">hg add</command> it. A 12.983 + <quote>plain wrong</quote> changeset is not as common, but no 12.984 + less annoying.</para> 12.985 + 12.986 + </sect2> 12.987 + <sect2 id="sec:undo:rollback"> 12.988 + <title>Rolling back a transaction</title> 12.989 + 12.990 + <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I 12.991 + mentioned that Mercurial treats each modification of a 12.992 + repository as a <emphasis>transaction</emphasis>. Every time 12.993 + you commit a changeset or pull changes from another 12.994 + repository, Mercurial remembers what you did. You can undo, 12.995 + or <emphasis>roll back</emphasis>, exactly one of these 12.996 + actions using the <command role="hg-cmd">hg rollback</command> 12.997 + command. (See <xref linkend="sec:undo:rollback-after-push"/> 12.998 + for an important caveat about the use of this command.)</para> 12.999 + 12.1000 + <para id="x_d5">Here's a mistake that I often find myself making: 12.1001 + committing a change in which I've created a new file, but 12.1002 + forgotten to <command role="hg-cmd">hg add</command> 12.1003 + it.</para> 12.1004 + 12.1005 + &interaction.rollback.commit; 12.1006 + 12.1007 + <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 12.1008 + status</command> after the commit immediately confirms the 12.1009 + error.</para> 12.1010 + 12.1011 + &interaction.rollback.status; 12.1012 + 12.1013 + <para id="x_d7">The commit captured the changes to the file 12.1014 + <filename>a</filename>, but not the new file 12.1015 + <filename>b</filename>. If I were to push this changeset to a 12.1016 + repository that I shared with a colleague, the chances are 12.1017 + high that something in <filename>a</filename> would refer to 12.1018 + <filename>b</filename>, which would not be present in their 12.1019 + repository when they pulled my changes. I would thus become 12.1020 + the object of some indignation.</para> 12.1021 + 12.1022 + <para id="x_d8">However, luck is with me&emdash;I've caught my error 12.1023 + before I pushed the changeset. I use the <command 12.1024 + role="hg-cmd">hg rollback</command> command, and Mercurial 12.1025 + makes that last changeset vanish.</para> 12.1026 + 12.1027 + &interaction.rollback.rollback; 12.1028 + 12.1029 + <para id="x_d9">Notice that the changeset is no longer present in the 12.1030 + repository's history, and the working directory once again 12.1031 + thinks that the file <filename>a</filename> is modified. The 12.1032 + commit and rollback have left the working directory exactly as 12.1033 + it was prior to the commit; the changeset has been completely 12.1034 + erased. I can now safely <command role="hg-cmd">hg 12.1035 + add</command> the file <filename>b</filename>, and rerun my 12.1036 + commit.</para> 12.1037 + 12.1038 + &interaction.rollback.add; 12.1039 + 12.1040 + </sect2> 12.1041 + <sect2> 12.1042 + <title>The erroneous pull</title> 12.1043 + 12.1044 + <para id="x_da">It's common practice with Mercurial to maintain separate 12.1045 + development branches of a project in different repositories. 12.1046 + Your development team might have one shared repository for 12.1047 + your project's <quote>0.9</quote> release, and another, 12.1048 + containing different changes, for the <quote>1.0</quote> 12.1049 + release.</para> 12.1050 + 12.1051 + <para id="x_db">Given this, you can imagine that the consequences could be 12.1052 + messy if you had a local <quote>0.9</quote> repository, and 12.1053 + accidentally pulled changes from the shared <quote>1.0</quote> 12.1054 + repository into it. At worst, you could be paying 12.1055 + insufficient attention, and push those changes into the shared 12.1056 + <quote>0.9</quote> tree, confusing your entire team (but don't 12.1057 + worry, we'll return to this horror scenario later). However, 12.1058 + it's more likely that you'll notice immediately, because 12.1059 + Mercurial will display the URL it's pulling from, or you will 12.1060 + see it pull a suspiciously large number of changes into the 12.1061 + repository.</para> 12.1062 + 12.1063 + <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 12.1064 + will work nicely to expunge all of the changesets that you 12.1065 + just pulled. Mercurial groups all changes from one <command 12.1066 + role="hg-cmd">hg pull</command> into a single transaction, 12.1067 + so one <command role="hg-cmd">hg rollback</command> is all you 12.1068 + need to undo this mistake.</para> 12.1069 + 12.1070 + </sect2> 12.1071 + <sect2 id="sec:undo:rollback-after-push"> 12.1072 + <title>Rolling back is useless once you've pushed</title> 12.1073 + 12.1074 + <para id="x_dd">The value of the <command role="hg-cmd">hg 12.1075 + rollback</command> command drops to zero once you've pushed 12.1076 + your changes to another repository. Rolling back a change 12.1077 + makes it disappear entirely, but <emphasis>only</emphasis> in 12.1078 + the repository in which you perform the <command 12.1079 + role="hg-cmd">hg rollback</command>. Because a rollback 12.1080 + eliminates history, there's no way for the disappearance of a 12.1081 + change to propagate between repositories.</para> 12.1082 + 12.1083 + <para id="x_de">If you've pushed a change to another 12.1084 + repository&emdash;particularly if it's a shared 12.1085 + repository&emdash;it has essentially <quote>escaped into the 12.1086 + wild,</quote> and you'll have to recover from your mistake 12.1087 + in a different way. If you push a changeset somewhere, then 12.1088 + roll it back, then pull from the repository you pushed to, the 12.1089 + changeset you thought you'd gotten rid of will simply reappear 12.1090 + in your repository.</para> 12.1091 + 12.1092 + <para id="x_df">(If you absolutely know for sure that the change 12.1093 + you want to roll back is the most recent change in the 12.1094 + repository that you pushed to, <emphasis>and</emphasis> you 12.1095 + know that nobody else could have pulled it from that 12.1096 + repository, you can roll back the changeset there, too, but 12.1097 + you really should not expect this to work reliably. Sooner or 12.1098 + later a change really will make it into a repository that you 12.1099 + don't directly control (or have forgotten about), and come 12.1100 + back to bite you.)</para> 12.1101 + 12.1102 + </sect2> 12.1103 + <sect2> 12.1104 + <title>You can only roll back once</title> 12.1105 + 12.1106 + <para id="x_e0">Mercurial stores exactly one transaction in its 12.1107 + transaction log; that transaction is the most recent one that 12.1108 + occurred in the repository. This means that you can only roll 12.1109 + back one transaction. If you expect to be able to roll back 12.1110 + one transaction, then its predecessor, this is not the 12.1111 + behavior you will get.</para> 12.1112 + 12.1113 + &interaction.rollback.twice; 12.1114 + 12.1115 + <para id="x_e1">Once you've rolled back one transaction in a repository, 12.1116 + you can't roll back again in that repository until you perform 12.1117 + another commit or pull.</para> 12.1118 + 12.1119 + </sect2> 12.1120 + </sect1> 12.1121 + <sect1> 12.1122 + <title>Reverting the mistaken change</title> 12.1123 + 12.1124 + <para id="x_e2">If you make a modification to a file, and decide that you 12.1125 + really didn't want to change the file at all, and you haven't 12.1126 + yet committed your changes, the <command role="hg-cmd">hg 12.1127 + revert</command> command is the one you'll need. It looks at 12.1128 + the changeset that's the parent of the working directory, and 12.1129 + restores the contents of the file to their state as of that 12.1130 + changeset. (That's a long-winded way of saying that, in the 12.1131 + normal case, it undoes your modifications.)</para> 12.1132 + 12.1133 + <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 12.1134 + revert</command> command works with yet another small example. 12.1135 + We'll begin by modifying a file that Mercurial is already 12.1136 + tracking.</para> 12.1137 + 12.1138 + &interaction.daily.revert.modify; 12.1139 + 12.1140 + <para id="x_e4">If we don't 12.1141 + want that change, we can simply <command role="hg-cmd">hg 12.1142 + revert</command> the file.</para> 12.1143 + 12.1144 + &interaction.daily.revert.unmodify; 12.1145 + 12.1146 + <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 12.1147 + provides us with an extra degree of safety by saving our 12.1148 + modified file with a <filename>.orig</filename> 12.1149 + extension.</para> 12.1150 + 12.1151 + &interaction.daily.revert.status; 12.1152 + 12.1153 + <tip> 12.1154 + <title>Be careful with <filename>.orig</filename> files</title> 12.1155 + 12.1156 + <para id="x_6b8">It's extremely unlikely that you are either using 12.1157 + Mercurial to manage files with <filename>.orig</filename> 12.1158 + extensions or that you even care about the contents of such 12.1159 + files. Just in case, though, it's useful to remember that 12.1160 + <command role="hg-cmd">hg revert</command> will 12.1161 + unconditionally overwrite an existing file with a 12.1162 + <filename>.orig</filename> extension. For instance, if you 12.1163 + already have a file named <filename>foo.orig</filename> when 12.1164 + you revert <filename>foo</filename>, the contents of 12.1165 + <filename>foo.orig</filename> will be clobbered.</para> 12.1166 + </tip> 12.1167 + 12.1168 + <para id="x_e6">Here is a summary of the cases that the <command 12.1169 + role="hg-cmd">hg revert</command> command can deal with. We 12.1170 + will describe each of these in more detail in the section that 12.1171 + follows.</para> 12.1172 + <itemizedlist> 12.1173 + <listitem><para id="x_e7">If you modify a file, it will restore the file 12.1174 + to its unmodified state.</para> 12.1175 + </listitem> 12.1176 + <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 12.1177 + file, it will undo the <quote>added</quote> state of the 12.1178 + file, but leave the file itself untouched.</para> 12.1179 + </listitem> 12.1180 + <listitem><para id="x_e9">If you delete a file without telling Mercurial, 12.1181 + it will restore the file to its unmodified contents.</para> 12.1182 + </listitem> 12.1183 + <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 12.1184 + remove</command> command to remove a file, it will undo 12.1185 + the <quote>removed</quote> state of the file, and restore 12.1186 + the file to its unmodified contents.</para> 12.1187 + </listitem></itemizedlist> 12.1188 + 12.1189 + <sect2 id="sec:undo:mgmt"> 12.1190 + <title>File management errors</title> 12.1191 + 12.1192 + <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 12.1193 + useful for more than just modified files. It lets you reverse 12.1194 + the results of all of Mercurial's file management 12.1195 + commands&emdash;<command role="hg-cmd">hg add</command>, 12.1196 + <command role="hg-cmd">hg remove</command>, and so on.</para> 12.1197 + 12.1198 + <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 12.1199 + then decide that in fact you don't want Mercurial to track it, 12.1200 + use <command role="hg-cmd">hg revert</command> to undo the 12.1201 + add. Don't worry; Mercurial will not modify the file in any 12.1202 + way. It will just <quote>unmark</quote> the file.</para> 12.1203 + 12.1204 + &interaction.daily.revert.add; 12.1205 + 12.1206 + <para id="x_ed">Similarly, if you ask Mercurial to <command 12.1207 + role="hg-cmd">hg remove</command> a file, you can use 12.1208 + <command role="hg-cmd">hg revert</command> to restore it to 12.1209 + the contents it had as of the parent of the working directory. 12.1210 + &interaction.daily.revert.remove; This works just as 12.1211 + well for a file that you deleted by hand, without telling 12.1212 + Mercurial (recall that in Mercurial terminology, this kind of 12.1213 + file is called <quote>missing</quote>).</para> 12.1214 + 12.1215 + &interaction.daily.revert.missing; 12.1216 + 12.1217 + <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 12.1218 + the copied-to file remains in your working directory 12.1219 + afterwards, untracked. Since a copy doesn't affect the 12.1220 + copied-from file in any way, Mercurial doesn't do anything 12.1221 + with the copied-from file.</para> 12.1222 + 12.1223 + &interaction.daily.revert.copy; 12.1224 + </sect2> 12.1225 + </sect1> 12.1226 + 12.1227 + <sect1> 12.1228 + <title>Dealing with committed changes</title> 12.1229 + 12.1230 + <para id="x_f5">Consider a case where you have committed a change 12.1231 + <emphasis>a</emphasis>, and another change 12.1232 + <emphasis>b</emphasis> on top of it; you then realise that 12.1233 + change <emphasis>a</emphasis> was incorrect. Mercurial lets you 12.1234 + <quote>back out</quote> an entire changeset automatically, and 12.1235 + building blocks that let you reverse part of a changeset by 12.1236 + hand.</para> 12.1237 + 12.1238 + <para id="x_f6">Before you read this section, here's something to 12.1239 + keep in mind: the <command role="hg-cmd">hg backout</command> 12.1240 + command undoes the effect of a change by 12.1241 + <emphasis>adding</emphasis> to your repository's history, not by 12.1242 + modifying or erasing it. It's the right tool to use if you're 12.1243 + fixing bugs, but not if you're trying to undo some change that 12.1244 + has catastrophic consequences. To deal with those, see 12.1245 + <xref linkend="sec:undo:aaaiiieee"/>.</para> 12.1246 + 12.1247 + <sect2> 12.1248 + <title>Backing out a changeset</title> 12.1249 + 12.1250 + <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 12.1251 + lets you <quote>undo</quote> the effects of an entire 12.1252 + changeset in an automated fashion. Because Mercurial's 12.1253 + history is immutable, this command <emphasis>does 12.1254 + not</emphasis> get rid of the changeset you want to undo. 12.1255 + Instead, it creates a new changeset that 12.1256 + <emphasis>reverses</emphasis> the effect of the to-be-undone 12.1257 + changeset.</para> 12.1258 + 12.1259 + <para id="x_f8">The operation of the <command role="hg-cmd">hg 12.1260 + backout</command> command is a little intricate, so let's 12.1261 + illustrate it with some examples. First, we'll create a 12.1262 + repository with some simple changes.</para> 12.1263 + 12.1264 + &interaction.backout.init; 12.1265 + 12.1266 + <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 12.1267 + takes a single changeset ID as its argument; this is the 12.1268 + changeset to back out. Normally, <command role="hg-cmd">hg 12.1269 + backout</command> will drop you into a text editor to write 12.1270 + a commit message, so you can record why you're backing the 12.1271 + change out. In this example, we provide a commit message on 12.1272 + the command line using the <option 12.1273 + role="hg-opt-backout">-m</option> option.</para> 12.1274 + 12.1275 + </sect2> 12.1276 + <sect2> 12.1277 + <title>Backing out the tip changeset</title> 12.1278 + 12.1279 + <para id="x_fa">We're going to start by backing out the last changeset we 12.1280 + committed.</para> 12.1281 + 12.1282 + &interaction.backout.simple; 12.1283 + 12.1284 + <para id="x_fb">You can see that the second line from 12.1285 + <filename>myfile</filename> is no longer present. Taking a 12.1286 + look at the output of <command role="hg-cmd">hg log</command> 12.1287 + gives us an idea of what the <command role="hg-cmd">hg 12.1288 + backout</command> command has done. 12.1289 + &interaction.backout.simple.log; Notice that the new changeset 12.1290 + that <command role="hg-cmd">hg backout</command> has created 12.1291 + is a child of the changeset we backed out. It's easier to see 12.1292 + this in <xref linkend="fig:undo:backout"/>, which presents a 12.1293 + graphical view of the change history. As you can see, the 12.1294 + history is nice and linear.</para> 12.1295 + 12.1296 + <figure id="fig:undo:backout"> 12.1297 + <title>Backing out a change using the <command 12.1298 + role="hg-cmd">hg backout</command> command</title> 12.1299 + <mediaobject> 12.1300 + <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject> 12.1301 + <textobject><phrase>XXX add text</phrase></textobject> 12.1302 + </mediaobject> 12.1303 + </figure> 12.1304 + 12.1305 + </sect2> 12.1306 + <sect2> 12.1307 + <title>Backing out a non-tip change</title> 12.1308 + 12.1309 + <para id="x_fd">If you want to back out a change other than the last one 12.1310 + you committed, pass the <option 12.1311 + role="hg-opt-backout">--merge</option> option to the 12.1312 + <command role="hg-cmd">hg backout</command> command.</para> 12.1313 + 12.1314 + &interaction.backout.non-tip.clone; 12.1315 + 12.1316 + <para id="x_fe">This makes backing out any changeset a 12.1317 + <quote>one-shot</quote> operation that's usually simple and 12.1318 + fast.</para> 12.1319 + 12.1320 + &interaction.backout.non-tip.backout; 12.1321 + 12.1322 + <para id="x_ff">If you take a look at the contents of 12.1323 + <filename>myfile</filename> after the backout finishes, you'll 12.1324 + see that the first and third changes are present, but not the 12.1325 + second.</para> 12.1326 + 12.1327 + &interaction.backout.non-tip.cat; 12.1328 + 12.1329 + <para id="x_100">As the graphical history in <xref 12.1330 + linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 12.1331 + still commits one change in this kind of situation (the 12.1332 + box-shaped node is the ones that Mercurial commits 12.1333 + automatically), but the revision graph now looks different. 12.1334 + Before Mercurial begins the backout process, it first 12.1335 + remembers what the current parent of the working directory is. 12.1336 + It then backs out the target changeset, and commits that as a 12.1337 + changeset. Finally, it merges back to the previous parent of 12.1338 + the working directory, but notice that it <emphasis>does not 12.1339 + commit</emphasis> the result of the merge. The repository 12.1340 + now contains two heads, and the working directory is in a 12.1341 + merge state.</para> 12.1342 + 12.1343 + <figure id="fig:undo:backout-non-tip"> 12.1344 + <title>Automated backout of a non-tip change using the 12.1345 + <command role="hg-cmd">hg backout</command> command</title> 12.1346 + <mediaobject> 12.1347 + <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject> 12.1348 + <textobject><phrase>XXX add text</phrase></textobject> 12.1349 + </mediaobject> 12.1350 + </figure> 12.1351 + 12.1352 + <para id="x_103">The result is that you end up <quote>back where you 12.1353 + were</quote>, only with some extra history that undoes the 12.1354 + effect of the changeset you wanted to back out.</para> 12.1355 + 12.1356 + <para id="x_6b9">You might wonder why Mercurial does not commit the result 12.1357 + of the merge that it performed. The reason lies in Mercurial 12.1358 + behaving conservatively: a merge naturally has more scope for 12.1359 + error than simply undoing the effect of the tip changeset, 12.1360 + so your work will be safest if you first inspect (and test!) 12.1361 + the result of the merge, <emphasis>then</emphasis> commit 12.1362 + it.</para> 12.1363 + 12.1364 + <sect3> 12.1365 + <title>Always use the <option 12.1366 + role="hg-opt-backout">--merge</option> option</title> 12.1367 + 12.1368 + <para id="x_104">In fact, since the <option 12.1369 + role="hg-opt-backout">--merge</option> option will do the 12.1370 + <quote>right thing</quote> whether or not the changeset 12.1371 + you're backing out is the tip (i.e. it won't try to merge if 12.1372 + it's backing out the tip, since there's no need), you should 12.1373 + <emphasis>always</emphasis> use this option when you run the 12.1374 + <command role="hg-cmd">hg backout</command> command.</para> 12.1375 + 12.1376 + </sect3> 12.1377 + </sect2> 12.1378 + <sect2> 12.1379 + <title>Gaining more control of the backout process</title> 12.1380 + 12.1381 + <para id="x_105">While I've recommended that you always use the <option 12.1382 + role="hg-opt-backout">--merge</option> option when backing 12.1383 + out a change, the <command role="hg-cmd">hg backout</command> 12.1384 + command lets you decide how to merge a backout changeset. 12.1385 + Taking control of the backout process by hand is something you 12.1386 + will rarely need to do, but it can be useful to understand 12.1387 + what the <command role="hg-cmd">hg backout</command> command 12.1388 + is doing for you automatically. To illustrate this, let's 12.1389 + clone our first repository, but omit the backout change that 12.1390 + it contains.</para> 12.1391 + 12.1392 + &interaction.backout.manual.clone; 12.1393 + 12.1394 + <para id="x_106">As with our 12.1395 + earlier example, We'll commit a third changeset, then back out 12.1396 + its parent, and see what happens.</para> 12.1397 + 12.1398 + &interaction.backout.manual.backout; 12.1399 + 12.1400 + <para id="x_107">Our new changeset is again a descendant of the changeset 12.1401 + we backout out; it's thus a new head, <emphasis>not</emphasis> 12.1402 + a descendant of the changeset that was the tip. The <command 12.1403 + role="hg-cmd">hg backout</command> command was quite 12.1404 + explicit in telling us this.</para> 12.1405 + 12.1406 + &interaction.backout.manual.log; 12.1407 + 12.1408 + <para id="x_108">Again, it's easier to see what has happened by looking at 12.1409 + a graph of the revision history, in <xref 12.1410 + linkend="fig:undo:backout-manual"/>. This makes it clear 12.1411 + that when we use <command role="hg-cmd">hg backout</command> 12.1412 + to back out a change other than the tip, Mercurial adds a new 12.1413 + head to the repository (the change it committed is 12.1414 + box-shaped).</para> 12.1415 + 12.1416 + <figure id="fig:undo:backout-manual"> 12.1417 + <title>Backing out a change using the <command 12.1418 + role="hg-cmd">hg backout</command> command</title> 12.1419 + <mediaobject> 12.1420 + <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject> 12.1421 + <textobject><phrase>XXX add text</phrase></textobject> 12.1422 + </mediaobject> 12.1423 + </figure> 12.1424 + 12.1425 + <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 12.1426 + command has completed, it leaves the new 12.1427 + <quote>backout</quote> changeset as the parent of the working 12.1428 + directory.</para> 12.1429 + 12.1430 + &interaction.backout.manual.parents; 12.1431 + 12.1432 + <para id="x_10b">Now we have two isolated sets of changes.</para> 12.1433 + 12.1434 + &interaction.backout.manual.heads; 12.1435 + 12.1436 + <para id="x_10c">Let's think about what we expect to see as the contents of 12.1437 + <filename>myfile</filename> now. The first change should be 12.1438 + present, because we've never backed it out. The second change 12.1439 + should be missing, as that's the change we backed out. Since 12.1440 + the history graph shows the third change as a separate head, 12.1441 + we <emphasis>don't</emphasis> expect to see the third change 12.1442 + present in <filename>myfile</filename>.</para> 12.1443 + 12.1444 + &interaction.backout.manual.cat; 12.1445 + 12.1446 + <para id="x_10d">To get the third change back into the file, we just do a 12.1447 + normal merge of our two heads.</para> 12.1448 + 12.1449 + &interaction.backout.manual.merge; 12.1450 + 12.1451 + <para id="x_10e">Afterwards, the graphical history of our 12.1452 + repository looks like 12.1453 + <xref linkend="fig:undo:backout-manual-merge"/>.</para> 12.1454 + 12.1455 + <figure id="fig:undo:backout-manual-merge"> 12.1456 + <title>Manually merging a backout change</title> 12.1457 + <mediaobject> 12.1458 + <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject> 12.1459 + <textobject><phrase>XXX add text</phrase></textobject> 12.1460 + </mediaobject> 12.1461 + </figure> 12.1462 + 12.1463 + </sect2> 12.1464 + <sect2> 12.1465 + <title>Why <command role="hg-cmd">hg backout</command> works as 12.1466 + it does</title> 12.1467 + 12.1468 + <para id="x_110">Here's a brief description of how the <command 12.1469 + role="hg-cmd">hg backout</command> command works.</para> 12.1470 + <orderedlist> 12.1471 + <listitem><para id="x_111">It ensures that the working directory is 12.1472 + <quote>clean</quote>, i.e. that the output of <command 12.1473 + role="hg-cmd">hg status</command> would be empty.</para> 12.1474 + </listitem> 12.1475 + <listitem><para id="x_112">It remembers the current parent of the working 12.1476 + directory. Let's call this changeset 12.1477 + <literal>orig</literal>.</para> 12.1478 + </listitem> 12.1479 + <listitem><para id="x_113">It does the equivalent of a <command 12.1480 + role="hg-cmd">hg update</command> to sync the working 12.1481 + directory to the changeset you want to back out. Let's 12.1482 + call this changeset <literal>backout</literal>.</para> 12.1483 + </listitem> 12.1484 + <listitem><para id="x_114">It finds the parent of that changeset. Let's 12.1485 + call that changeset <literal>parent</literal>.</para> 12.1486 + </listitem> 12.1487 + <listitem><para id="x_115">For each file that the 12.1488 + <literal>backout</literal> changeset affected, it does the 12.1489 + equivalent of a <command role="hg-cmd">hg revert -r 12.1490 + parent</command> on that file, to restore it to the 12.1491 + contents it had before that changeset was 12.1492 + committed.</para> 12.1493 + </listitem> 12.1494 + <listitem><para id="x_116">It commits the result as a new changeset. 12.1495 + This changeset has <literal>backout</literal> as its 12.1496 + parent.</para> 12.1497 + </listitem> 12.1498 + <listitem><para id="x_117">If you specify <option 12.1499 + role="hg-opt-backout">--merge</option> on the command 12.1500 + line, it merges with <literal>orig</literal>, and commits 12.1501 + the result of the merge.</para> 12.1502 + </listitem></orderedlist> 12.1503 + 12.1504 + <para id="x_118">An alternative way to implement the <command 12.1505 + role="hg-cmd">hg backout</command> command would be to 12.1506 + <command role="hg-cmd">hg export</command> the 12.1507 + to-be-backed-out changeset as a diff, then use the <option 12.1508 + role="cmd-opt-patch">--reverse</option> option to the 12.1509 + <command>patch</command> command to reverse the effect of the 12.1510 + change without fiddling with the working directory. This 12.1511 + sounds much simpler, but it would not work nearly as 12.1512 + well.</para> 12.1513 + 12.1514 + <para id="x_119">The reason that <command role="hg-cmd">hg 12.1515 + backout</command> does an update, a commit, a merge, and 12.1516 + another commit is to give the merge machinery the best chance 12.1517 + to do a good job when dealing with all the changes 12.1518 + <emphasis>between</emphasis> the change you're backing out and 12.1519 + the current tip.</para> 12.1520 + 12.1521 + <para id="x_11a">If you're backing out a changeset that's 100 revisions 12.1522 + back in your project's history, the chances that the 12.1523 + <command>patch</command> command will be able to apply a 12.1524 + reverse diff cleanly are not good, because intervening changes 12.1525 + are likely to have <quote>broken the context</quote> that 12.1526 + <command>patch</command> uses to determine whether it can 12.1527 + apply a patch (if this sounds like gibberish, see <xref 12.1528 + linkend="sec:mq:patch"/> for a 12.1529 + discussion of the <command>patch</command> command). Also, 12.1530 + Mercurial's merge machinery will handle files and directories 12.1531 + being renamed, permission changes, and modifications to binary 12.1532 + files, none of which <command>patch</command> can deal 12.1533 + with.</para> 12.1534 + 12.1535 + </sect2> 12.1536 + </sect1> 12.1537 + <sect1 id="sec:undo:aaaiiieee"> 12.1538 + <title>Changes that should never have been</title> 12.1539 + 12.1540 + <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 12.1541 + backout</command> command is exactly what you need if you want 12.1542 + to undo the effects of a change. It leaves a permanent record 12.1543 + of exactly what you did, both when committing the original 12.1544 + changeset and when you cleaned up after it.</para> 12.1545 + 12.1546 + <para id="x_11c">On rare occasions, though, you may find that you've 12.1547 + committed a change that really should not be present in the 12.1548 + repository at all. For example, it would be very unusual, and 12.1549 + usually considered a mistake, to commit a software project's 12.1550 + object files as well as its source files. Object files have 12.1551 + almost no intrinsic value, and they're <emphasis>big</emphasis>, 12.1552 + so they increase the size of the repository and the amount of 12.1553 + time it takes to clone or pull changes.</para> 12.1554 + 12.1555 + <para id="x_11d">Before I discuss the options that you have if you commit a 12.1556 + <quote>brown paper bag</quote> change (the kind that's so bad 12.1557 + that you want to pull a brown paper bag over your head), let me 12.1558 + first discuss some approaches that probably won't work.</para> 12.1559 + 12.1560 + <para id="x_11e">Since Mercurial treats history as 12.1561 + accumulative&emdash;every change builds on top of all changes 12.1562 + that preceded it&emdash;you generally can't just make disastrous 12.1563 + changes disappear. The one exception is when you've just 12.1564 + committed a change, and it hasn't been pushed or pulled into 12.1565 + another repository. That's when you can safely use the <command 12.1566 + role="hg-cmd">hg rollback</command> command, as I detailed in 12.1567 + <xref linkend="sec:undo:rollback"/>.</para> 12.1568 + 12.1569 + <para id="x_11f">After you've pushed a bad change to another repository, you 12.1570 + <emphasis>could</emphasis> still use <command role="hg-cmd">hg 12.1571 + rollback</command> to make your local copy of the change 12.1572 + disappear, but it won't have the consequences you want. The 12.1573 + change will still be present in the remote repository, so it 12.1574 + will reappear in your local repository the next time you 12.1575 + pull.</para> 12.1576 + 12.1577 + <para id="x_120">If a situation like this arises, and you know which 12.1578 + repositories your bad change has propagated into, you can 12.1579 + <emphasis>try</emphasis> to get rid of the change from 12.1580 + <emphasis>every</emphasis> one of those repositories. This is, 12.1581 + of course, not a satisfactory solution: if you miss even a 12.1582 + single repository while you're expunging, the change is still 12.1583 + <quote>in the wild</quote>, and could propagate further.</para> 12.1584 + 12.1585 + <para id="x_121">If you've committed one or more changes 12.1586 + <emphasis>after</emphasis> the change that you'd like to see 12.1587 + disappear, your options are further reduced. Mercurial doesn't 12.1588 + provide a way to <quote>punch a hole</quote> in history, leaving 12.1589 + changesets intact.</para> 12.1590 + 12.1591 + <sect2> 12.1592 + <title>Backing out a merge</title> 12.1593 + 12.1594 + <para id="x_6ba">Since merges are often complicated, it is not unheard of 12.1595 + for a merge to be mangled badly, but committed erroneously. 12.1596 + Mercurial provides an important safeguard against bad merges 12.1597 + by refusing to commit unresolved files, but human ingenuity 12.1598 + guarantees that it is still possible to mess a merge up and 12.1599 + commit it.</para> 12.1600 + 12.1601 + <para id="x_6bb">Given a bad merge that has been committed, usually the 12.1602 + best way to approach it is to simply try to repair the damage 12.1603 + by hand. A complete disaster that cannot be easily fixed up 12.1604 + by hand ought to be very rare, but the <command 12.1605 + role="hg-cmd">hg backout</command> command may help in 12.1606 + making the cleanup easier. It offers a <option 12.1607 + role="hg-opt-backout">--parent</option> option, which lets 12.1608 + you specify which parent to revert to when backing out a 12.1609 + merge.</para> 12.1610 + 12.1611 + <figure id="fig:undo:bad-merge-1"> 12.1612 + <title>A bad merge</title> 12.1613 + <mediaobject> 12.1614 + <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject> 12.1615 + <textobject><phrase>XXX add text</phrase></textobject> 12.1616 + </mediaobject> 12.1617 + </figure> 12.1618 + 12.1619 + <para id="x_6bc">Suppose we have a revision graph like that in <xref 12.1620 + linkend="fig:undo:bad-merge-1"/>. What we'd like is to 12.1621 + <emphasis>redo</emphasis> the merge of revisions 2 and 12.1622 + 3.</para> 12.1623 + 12.1624 + <para id="x_6bd">One way to do so would be as follows.</para> 12.1625 + 12.1626 + <orderedlist> 12.1627 + <listitem> 12.1628 + <para id="x_6be">Call <command role="hg-cmd">hg backout --rev=4 12.1629 + --parent=2</command>. This tells <command 12.1630 + role="hg-cmd">hg backout</command> to back out revision 12.1631 + 4, which is the bad merge, and to when deciding which 12.1632 + revision to prefer, to choose parent 2, one of the parents 12.1633 + of the merge. The effect can be seen in <xref 12.1634 + linkend="fig:undo:bad-merge-2"/>.</para> 12.1635 + <figure id="fig:undo:bad-merge-2"> 12.1636 + <title>Backing out the merge, favoring one parent</title> 12.1637 + <mediaobject> 12.1638 + <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject> 12.1639 + <textobject><phrase>XXX add text</phrase></textobject> 12.1640 + </mediaobject> 12.1641 + </figure> 12.1642 + </listitem> 12.1643 + 12.1644 + <listitem> 12.1645 + <para id="x_6bf">Call <command role="hg-cmd">hg backout --rev=4 12.1646 + --parent=3</command>. This tells <command 12.1647 + role="hg-cmd">hg backout</command> to back out revision 12.1648 + 4 again, but this time to choose parent 3, the other 12.1649 + parent of the merge. The result is visible in <xref 12.1650 + linkend="fig:undo:bad-merge-3"/>, in which the repository 12.1651 + now contains three heads.</para> 12.1652 + <figure id="fig:undo:bad-merge-3"> 12.1653 + <title>Backing out the merge, favoring the other 12.1654 + parent</title> 12.1655 + <mediaobject> 12.1656 + <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject> 12.1657 + <textobject><phrase>XXX add text</phrase></textobject> 12.1658 + </mediaobject> 12.1659 + </figure> 12.1660 + </listitem> 12.1661 + 12.1662 + <listitem> 12.1663 + <para id="x_6c0">Redo the bad merge by merging the two backout heads, 12.1664 + which reduces the number of heads in the repository to 12.1665 + two, as can be seen in <xref 12.1666 + linkend="fig:undo:bad-merge-4"/>.</para> 12.1667 + <figure id="fig:undo:bad-merge-4"> 12.1668 + <title>Merging the backouts</title> 12.1669 + <mediaobject> 12.1670 + <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject> 12.1671 + <textobject><phrase>XXX add text</phrase></textobject> 12.1672 + </mediaobject> 12.1673 + </figure> 12.1674 + </listitem> 12.1675 + 12.1676 + <listitem> 12.1677 + <para id="x_6c1">Merge with the commit that was made after the bad 12.1678 + merge, as shown in <xref 12.1679 + linkend="fig:undo:bad-merge-5"/>.</para> 12.1680 + <figure id="fig:undo:bad-merge-5"> 12.1681 + <title>Merging the backouts</title> 12.1682 + <mediaobject> 12.1683 + <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject> 12.1684 + <textobject><phrase>XXX add text</phrase></textobject> 12.1685 + </mediaobject> 12.1686 + </figure> 12.1687 + </listitem> 12.1688 + </orderedlist> 12.1689 + </sect2> 12.1690 + 12.1691 + <sect2> 12.1692 + <title>Protect yourself from <quote>escaped</quote> 12.1693 + changes</title> 12.1694 + 12.1695 + <para id="x_123">If you've committed some changes to your local repository 12.1696 + and they've been pushed or pulled somewhere else, this isn't 12.1697 + necessarily a disaster. You can protect yourself ahead of 12.1698 + time against some classes of bad changeset. This is 12.1699 + particularly easy if your team usually pulls changes from a 12.1700 + central repository.</para> 12.1701 + 12.1702 + <para id="x_124">By configuring some hooks on that repository to validate 12.1703 + incoming changesets (see chapter <xref linkend="chap:hook"/>), 12.1704 + you can 12.1705 + automatically prevent some kinds of bad changeset from being 12.1706 + pushed to the central repository at all. With such a 12.1707 + configuration in place, some kinds of bad changeset will 12.1708 + naturally tend to <quote>die out</quote> because they can't 12.1709 + propagate into the central repository. Better yet, this 12.1710 + happens without any need for explicit intervention.</para> 12.1711 + 12.1712 + <para id="x_125">For instance, an incoming change hook that 12.1713 + verifies that a changeset will actually compile can prevent 12.1714 + people from inadvertently <quote>breaking the 12.1715 + build</quote>.</para> 12.1716 + </sect2> 12.1717 + 12.1718 + <sect2> 12.1719 + <title>What to do about sensitive changes that escape</title> 12.1720 + 12.1721 + <para id="x_6c2">Even a carefully run project can suffer an unfortunate 12.1722 + event such as the committing and uncontrolled propagation of a 12.1723 + file that contains important passwords.</para> 12.1724 + 12.1725 + <para id="x_6c3">If something like this happens to you, and the information 12.1726 + that gets accidentally propagated is truly sensitive, your 12.1727 + first step should be to mitigate the effect of the leak 12.1728 + without trying to control the leak itself. If you are not 100% 12.1729 + certain that you know exactly who could have seen the changes, 12.1730 + you should immediately change passwords, cancel credit cards, 12.1731 + or find some other way to make sure that the information that 12.1732 + has leaked is no longer useful. In other words, assume that 12.1733 + the change has propagated far and wide, and that there's 12.1734 + nothing more you can do.</para> 12.1735 + 12.1736 + <para id="x_6c4">You might hope that there would be mechanisms you could 12.1737 + use to either figure out who has seen a change or to erase the 12.1738 + change permanently everywhere, but there are good reasons why 12.1739 + these are not possible.</para> 12.1740 + 12.1741 + <para id="x_6c5">Mercurial does not provide an audit trail of who has 12.1742 + pulled changes from a repository, because it is usually either 12.1743 + impossible to record such information or trivial to spoof it. 12.1744 + In a multi-user or networked environment, you should thus be 12.1745 + extremely skeptical of yourself if you think that you have 12.1746 + identified every place that a sensitive changeset has 12.1747 + propagated to. Don't forget that people can and will send 12.1748 + bundles by email, have their backup software save data 12.1749 + offsite, carry repositories on USB sticks, and find other 12.1750 + completely innocent ways to confound your attempts to track 12.1751 + down every copy of a problematic change.</para> 12.1752 + 12.1753 + <para id="x_6c6">Mercurial also does not provide a way to make a file or 12.1754 + changeset completely disappear from history, because there is 12.1755 + no way to enforce its disappearance; someone could easily 12.1756 + modify their copy of Mercurial to ignore such directives. In 12.1757 + addition, even if Mercurial provided such a capability, 12.1758 + someone who simply hadn't pulled a <quote>make this file 12.1759 + disappear</quote> changeset wouldn't be affected by it, nor 12.1760 + would web crawlers visiting at the wrong time, disk backups, 12.1761 + or other mechanisms. Indeed, no distributed revision control 12.1762 + system can make data reliably vanish. Providing the illusion 12.1763 + of such control could easily give a false sense of security, 12.1764 + and be worse than not providing it at all.</para> 12.1765 + </sect2> 12.1766 + </sect1> 12.1767 + 12.1768 + <sect1 id="sec:undo:bisect"> 12.1769 + <title>Finding the source of a bug</title> 12.1770 + 12.1771 + <para id="x_126">While it's all very well to be able to back out a changeset 12.1772 + that introduced a bug, this requires that you know which 12.1773 + changeset to back out. Mercurial provides an invaluable 12.1774 + command, called <command role="hg-cmd">hg bisect</command>, that 12.1775 + helps you to automate this process and accomplish it very 12.1776 + efficiently.</para> 12.1777 + 12.1778 + <para id="x_127">The idea behind the <command role="hg-cmd">hg 12.1779 + bisect</command> command is that a changeset has introduced 12.1780 + some change of behavior that you can identify with a simple 12.1781 + pass/fail test. You don't know which piece of code introduced the 12.1782 + change, but you know how to test for the presence of the bug. 12.1783 + The <command role="hg-cmd">hg bisect</command> command uses your 12.1784 + test to direct its search for the changeset that introduced the 12.1785 + code that caused the bug.</para> 12.1786 + 12.1787 + <para id="x_128">Here are a few scenarios to help you understand how you 12.1788 + might apply this command.</para> 12.1789 + <itemizedlist> 12.1790 + <listitem><para id="x_129">The most recent version of your software has a 12.1791 + bug that you remember wasn't present a few weeks ago, but 12.1792 + you don't know when it was introduced. Here, your binary 12.1793 + test checks for the presence of that bug.</para> 12.1794 + </listitem> 12.1795 + <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 12.1796 + close the entry in your team's bug database. The bug 12.1797 + database requires a changeset ID when you close an entry, 12.1798 + but you don't remember which changeset you fixed the bug in. 12.1799 + Once again, your binary test checks for the presence of the 12.1800 + bug.</para> 12.1801 + </listitem> 12.1802 + <listitem><para id="x_12b">Your software works correctly, but runs 15% 12.1803 + slower than the last time you measured it. You want to know 12.1804 + which changeset introduced the performance regression. In 12.1805 + this case, your binary test measures the performance of your 12.1806 + software, to see whether it's <quote>fast</quote> or 12.1807 + <quote>slow</quote>.</para> 12.1808 + </listitem> 12.1809 + <listitem><para id="x_12c">The sizes of the components of your project that 12.1810 + you ship exploded recently, and you suspect that something 12.1811 + changed in the way you build your project.</para> 12.1812 + </listitem></itemizedlist> 12.1813 + 12.1814 + <para id="x_12d">From these examples, it should be clear that the <command 12.1815 + role="hg-cmd">hg bisect</command> command is not useful only 12.1816 + for finding the sources of bugs. You can use it to find any 12.1817 + <quote>emergent property</quote> of a repository (anything that 12.1818 + you can't find from a simple text search of the files in the 12.1819 + tree) for which you can write a binary test.</para> 12.1820 + 12.1821 + <para id="x_12e">We'll introduce a little bit of terminology here, just to 12.1822 + make it clear which parts of the search process are your 12.1823 + responsibility, and which are Mercurial's. A 12.1824 + <emphasis>test</emphasis> is something that 12.1825 + <emphasis>you</emphasis> run when <command role="hg-cmd">hg 12.1826 + bisect</command> chooses a changeset. A 12.1827 + <emphasis>probe</emphasis> is what <command role="hg-cmd">hg 12.1828 + bisect</command> runs to tell whether a revision is good. 12.1829 + Finally, we'll use the word <quote>bisect</quote>, as both a 12.1830 + noun and a verb, to stand in for the phrase <quote>search using 12.1831 + the <command role="hg-cmd">hg bisect</command> 12.1832 + command</quote>.</para> 12.1833 + 12.1834 + <para id="x_12f">One simple way to automate the searching process would be 12.1835 + simply to probe every changeset. However, this scales poorly. 12.1836 + If it took ten minutes to test a single changeset, and you had 12.1837 + 10,000 changesets in your repository, the exhaustive approach 12.1838 + would take on average 35 <emphasis>days</emphasis> to find the 12.1839 + changeset that introduced a bug. Even if you knew that the bug 12.1840 + was introduced by one of the last 500 changesets, and limited 12.1841 + your search to those, you'd still be looking at over 40 hours to 12.1842 + find the changeset that introduced your bug.</para> 12.1843 + 12.1844 + <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 12.1845 + does is use its knowledge of the <quote>shape</quote> of your 12.1846 + project's revision history to perform a search in time 12.1847 + proportional to the <emphasis>logarithm</emphasis> of the number 12.1848 + of changesets to check (the kind of search it performs is called 12.1849 + a dichotomic search). With this approach, searching through 12.1850 + 10,000 changesets will take less than three hours, even at ten 12.1851 + minutes per test (the search will require about 14 tests). 12.1852 + Limit your search to the last hundred changesets, and it will 12.1853 + take only about an hour (roughly seven tests).</para> 12.1854 + 12.1855 + <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 12.1856 + aware of the <quote>branchy</quote> nature of a Mercurial 12.1857 + project's revision history, so it has no problems dealing with 12.1858 + branches, merges, or multiple heads in a repository. It can 12.1859 + prune entire branches of history with a single probe, which is 12.1860 + how it operates so efficiently.</para> 12.1861 + 12.1862 + <sect2> 12.1863 + <title>Using the <command role="hg-cmd">hg bisect</command> 12.1864 + command</title> 12.1865 + 12.1866 + <para id="x_132">Here's an example of <command role="hg-cmd">hg 12.1867 + bisect</command> in action.</para> 12.1868 + 12.1869 + <note> 12.1870 + <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 12.1871 + role="hg-cmd">hg bisect</command> was not a core command: 12.1872 + it was distributed with Mercurial as an extension. This 12.1873 + section describes the built-in command, not the old 12.1874 + extension.</para> 12.1875 + </note> 12.1876 + 12.1877 + <para id="x_134">Now let's create a repository, so that we can try out the 12.1878 + <command role="hg-cmd">hg bisect</command> command in 12.1879 + isolation.</para> 12.1880 + 12.1881 + &interaction.bisect.init; 12.1882 + 12.1883 + <para id="x_135">We'll simulate a project that has a bug in it in a 12.1884 + simple-minded way: create trivial changes in a loop, and 12.1885 + nominate one specific change that will have the 12.1886 + <quote>bug</quote>. This loop creates 35 changesets, each 12.1887 + adding a single file to the repository. We'll represent our 12.1888 + <quote>bug</quote> with a file that contains the text <quote>i 12.1889 + have a gub</quote>.</para> 12.1890 + 12.1891 + &interaction.bisect.commits; 12.1892 + 12.1893 + <para id="x_136">The next thing that we'd like to do is figure out how to 12.1894 + use the <command role="hg-cmd">hg bisect</command> command. 12.1895 + We can use Mercurial's normal built-in help mechanism for 12.1896 + this.</para> 12.1897 + 12.1898 + &interaction.bisect.help; 12.1899 + 12.1900 + <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 12.1901 + works in steps. Each step proceeds as follows.</para> 12.1902 + <orderedlist> 12.1903 + <listitem><para id="x_138">You run your binary test.</para> 12.1904 + <itemizedlist> 12.1905 + <listitem><para id="x_139">If the test succeeded, you tell <command 12.1906 + role="hg-cmd">hg bisect</command> by running the 12.1907 + <command role="hg-cmd">hg bisect --good</command> 12.1908 + command.</para> 12.1909 + </listitem> 12.1910 + <listitem><para id="x_13a">If it failed, run the <command 12.1911 + role="hg-cmd">hg bisect --bad</command> 12.1912 + command.</para></listitem></itemizedlist> 12.1913 + </listitem> 12.1914 + <listitem><para id="x_13b">The command uses your information to decide 12.1915 + which changeset to test next.</para> 12.1916 + </listitem> 12.1917 + <listitem><para id="x_13c">It updates the working directory to that 12.1918 + changeset, and the process begins again.</para> 12.1919 + </listitem></orderedlist> 12.1920 + <para id="x_13d">The process ends when <command role="hg-cmd">hg 12.1921 + bisect</command> identifies a unique changeset that marks 12.1922 + the point where your test transitioned from 12.1923 + <quote>succeeding</quote> to <quote>failing</quote>.</para> 12.1924 + 12.1925 + <para id="x_13e">To start the search, we must run the <command 12.1926 + role="hg-cmd">hg bisect --reset</command> command.</para> 12.1927 + 12.1928 + &interaction.bisect.search.init; 12.1929 + 12.1930 + <para id="x_13f">In our case, the binary test we use is simple: we check to 12.1931 + see if any file in the repository contains the string <quote>i 12.1932 + have a gub</quote>. If it does, this changeset contains the 12.1933 + change that <quote>caused the bug</quote>. By convention, a 12.1934 + changeset that has the property we're searching for is 12.1935 + <quote>bad</quote>, while one that doesn't is 12.1936 + <quote>good</quote>.</para> 12.1937 + 12.1938 + <para id="x_140">Most of the time, the revision to which the working 12.1939 + directory is synced (usually the tip) already exhibits the 12.1940 + problem introduced by the buggy change, so we'll mark it as 12.1941 + <quote>bad</quote>.</para> 12.1942 + 12.1943 + &interaction.bisect.search.bad-init; 12.1944 + 12.1945 + <para id="x_141">Our next task is to nominate a changeset that we know 12.1946 + <emphasis>doesn't</emphasis> have the bug; the <command 12.1947 + role="hg-cmd">hg bisect</command> command will 12.1948 + <quote>bracket</quote> its search between the first pair of 12.1949 + good and bad changesets. In our case, we know that revision 12.1950 + 10 didn't have the bug. (I'll have more words about choosing 12.1951 + the first <quote>good</quote> changeset later.)</para> 12.1952 + 12.1953 + &interaction.bisect.search.good-init; 12.1954 + 12.1955 + <para id="x_142">Notice that this command printed some output.</para> 12.1956 + <itemizedlist> 12.1957 + <listitem><para id="x_143">It told us how many changesets it must 12.1958 + consider before it can identify the one that introduced 12.1959 + the bug, and how many tests that will require.</para> 12.1960 + </listitem> 12.1961 + <listitem><para id="x_144">It updated the working directory to the next 12.1962 + changeset to test, and told us which changeset it's 12.1963 + testing.</para> 12.1964 + </listitem></itemizedlist> 12.1965 + 12.1966 + <para id="x_145">We now run our test in the working directory. We use the 12.1967 + <command>grep</command> command to see if our 12.1968 + <quote>bad</quote> file is present in the working directory. 12.1969 + If it is, this revision is bad; if not, this revision is good. 12.1970 + &interaction.bisect.search.step1;</para> 12.1971 + 12.1972 + <para id="x_146">This test looks like a perfect candidate for automation, 12.1973 + so let's turn it into a shell function.</para> 12.1974 + &interaction.bisect.search.mytest; 12.1975 + 12.1976 + <para id="x_147">We can now run an entire test step with a single command, 12.1977 + <literal>mytest</literal>.</para> 12.1978 + 12.1979 + &interaction.bisect.search.step2; 12.1980 + 12.1981 + <para id="x_148">A few more invocations of our canned test step command, 12.1982 + and we're done.</para> 12.1983 + 12.1984 + &interaction.bisect.search.rest; 12.1985 + 12.1986 + <para id="x_149">Even though we had 40 changesets to search through, the 12.1987 + <command role="hg-cmd">hg bisect</command> command let us find 12.1988 + the changeset that introduced our <quote>bug</quote> with only 12.1989 + five tests. Because the number of tests that the <command 12.1990 + role="hg-cmd">hg bisect</command> command performs grows 12.1991 + logarithmically with the number of changesets to search, the 12.1992 + advantage that it has over the <quote>brute force</quote> 12.1993 + search approach increases with every changeset you add.</para> 12.1994 + 12.1995 + </sect2> 12.1996 + <sect2> 12.1997 + <title>Cleaning up after your search</title> 12.1998 + 12.1999 + <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 12.2000 + bisect</command> command in a repository, you can use the 12.2001 + <command role="hg-cmd">hg bisect --reset</command> command to 12.2002 + drop the information it was using to drive your search. The 12.2003 + command doesn't use much space, so it doesn't matter if you 12.2004 + forget to run this command. However, <command 12.2005 + role="hg-cmd">hg bisect</command> won't let you start a new 12.2006 + search in that repository until you do a <command 12.2007 + role="hg-cmd">hg bisect --reset</command>.</para> 12.2008 + 12.2009 + &interaction.bisect.search.reset; 12.2010 + 12.2011 + </sect2> 12.2012 + </sect1> 12.2013 + <sect1> 12.2014 + <title>Tips for finding bugs effectively</title> 12.2015 + 12.2016 + <sect2> 12.2017 + <title>Give consistent input</title> 12.2018 + 12.2019 + <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 12.2020 + requires that you correctly report the result of every test 12.2021 + you perform. If you tell it that a test failed when it really 12.2022 + succeeded, it <emphasis>might</emphasis> be able to detect the 12.2023 + inconsistency. If it can identify an inconsistency in your 12.2024 + reports, it will tell you that a particular changeset is both 12.2025 + good and bad. However, it can't do this perfectly; it's about 12.2026 + as likely to report the wrong changeset as the source of the 12.2027 + bug.</para> 12.2028 + 12.2029 + </sect2> 12.2030 + <sect2> 12.2031 + <title>Automate as much as possible</title> 12.2032 + 12.2033 + <para id="x_14c">When I started using the <command role="hg-cmd">hg 12.2034 + bisect</command> command, I tried a few times to run my 12.2035 + tests by hand, on the command line. This is an approach that 12.2036 + I, at least, am not suited to. After a few tries, I found 12.2037 + that I was making enough mistakes that I was having to restart 12.2038 + my searches several times before finally getting correct 12.2039 + results.</para> 12.2040 + 12.2041 + <para id="x_14d">My initial problems with driving the <command 12.2042 + role="hg-cmd">hg bisect</command> command by hand occurred 12.2043 + even with simple searches on small repositories; if the 12.2044 + problem you're looking for is more subtle, or the number of 12.2045 + tests that <command role="hg-cmd">hg bisect</command> must 12.2046 + perform increases, the likelihood of operator error ruining 12.2047 + the search is much higher. Once I started automating my 12.2048 + tests, I had much better results.</para> 12.2049 + 12.2050 + <para id="x_14e">The key to automated testing is twofold:</para> 12.2051 + <itemizedlist> 12.2052 + <listitem><para id="x_14f">always test for the same symptom, and</para> 12.2053 + </listitem> 12.2054 + <listitem><para id="x_150">always feed consistent input to the <command 12.2055 + role="hg-cmd">hg bisect</command> command.</para> 12.2056 + </listitem></itemizedlist> 12.2057 + <para id="x_151">In my tutorial example above, the <command>grep</command> 12.2058 + command tests for the symptom, and the <literal>if</literal> 12.2059 + statement takes the result of this check and ensures that we 12.2060 + always feed the same input to the <command role="hg-cmd">hg 12.2061 + bisect</command> command. The <literal>mytest</literal> 12.2062 + function marries these together in a reproducible way, so that 12.2063 + every test is uniform and consistent.</para> 12.2064 + 12.2065 + </sect2> 12.2066 + <sect2> 12.2067 + <title>Check your results</title> 12.2068 + 12.2069 + <para id="x_152">Because the output of a <command role="hg-cmd">hg 12.2070 + bisect</command> search is only as good as the input you 12.2071 + give it, don't take the changeset it reports as the absolute 12.2072 + truth. A simple way to cross-check its report is to manually 12.2073 + run your test at each of the following changesets:</para> 12.2074 + <itemizedlist> 12.2075 + <listitem><para id="x_153">The changeset that it reports as the first bad 12.2076 + revision. Your test should still report this as 12.2077 + bad.</para> 12.2078 + </listitem> 12.2079 + <listitem><para id="x_154">The parent of that changeset (either parent, 12.2080 + if it's a merge). Your test should report this changeset 12.2081 + as good.</para> 12.2082 + </listitem> 12.2083 + <listitem><para id="x_155">A child of that changeset. Your test should 12.2084 + report this changeset as bad.</para> 12.2085 + </listitem></itemizedlist> 12.2086 + 12.2087 + </sect2> 12.2088 + <sect2> 12.2089 + <title>Beware interference between bugs</title> 12.2090 + 12.2091 + <para id="x_156">It's possible that your search for one bug could be 12.2092 + disrupted by the presence of another. For example, let's say 12.2093 + your software crashes at revision 100, and worked correctly at 12.2094 + revision 50. Unknown to you, someone else introduced a 12.2095 + different crashing bug at revision 60, and fixed it at 12.2096 + revision 80. This could distort your results in one of 12.2097 + several ways.</para> 12.2098 + 12.2099 + <para id="x_157">It is possible that this other bug completely 12.2100 + <quote>masks</quote> yours, which is to say that it occurs 12.2101 + before your bug has a chance to manifest itself. If you can't 12.2102 + avoid that other bug (for example, it prevents your project 12.2103 + from building), and so can't tell whether your bug is present 12.2104 + in a particular changeset, the <command role="hg-cmd">hg 12.2105 + bisect</command> command cannot help you directly. Instead, 12.2106 + you can mark a changeset as untested by running <command 12.2107 + role="hg-cmd">hg bisect --skip</command>.</para> 12.2108 + 12.2109 + <para id="x_158">A different problem could arise if your test for a bug's 12.2110 + presence is not specific enough. If you check for <quote>my 12.2111 + program crashes</quote>, then both your crashing bug and an 12.2112 + unrelated crashing bug that masks it will look like the same 12.2113 + thing, and mislead <command role="hg-cmd">hg 12.2114 + bisect</command>.</para> 12.2115 + 12.2116 + <para id="x_159">Another useful situation in which to use <command 12.2117 + role="hg-cmd">hg bisect --skip</command> is if you can't 12.2118 + test a revision because your project was in a broken and hence 12.2119 + untestable state at that revision, perhaps because someone 12.2120 + checked in a change that prevented the project from 12.2121 + building.</para> 12.2122 + 12.2123 + </sect2> 12.2124 + <sect2> 12.2125 + <title>Bracket your search lazily</title> 12.2126 + 12.2127 + <para id="x_15a">Choosing the first <quote>good</quote> and 12.2128 + <quote>bad</quote> changesets that will mark the end points of 12.2129 + your search is often easy, but it bears a little discussion 12.2130 + nevertheless. From the perspective of <command 12.2131 + role="hg-cmd">hg bisect</command>, the <quote>newest</quote> 12.2132 + changeset is conventionally <quote>bad</quote>, and the older 12.2133 + changeset is <quote>good</quote>.</para> 12.2134 + 12.2135 + <para id="x_15b">If you're having trouble remembering when a suitable 12.2136 + <quote>good</quote> change was, so that you can tell <command 12.2137 + role="hg-cmd">hg bisect</command>, you could do worse than 12.2138 + testing changesets at random. Just remember to eliminate 12.2139 + contenders that can't possibly exhibit the bug (perhaps 12.2140 + because the feature with the bug isn't present yet) and those 12.2141 + where another problem masks the bug (as I discussed 12.2142 + above).</para> 12.2143 + 12.2144 + <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 12.2145 + changesets or months of history, you will only add a handful 12.2146 + of tests to the total number that <command role="hg-cmd">hg 12.2147 + bisect</command> must perform, thanks to its logarithmic 12.2148 + behavior.</para> 12.2149 + 12.2150 + </sect2> 12.2151 + </sect1> 12.2152 </chapter> 12.2153 12.2154 <!-- 12.2155 local variables: 12.2156 sgml-parent-document: ("00book.xml" "book" "chapter") 12.2157 end: 12.2158 ---> 12.2159 \ No newline at end of file 12.2160 +-->
13.1 --- a/fr/ch10-hook.xml Sat Sep 12 17:58:26 2009 +0200 13.2 +++ b/fr/ch10-hook.xml Sat Sep 12 17:58:56 2009 +0200 13.3 @@ -1,1883 +1,1928 @@ 13.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 13.5 13.6 -<chapter> 13.7 -<title>Handling repository events with hooks</title> 13.8 -<para>\label{chap:hook}</para> 13.9 - 13.10 -<para>Mercurial offers a powerful mechanism to let you perform automated 13.11 -actions in response to events that occur in a repository. In some 13.12 -cases, you can even control Mercurial's response to those events.</para> 13.13 - 13.14 -<para>The name Mercurial uses for one of these actions is a <emphasis>hook</emphasis>. 13.15 -Hooks are called <quote>triggers</quote> in some revision control systems, but 13.16 -the two names refer to the same idea.</para> 13.17 - 13.18 -<sect1> 13.19 -<title>An overview of hooks in Mercurial</title> 13.20 - 13.21 -<para>Here is a brief list of the hooks that Mercurial supports. We will 13.22 -revisit each of these hooks in more detail later, in 13.23 -section <xref linkend="sec:hook:ref"/>.</para> 13.24 - 13.25 -<itemizedlist> 13.26 -<listitem><para><literal role="hook">changegroup</literal>: This is run after a group of 13.27 - changesets has been brought into the repository from elsewhere.</para> 13.28 -</listitem> 13.29 -<listitem><para><literal role="hook">commit</literal>: This is run after a new changeset has been 13.30 - created in the local repository.</para> 13.31 -</listitem> 13.32 -<listitem><para><literal role="hook">incoming</literal>: This is run once for each new changeset 13.33 - that is brought into the repository from elsewhere. Notice the 13.34 - difference from <literal role="hook">changegroup</literal>, which is run once per 13.35 - <emphasis>group</emphasis> of changesets brought in.</para> 13.36 -</listitem> 13.37 -<listitem><para><literal role="hook">outgoing</literal>: This is run after a group of changesets 13.38 - has been transmitted from this repository.</para> 13.39 -</listitem> 13.40 -<listitem><para><literal role="hook">prechangegroup</literal>: This is run before starting to 13.41 - bring a group of changesets into the repository. 13.42 -</para> 13.43 -</listitem> 13.44 -<listitem><para><literal role="hook">precommit</literal>: Controlling. This is run before starting 13.45 - a commit. 13.46 -</para> 13.47 -</listitem> 13.48 -<listitem><para><literal role="hook">preoutgoing</literal>: Controlling. This is run before 13.49 - starting to transmit a group of changesets from this repository. 13.50 -</para> 13.51 -</listitem> 13.52 -<listitem><para><literal role="hook">pretag</literal>: Controlling. This is run before creating a tag. 13.53 -</para> 13.54 -</listitem> 13.55 -<listitem><para><literal role="hook">pretxnchangegroup</literal>: Controlling. This is run after a 13.56 - group of changesets has been brought into the local repository from 13.57 - another, but before the transaction completes that will make the 13.58 - changes permanent in the repository. 13.59 -</para> 13.60 -</listitem> 13.61 -<listitem><para><literal role="hook">pretxncommit</literal>: Controlling. This is run after a new 13.62 - changeset has been created in the local repository, but before the 13.63 - transaction completes that will make it permanent. 13.64 -</para> 13.65 -</listitem> 13.66 -<listitem><para><literal role="hook">preupdate</literal>: Controlling. This is run before starting 13.67 - an update or merge of the working directory. 13.68 -</para> 13.69 -</listitem> 13.70 -<listitem><para><literal role="hook">tag</literal>: This is run after a tag is created. 13.71 -</para> 13.72 -</listitem> 13.73 -<listitem><para><literal role="hook">update</literal>: This is run after an update or merge of the 13.74 - working directory has finished. 13.75 -</para> 13.76 -</listitem></itemizedlist> 13.77 -<para>Each of the hooks whose description begins with the word 13.78 -<quote>Controlling</quote> has the ability to determine whether an activity can 13.79 -proceed. If the hook succeeds, the activity may proceed; if it fails, 13.80 -the activity is either not permitted or undone, depending on the hook. 13.81 -</para> 13.82 - 13.83 -</sect1> 13.84 -<sect1> 13.85 -<title>Hooks and security</title> 13.86 - 13.87 -<sect2> 13.88 -<title>Hooks are run with your privileges</title> 13.89 - 13.90 -<para>When you run a Mercurial command in a repository, and the command 13.91 -causes a hook to run, that hook runs on <emphasis>your</emphasis> system, under 13.92 -<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> privilege level. Since 13.93 -hooks are arbitrary pieces of executable code, you should treat them 13.94 -with an appropriate level of suspicion. Do not install a hook unless 13.95 -you are confident that you know who created it and what it does. 13.96 -</para> 13.97 - 13.98 -<para>In some cases, you may be exposed to hooks that you did not install 13.99 -yourself. If you work with Mercurial on an unfamiliar system, 13.100 -Mercurial will run hooks defined in that system's global <filename role="special"> /.hgrc</filename>\ file. 13.101 -</para> 13.102 - 13.103 -<para>If you are working with a repository owned by another user, Mercurial 13.104 -can run hooks defined in that user's repository, but it will still run 13.105 -them as <quote>you</quote>. For example, if you <command role="hg-cmd">hg pull</command> from that 13.106 -repository, and its <filename role="special">.hg/hgrc</filename> defines a local 13.107 -<literal role="hook">outgoing</literal> hook, that hook will run under your user account, even 13.108 -though you don't own that repository. 13.109 -</para> 13.110 - 13.111 -<note> 13.112 -<para> This only applies if you are pulling from a repository on a local or 13.113 - network filesystem. If you're pulling over http or ssh, any 13.114 - <literal role="hook">outgoing</literal> hook will run under whatever account is executing 13.115 - the server process, on the server. 13.116 -</para> 13.117 -</note> 13.118 - 13.119 -<para>XXX To see what hooks are defined in a repository, use the 13.120 -<command role="hg-cmd">hg config hooks</command> command. If you are working in one 13.121 -repository, but talking to another that you do not own (e.g. using 13.122 -<command role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg incoming</command>), remember that it is the other 13.123 -repository's hooks you should be checking, not your own. 13.124 -</para> 13.125 - 13.126 -</sect2> 13.127 -<sect2> 13.128 -<title>Hooks do not propagate</title> 13.129 - 13.130 -<para>In Mercurial, hooks are not revision controlled, and do not propagate 13.131 -when you clone, or pull from, a repository. The reason for this is 13.132 -simple: a hook is a completely arbitrary piece of executable code. It 13.133 -runs under your user identity, with your privilege level, on your 13.134 -machine. 13.135 -</para> 13.136 - 13.137 -<para>It would be extremely reckless for any distributed revision control 13.138 -system to implement revision-controlled hooks, as this would offer an 13.139 -easily exploitable way to subvert the accounts of users of the 13.140 -revision control system. 13.141 -</para> 13.142 - 13.143 -<para>Since Mercurial does not propagate hooks, if you are collaborating 13.144 -with other people on a common project, you should not assume that they 13.145 -are using the same Mercurial hooks as you are, or that theirs are 13.146 -correctly configured. You should document the hooks you expect people 13.147 -to use. 13.148 -</para> 13.149 - 13.150 -<para>In a corporate intranet, this is somewhat easier to control, as you 13.151 -can for example provide a <quote>standard</quote> installation of Mercurial on an 13.152 -NFS filesystem, and use a site-wide <filename role="special"> /.hgrc</filename>\ file to define hooks that 13.153 -all users will see. However, this too has its limits; see below. 13.154 -</para> 13.155 - 13.156 -</sect2> 13.157 -<sect2> 13.158 -<title>Hooks can be overridden</title> 13.159 - 13.160 -<para>Mercurial allows you to override a hook definition by redefining the 13.161 -hook. You can disable it by setting its value to the empty string, or 13.162 -change its behaviour as you wish. 13.163 -</para> 13.164 - 13.165 -<para>If you deploy a system- or site-wide <filename role="special"> /.hgrc</filename>\ file that defines some 13.166 -hooks, you should thus understand that your users can disable or 13.167 -override those hooks. 13.168 -</para> 13.169 - 13.170 -</sect2> 13.171 -<sect2> 13.172 -<title>Ensuring that critical hooks are run</title> 13.173 - 13.174 -<para>Sometimes you may want to enforce a policy that you do not want others 13.175 -to be able to work around. For example, you may have a requirement 13.176 -that every changeset must pass a rigorous set of tests. Defining this 13.177 -requirement via a hook in a site-wide <filename role="special"> /.hgrc</filename>\ won't work for remote 13.178 -users on laptops, and of course local users can subvert it at will by 13.179 -overriding the hook. 13.180 -</para> 13.181 - 13.182 -<para>Instead, you can set up your policies for use of Mercurial so that 13.183 -people are expected to propagate changes through a well-known 13.184 -<quote>canonical</quote> server that you have locked down and configured 13.185 -appropriately. 13.186 -</para> 13.187 - 13.188 -<para>One way to do this is via a combination of social engineering and 13.189 -technology. Set up a restricted-access account; users can push 13.190 -changes over the network to repositories managed by this account, but 13.191 -they cannot log into the account and run normal shell commands. In 13.192 -this scenario, a user can commit a changeset that contains any old 13.193 -garbage they want. 13.194 -</para> 13.195 - 13.196 -<para>When someone pushes a changeset to the server that everyone pulls 13.197 -from, the server will test the changeset before it accepts it as 13.198 -permanent, and reject it if it fails to pass the test suite. If 13.199 -people only pull changes from this filtering server, it will serve to 13.200 -ensure that all changes that people pull have been automatically 13.201 -vetted. 13.202 -</para> 13.203 - 13.204 -</sect2> 13.205 -</sect1> 13.206 -<sect1> 13.207 -<title>Care with <literal>pretxn</literal> hooks in a shared-access repository</title> 13.208 - 13.209 -<para>If you want to use hooks to do some automated work in a repository 13.210 -that a number of people have shared access to, you need to be careful 13.211 -in how you do this. 13.212 -</para> 13.213 - 13.214 -<para>Mercurial only locks a repository when it is writing to the 13.215 -repository, and only the parts of Mercurial that write to the 13.216 -repository pay attention to locks. Write locks are necessary to 13.217 -prevent multiple simultaneous writers from scribbling on each other's 13.218 -work, corrupting the repository. 13.219 -</para> 13.220 - 13.221 -<para>Because Mercurial is careful with the order in which it reads and 13.222 -writes data, it does not need to acquire a lock when it wants to read 13.223 -data from the repository. The parts of Mercurial that read from the 13.224 -repository never pay attention to locks. This lockless reading scheme 13.225 -greatly increases performance and concurrency. 13.226 -</para> 13.227 - 13.228 -<para>With great performance comes a trade-off, though, one which has the 13.229 -potential to cause you trouble unless you're aware of it. To describe 13.230 -this requires a little detail about how Mercurial adds changesets to a 13.231 -repository and reads those changes. 13.232 -</para> 13.233 - 13.234 -<para>When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight into the 13.235 -destination file. It writes file data first, then manifest data 13.236 -(which contains pointers to the new file data), then changelog data 13.237 -(which contains pointers to the new manifest data). Before the first 13.238 -write to each file, it stores a record of where the end of the file 13.239 -was in its transaction log. If the transaction must be rolled back, 13.240 -Mercurial simply truncates each file back to the size it was before the 13.241 -transaction began. 13.242 -</para> 13.243 - 13.244 -<para>When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog first, 13.245 -then everything else. Since a reader will only access parts of the 13.246 -manifest or file metadata that it can see in the changelog, it can 13.247 -never see partially written data. 13.248 -</para> 13.249 - 13.250 -<para>Some controlling hooks (<literal role="hook">pretxncommit</literal> and 13.251 -<literal role="hook">pretxnchangegroup</literal>) run when a transaction is almost complete. 13.252 -All of the metadata has been written, but Mercurial can still roll the 13.253 -transaction back and cause the newly-written data to disappear. 13.254 -</para> 13.255 - 13.256 -<para>If one of these hooks runs for long, it opens a window of time during 13.257 -which a reader can see the metadata for changesets that are not yet 13.258 -permanent, and should not be thought of as <quote>really there</quote>. The 13.259 -longer the hook runs, the longer that window is open. 13.260 -</para> 13.261 - 13.262 -<sect2> 13.263 -<title>The problem illustrated</title> 13.264 - 13.265 -<para>In principle, a good use for the <literal role="hook">pretxnchangegroup</literal> hook would 13.266 -be to automatically build and test incoming changes before they are 13.267 -accepted into a central repository. This could let you guarantee that 13.268 -nobody can push changes to this repository that <quote>break the build</quote>. 13.269 -But if a client can pull changes while they're being tested, the 13.270 -usefulness of the test is zero; an unsuspecting someone can pull 13.271 -untested changes, potentially breaking their build. 13.272 -</para> 13.273 - 13.274 -<para>The safest technological answer to this challenge is to set up such a 13.275 -<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>. Let it take 13.276 -changes pushed in from the outside, but do not allow anyone to pull 13.277 -changes from it (use the <literal role="hook">preoutgoing</literal> hook to lock it down). 13.278 -Configure a <literal role="hook">changegroup</literal> hook so that if a build or test 13.279 -succeeds, the hook will push the new changes out to another repository 13.280 -that people <emphasis>can</emphasis> pull from. 13.281 -</para> 13.282 - 13.283 -<para>In practice, putting a centralised bottleneck like this in place is 13.284 -not often a good idea, and transaction visibility has nothing to do 13.285 -with the problem. As the size of a project&emdash;and the time it takes to 13.286 -build and test&emdash;grows, you rapidly run into a wall with this <quote>try 13.287 -before you buy</quote> approach, where you have more changesets to test than 13.288 -time in which to deal with them. The inevitable result is frustration 13.289 -on the part of all involved. 13.290 -</para> 13.291 - 13.292 -<para>An approach that scales better is to get people to build and test 13.293 -before they push, then run automated builds and tests centrally 13.294 -<emphasis>after</emphasis> a push, to be sure all is well. The advantage of this 13.295 -approach is that it does not impose a limit on the rate at which the 13.296 -repository can accept changes. 13.297 -</para> 13.298 - 13.299 -</sect2> 13.300 -</sect1> 13.301 -<sect1> 13.302 -<title>A short tutorial on using hooks</title> 13.303 -<para>\label{sec:hook:simple} 13.304 -</para> 13.305 - 13.306 -<para>It is easy to write a Mercurial hook. Let's start with a hook that 13.307 -runs when you finish a <command role="hg-cmd">hg commit</command>, and simply prints the hash of 13.308 -the changeset you just created. The hook is called <literal role="hook">commit</literal>. 13.309 -</para> 13.310 - 13.311 -<informalfigure> 13.312 -<para> <!-- &interaction.hook.simple.init; --> 13.313 - <caption><para>A simple hook that runs when a changeset is committed</para></caption> 13.314 - \label{ex:hook:init} 13.315 -</para> 13.316 -</informalfigure> 13.317 - 13.318 -<para>All hooks follow the pattern in example <xref linkend="ex:hook:init"/>. You add 13.319 -an entry to the <literal role="rc-hooks">hooks</literal> section of your <filename role="special"> /.hgrc</filename>. On the left 13.320 -is the name of the event to trigger on; on the right is the action to 13.321 -take. As you can see, you can run an arbitrary shell command in a 13.322 -hook. Mercurial passes extra information to the hook using 13.323 -environment variables (look for <envar>HG_NODE</envar> in the example). 13.324 -</para> 13.325 - 13.326 -<sect2> 13.327 -<title>Performing multiple actions per event</title> 13.328 - 13.329 -<para>Quite often, you will want to define more than one hook for a 13.330 -particular kind of event, as shown in example <xref linkend="ex:hook:ext"/>. 13.331 -Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the end of 13.332 -a hook's name. You extend a hook's name by giving the name of the 13.333 -hook, followed by a full stop (the <quote><literal>.</literal></quote> character), followed 13.334 -by some more text of your choosing. For example, Mercurial will run 13.335 -both <literal>commit.foo</literal> and <literal>commit.bar</literal> when the 13.336 -<literal>commit</literal> event occurs. 13.337 -</para> 13.338 - 13.339 -<informalfigure> 13.340 -<para> <!-- &interaction.hook.simple.ext; --> 13.341 - <caption><para>Defining a second <literal role="hook">commit</para></caption> hook</literal> 13.342 - \label{ex:hook:ext} 13.343 -</para> 13.344 -</informalfigure> 13.345 - 13.346 -<para>To give a well-defined order of execution when there are multiple 13.347 -hooks defined for an event, Mercurial sorts hooks by extension, and 13.348 -executes the hook commands in this sorted order. In the above 13.349 -example, it will execute <literal>commit.bar</literal> before 13.350 -<literal>commit.foo</literal>, and <literal>commit</literal> before both. 13.351 -</para> 13.352 - 13.353 -<para>It is a good idea to use a somewhat descriptive extension when you 13.354 -define a new hook. This will help you to remember what the hook was 13.355 -for. If the hook fails, you'll get an error message that contains the 13.356 -hook name and extension, so using a descriptive extension could give 13.357 -you an immediate hint as to why the hook failed (see 13.358 -section <xref linkend="sec:hook:perm"/> for an example). 13.359 -</para> 13.360 - 13.361 -</sect2> 13.362 -<sect2> 13.363 -<title>Controlling whether an activity can proceed</title> 13.364 -<para>\label{sec:hook:perm} 13.365 -</para> 13.366 - 13.367 -<para>In our earlier examples, we used the <literal role="hook">commit</literal> hook, which is 13.368 -run after a commit has completed. This is one of several Mercurial 13.369 -hooks that run after an activity finishes. Such hooks have no way of 13.370 -influencing the activity itself. 13.371 -</para> 13.372 - 13.373 -<para>Mercurial defines a number of events that occur before an activity 13.374 -starts; or after it starts, but before it finishes. Hooks that 13.375 -trigger on these events have the added ability to choose whether the 13.376 -activity can continue, or will abort. 13.377 -</para> 13.378 - 13.379 -<para>The <literal role="hook">pretxncommit</literal> hook runs after a commit has all but 13.380 -completed. In other words, the metadata representing the changeset 13.381 -has been written out to disk, but the transaction has not yet been 13.382 -allowed to complete. The <literal role="hook">pretxncommit</literal> hook has the ability to 13.383 -decide whether the transaction can complete, or must be rolled back. 13.384 -</para> 13.385 - 13.386 -<para>If the <literal role="hook">pretxncommit</literal> hook exits with a status code of zero, the 13.387 -transaction is allowed to complete; the commit finishes; and the 13.388 -<literal role="hook">commit</literal> hook is run. If the <literal role="hook">pretxncommit</literal> hook exits with 13.389 -a non-zero status code, the transaction is rolled back; the metadata 13.390 -representing the changeset is erased; and the <literal role="hook">commit</literal> hook is 13.391 -not run. 13.392 -</para> 13.393 - 13.394 -<informalfigure> 13.395 -<para> <!-- &interaction.hook.simple.pretxncommit; --> 13.396 - <caption><para>Using the <literal role="hook">pretxncommit</para></caption> hook to control commits</literal> 13.397 - \label{ex:hook:pretxncommit} 13.398 -</para> 13.399 -</informalfigure> 13.400 - 13.401 -<para>The hook in example <xref linkend="ex:hook:pretxncommit"/> checks that a commit 13.402 -comment contains a bug ID. If it does, the commit can complete. If 13.403 -not, the commit is rolled back. 13.404 -</para> 13.405 - 13.406 -</sect2> 13.407 -</sect1> 13.408 -<sect1> 13.409 -<title>Writing your own hooks</title> 13.410 - 13.411 -<para>When you are writing a hook, you might find it useful to run Mercurial 13.412 -either with the <option role="hg-opt-global">-v</option> option, or the <envar role="rc-item-ui">verbose</envar> config 13.413 -item set to <quote>true</quote>. When you do so, Mercurial will print a message 13.414 -before it calls each hook. 13.415 -</para> 13.416 - 13.417 -<sect2> 13.418 -<title>Choosing how your hook should run</title> 13.419 -<para>\label{sec:hook:lang} 13.420 -</para> 13.421 - 13.422 -<para>You can write a hook either as a normal program&emdash;typically a shell 13.423 -script&emdash;or as a Python function that is executed within the Mercurial 13.424 -process. 13.425 -</para> 13.426 - 13.427 -<para>Writing a hook as an external program has the advantage that it 13.428 -requires no knowledge of Mercurial's internals. You can call normal 13.429 -Mercurial commands to get any added information you need. The 13.430 -trade-off is that external hooks are slower than in-process hooks. 13.431 -</para> 13.432 - 13.433 -<para>An in-process Python hook has complete access to the Mercurial API, 13.434 -and does not <quote>shell out</quote> to another process, so it is inherently 13.435 -faster than an external hook. It is also easier to obtain much of the 13.436 -information that a hook requires by using the Mercurial API than by 13.437 -running Mercurial commands. 13.438 -</para> 13.439 - 13.440 -<para>If you are comfortable with Python, or require high performance, 13.441 -writing your hooks in Python may be a good choice. However, when you 13.442 -have a straightforward hook to write and you don't need to care about 13.443 -performance (probably the majority of hooks), a shell script is 13.444 -perfectly fine. 13.445 -</para> 13.446 - 13.447 -</sect2> 13.448 -<sect2> 13.449 -<title>Hook parameters</title> 13.450 -<para>\label{sec:hook:param} 13.451 -</para> 13.452 - 13.453 -<para>Mercurial calls each hook with a set of well-defined parameters. In 13.454 -Python, a parameter is passed as a keyword argument to your hook 13.455 -function. For an external program, a parameter is passed as an 13.456 -environment variable. 13.457 -</para> 13.458 - 13.459 -<para>Whether your hook is written in Python or as a shell script, the 13.460 -hook-specific parameter names and values will be the same. A boolean 13.461 -parameter will be represented as a boolean value in Python, but as the 13.462 -number 1 (for <quote>true</quote>) or 0 (for <quote>false</quote>) as an environment 13.463 -variable for an external hook. If a hook parameter is named 13.464 -<literal>foo</literal>, the keyword argument for a Python hook will also be 13.465 -named <literal>foo</literal>, while the environment variable for an external 13.466 -hook will be named <literal>HG_FOO</literal>. 13.467 -</para> 13.468 - 13.469 -</sect2> 13.470 -<sect2> 13.471 -<title>Hook return values and activity control</title> 13.472 - 13.473 -<para>A hook that executes successfully must exit with a status of zero if 13.474 -external, or return boolean <quote>false</quote> if in-process. Failure is 13.475 -indicated with a non-zero exit status from an external hook, or an 13.476 -in-process hook returning boolean <quote>true</quote>. If an in-process hook 13.477 -raises an exception, the hook is considered to have failed. 13.478 -</para> 13.479 - 13.480 -<para>For a hook that controls whether an activity can proceed, zero/false 13.481 -means <quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>. 13.482 -</para> 13.483 - 13.484 -</sect2> 13.485 -<sect2> 13.486 -<title>Writing an external hook</title> 13.487 - 13.488 -<para>When you define an external hook in your <filename role="special"> /.hgrc</filename>\ and the hook is run, 13.489 -its value is passed to your shell, which interprets it. This means 13.490 -that you can use normal shell constructs in the body of the hook. 13.491 -</para> 13.492 - 13.493 -<para>An executable hook is always run with its current directory set to a 13.494 -repository's root directory. 13.495 -</para> 13.496 - 13.497 -<para>Each hook parameter is passed in as an environment variable; the name 13.498 -is upper-cased, and prefixed with the string <quote><literal>HG_</literal></quote>. 13.499 -</para> 13.500 - 13.501 -<para>With the exception of hook parameters, Mercurial does not set or 13.502 -modify any environment variables when running a hook. This is useful 13.503 -to remember if you are writing a site-wide hook that may be run by a 13.504 -number of different users with differing environment variables set. 13.505 -In multi-user situations, you should not rely on environment variables 13.506 -being set to the values you have in your environment when testing the 13.507 -hook. 13.508 -</para> 13.509 - 13.510 -</sect2> 13.511 -<sect2> 13.512 -<title>Telling Mercurial to use an in-process hook</title> 13.513 - 13.514 -<para>The <filename role="special"> /.hgrc</filename>\ syntax for defining an in-process hook is slightly 13.515 -different than for an executable hook. The value of the hook must 13.516 -start with the text <quote><literal>python:</literal></quote>, and continue with the 13.517 -fully-qualified name of a callable object to use as the hook's value. 13.518 -</para> 13.519 - 13.520 -<para>The module in which a hook lives is automatically imported when a hook 13.521 -is run. So long as you have the module name and <envar>PYTHONPATH</envar> 13.522 -right, it should <quote>just work</quote>. 13.523 -</para> 13.524 - 13.525 -<para>The following <filename role="special"> /.hgrc</filename>\ example snippet illustrates the syntax and 13.526 -meaning of the notions we just described. 13.527 -</para> 13.528 -<programlisting> 13.529 -<para> [hooks] 13.530 - commit.example = python:mymodule.submodule.myhook 13.531 -</para> 13.532 -</programlisting> 13.533 -<para>When Mercurial runs the <literal>commit.example</literal> hook, it imports 13.534 -<literal>mymodule.submodule</literal>, looks for the callable object named 13.535 -<literal>myhook</literal>, and calls it. 13.536 -</para> 13.537 - 13.538 -</sect2> 13.539 -<sect2> 13.540 -<title>Writing an in-process hook</title> 13.541 - 13.542 -<para>The simplest in-process hook does nothing, but illustrates the basic 13.543 -shape of the hook API: 13.544 -</para> 13.545 -<programlisting> 13.546 -<para> def myhook(ui, repo, **kwargs): 13.547 - pass 13.548 -</para> 13.549 -</programlisting> 13.550 -<para>The first argument to a Python hook is always a 13.551 -<literal role="py-mod-mercurial.ui">ui</literal> object. The second is a repository object; 13.552 -at the moment, it is always an instance of 13.553 -<literal role="py-mod-mercurial.localrepo">localrepository</literal>. Following these two 13.554 -arguments are other keyword arguments. Which ones are passed in 13.555 -depends on the hook being called, but a hook can ignore arguments it 13.556 -doesn't care about by dropping them into a keyword argument dict, as 13.557 -with <literal>**kwargs</literal> above. 13.558 -</para> 13.559 - 13.560 -</sect2> 13.561 -</sect1> 13.562 -<sect1> 13.563 -<title>Some hook examples</title> 13.564 - 13.565 -<sect2> 13.566 -<title>Writing meaningful commit messages</title> 13.567 - 13.568 -<para>It's hard to imagine a useful commit message being very short. The 13.569 -simple <literal role="hook">pretxncommit</literal> hook of figure <xref linkend="ex:hook:msglen.go"/> 13.570 -will prevent you from committing a changeset with a message that is 13.571 -less than ten bytes long. 13.572 -</para> 13.573 - 13.574 -<informalfigure> 13.575 -<para> <!-- &interaction.hook.msglen.go; --> 13.576 - <caption><para>A hook that forbids overly short commit messages</para></caption> 13.577 - \label{ex:hook:msglen.go} 13.578 -</para> 13.579 -</informalfigure> 13.580 - 13.581 -</sect2> 13.582 -<sect2> 13.583 -<title>Checking for trailing whitespace</title> 13.584 - 13.585 -<para>An interesting use of a commit-related hook is to help you to write 13.586 -cleaner code. A simple example of <quote>cleaner code</quote> is the dictum that 13.587 -a change should not add any new lines of text that contain <quote>trailing 13.588 -whitespace</quote>. Trailing whitespace is a series of space and tab 13.589 -characters at the end of a line of text. In most cases, trailing 13.590 -whitespace is unnecessary, invisible noise, but it is occasionally 13.591 -problematic, and people often prefer to get rid of it. 13.592 -</para> 13.593 - 13.594 -<para>You can use either the <literal role="hook">precommit</literal> or <literal role="hook">pretxncommit</literal> hook to 13.595 -tell whether you have a trailing whitespace problem. If you use the 13.596 -<literal role="hook">precommit</literal> hook, the hook will not know which files you are 13.597 -committing, so it will have to check every modified file in the 13.598 -repository for trailing white space. If you want to commit a change 13.599 -to just the file <filename>foo</filename>, but the file <filename>bar</filename> contains 13.600 -trailing whitespace, doing a check in the <literal role="hook">precommit</literal> hook will 13.601 -prevent you from committing <filename>foo</filename> due to the problem with 13.602 -<filename>bar</filename>. This doesn't seem right. 13.603 -</para> 13.604 - 13.605 -<para>Should you choose the <literal role="hook">pretxncommit</literal> hook, the check won't occur 13.606 -until just before the transaction for the commit completes. This will 13.607 -allow you to check for problems only the exact files that are being 13.608 -committed. However, if you entered the commit message interactively 13.609 -and the hook fails, the transaction will roll back; you'll have to 13.610 -re-enter the commit message after you fix the trailing whitespace and 13.611 -run <command role="hg-cmd">hg commit</command> again. 13.612 -</para> 13.613 - 13.614 -<informalfigure> 13.615 -<para> <!-- &interaction.hook.ws.simple; --> 13.616 - <caption><para>A simple hook that checks for trailing whitespace</para></caption> 13.617 - \label{ex:hook:ws.simple} 13.618 -</para> 13.619 -</informalfigure> 13.620 - 13.621 -<para>Figure <xref linkend="ex:hook:ws.simple"/> introduces a simple <literal role="hook">pretxncommit</literal> 13.622 -hook that checks for trailing whitespace. This hook is short, but not 13.623 -very helpful. It exits with an error status if a change adds a line 13.624 -with trailing whitespace to any file, but does not print any 13.625 -information that might help us to identify the offending file or 13.626 -line. It also has the nice property of not paying attention to 13.627 -unmodified lines; only lines that introduce new trailing whitespace 13.628 -cause problems. 13.629 -</para> 13.630 - 13.631 -<informalfigure> 13.632 -<para> <!-- &interaction.hook.ws.better; --> 13.633 - <caption><para>A better trailing whitespace hook</para></caption> 13.634 - \label{ex:hook:ws.better} 13.635 -</para> 13.636 -</informalfigure> 13.637 - 13.638 -<para>The example of figure <xref linkend="ex:hook:ws.better"/> is much more complex, 13.639 -but also more useful. It parses a unified diff to see if any lines 13.640 -add trailing whitespace, and prints the name of the file and the line 13.641 -number of each such occurrence. Even better, if the change adds 13.642 -trailing whitespace, this hook saves the commit comment and prints the 13.643 -name of the save file before exiting and telling Mercurial to roll the 13.644 -transaction back, so you can use 13.645 -<command role="hg-cmd">hg commit <option role="hg-opt-commit">-l</option> <emphasis>filename</emphasis></command> to reuse the 13.646 -saved commit message once you've corrected the problem. 13.647 -</para> 13.648 - 13.649 -<para>As a final aside, note in figure <xref linkend="ex:hook:ws.better"/> the use of 13.650 -<command>perl</command>'s in-place editing feature to get rid of trailing 13.651 -whitespace from a file. This is concise and useful enough that I will 13.652 -reproduce it here. 13.653 -</para> 13.654 -<programlisting> 13.655 -<para> perl -pi -e 's,\textbackslash{}s+$,,' filename 13.656 -</para> 13.657 -</programlisting> 13.658 - 13.659 -</sect2> 13.660 -</sect1> 13.661 -<sect1> 13.662 -<title>Bundled hooks</title> 13.663 - 13.664 -<para>Mercurial ships with several bundled hooks. You can find them in the 13.665 -<filename class="directory">hgext</filename> directory of a Mercurial source tree. If you are 13.666 -using a Mercurial binary package, the hooks will be located in the 13.667 -<filename class="directory">hgext</filename> directory of wherever your package installer put 13.668 -Mercurial. 13.669 -</para> 13.670 - 13.671 -<sect2> 13.672 -<title><literal role="hg-ext">acl</literal>&emdash;access control for parts of a repository</title> 13.673 - 13.674 -<para>The <literal role="hg-ext">acl</literal> extension lets you control which remote users are 13.675 -allowed to push changesets to a networked server. You can protect any 13.676 -portion of a repository (including the entire repo), so that a 13.677 -specific remote user can push changes that do not affect the protected 13.678 -portion. 13.679 -</para> 13.680 - 13.681 -<para>This extension implements access control based on the identity of the 13.682 -user performing a push, <emphasis>not</emphasis> on who committed the changesets 13.683 -they're pushing. It makes sense to use this hook only if you have a 13.684 -locked-down server environment that authenticates remote users, and 13.685 -you want to be sure that only specific users are allowed to push 13.686 -changes to that server. 13.687 -</para> 13.688 - 13.689 -<sect3> 13.690 -<title>Configuring the <literal role="hook">acl</literal> hook</title> 13.691 - 13.692 -<para>In order to manage incoming changesets, the <literal role="hg-ext">acl</literal> hook must be 13.693 -used as a <literal role="hook">pretxnchangegroup</literal> hook. This lets it see which files 13.694 -are modified by each incoming changeset, and roll back a group of 13.695 -changesets if they modify <quote>forbidden</quote> files. Example: 13.696 -</para> 13.697 -<programlisting> 13.698 -<para> [hooks] 13.699 - pretxnchangegroup.acl = python:hgext.acl.hook 13.700 -</para> 13.701 -</programlisting> 13.702 - 13.703 -<para>The <literal role="hg-ext">acl</literal> extension is configured using three sections. 13.704 -</para> 13.705 - 13.706 -<para>The <literal role="rc-acl">acl</literal> section has only one entry, <envar role="rc-item-acl">sources</envar>, 13.707 -which lists the sources of incoming changesets that the hook should 13.708 -pay attention to. You don't normally need to configure this section. 13.709 -</para> 13.710 -<itemizedlist> 13.711 -<listitem><para><envar role="rc-item-acl">serve</envar>: Control incoming changesets that are arriving 13.712 - from a remote repository over http or ssh. This is the default 13.713 - value of <envar role="rc-item-acl">sources</envar>, and usually the only setting you'll 13.714 - need for this configuration item. 13.715 -</para> 13.716 -</listitem> 13.717 -<listitem><para><envar role="rc-item-acl">pull</envar>: Control incoming changesets that are 13.718 - arriving via a pull from a local repository. 13.719 -</para> 13.720 -</listitem> 13.721 -<listitem><para><envar role="rc-item-acl">push</envar>: Control incoming changesets that are 13.722 - arriving via a push from a local repository. 13.723 -</para> 13.724 -</listitem> 13.725 -<listitem><para><envar role="rc-item-acl">bundle</envar>: Control incoming changesets that are 13.726 - arriving from another repository via a bundle. 13.727 -</para> 13.728 -</listitem></itemizedlist> 13.729 - 13.730 -<para>The <literal role="rc-acl.allow">acl.allow</literal> section controls the users that are allowed to 13.731 -add changesets to the repository. If this section is not present, all 13.732 -users that are not explicitly denied are allowed. If this section is 13.733 -present, all users that are not explicitly allowed are denied (so an 13.734 -empty section means that all users are denied). 13.735 -</para> 13.736 - 13.737 -<para>The <literal role="rc-acl.deny">acl.deny</literal> section determines which users are denied 13.738 -from adding changesets to the repository. If this section is not 13.739 -present or is empty, no users are denied. 13.740 -</para> 13.741 - 13.742 -<para>The syntaxes for the <literal role="rc-acl.allow">acl.allow</literal> and <literal role="rc-acl.deny">acl.deny</literal> 13.743 -sections are identical. On the left of each entry is a glob pattern 13.744 -that matches files or directories, relative to the root of the 13.745 -repository; on the right, a user name. 13.746 -</para> 13.747 - 13.748 -<para>In the following example, the user <literal>docwriter</literal> can only push 13.749 -changes to the <filename class="directory">docs</filename> subtree of the repository, while 13.750 -<literal>intern</literal> can push changes to any file or directory except 13.751 -<filename class="directory">source/sensitive</filename>. 13.752 -</para> 13.753 -<programlisting> 13.754 -<para> [acl.allow] 13.755 - docs/** = docwriter 13.756 -</para> 13.757 - 13.758 -<para> [acl.deny] 13.759 - source/sensitive/** = intern 13.760 -</para> 13.761 -</programlisting> 13.762 - 13.763 -</sect3> 13.764 -<sect3> 13.765 -<title>Testing and troubleshooting</title> 13.766 - 13.767 -<para>If you want to test the <literal role="hg-ext">acl</literal> hook, run it with Mercurial's 13.768 -debugging output enabled. Since you'll probably be running it on a 13.769 -server where it's not convenient (or sometimes possible) to pass in 13.770 -the <option role="hg-opt-global">--debug</option> option, don't forget that you can enable 13.771 -debugging output in your <filename role="special"> /.hgrc</filename>: 13.772 -</para> 13.773 -<programlisting> 13.774 -<para> [ui] 13.775 - debug = true 13.776 -</para> 13.777 -</programlisting> 13.778 -<para>With this enabled, the <literal role="hg-ext">acl</literal> hook will print enough information 13.779 -to let you figure out why it is allowing or forbidding pushes from 13.780 -specific users. 13.781 -</para> 13.782 - 13.783 -</sect3> 13.784 -</sect2> 13.785 -<sect2> 13.786 -<title><literal role="hg-ext">bugzilla</literal>&emdash;integration with Bugzilla</title> 13.787 - 13.788 -<para>The <literal role="hg-ext">bugzilla</literal> extension adds a comment to a Bugzilla bug 13.789 -whenever it finds a reference to that bug ID in a commit comment. You 13.790 -can install this hook on a shared server, so that any time a remote 13.791 -user pushes changes to this server, the hook gets run. 13.792 -</para> 13.793 - 13.794 -<para>It adds a comment to the bug that looks like this (you can configure 13.795 -the contents of the comment&emdash;see below): 13.796 -</para> 13.797 -<programlisting> 13.798 -<para> Changeset aad8b264143a, made by Joe User <joe.user@domain.com> in 13.799 - the frobnitz repository, refers to this bug. 13.800 -</para> 13.801 - 13.802 -<para> For complete details, see 13.803 - http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 13.804 -</para> 13.805 - 13.806 -<para> Changeset description: 13.807 - Fix bug 10483 by guarding against some NULL pointers 13.808 -</para> 13.809 -</programlisting> 13.810 -<para>The value of this hook is that it automates the process of updating a 13.811 -bug any time a changeset refers to it. If you configure the hook 13.812 -properly, it makes it easy for people to browse straight from a 13.813 -Bugzilla bug to a changeset that refers to that bug. 13.814 -</para> 13.815 - 13.816 -<para>You can use the code in this hook as a starting point for some more 13.817 -exotic Bugzilla integration recipes. Here are a few possibilities: 13.818 -</para> 13.819 -<itemizedlist> 13.820 -<listitem><para>Require that every changeset pushed to the server have a valid 13.821 - bug ID in its commit comment. In this case, you'd want to configure 13.822 - the hook as a <literal role="hook">pretxncommit</literal> hook. This would allow the hook 13.823 - to reject changes that didn't contain bug IDs. 13.824 -</para> 13.825 -</listitem> 13.826 -<listitem><para>Allow incoming changesets to automatically modify the 13.827 - <emphasis>state</emphasis> of a bug, as well as simply adding a comment. For 13.828 - example, the hook could recognise the string <quote>fixed bug 31337</quote> as 13.829 - indicating that it should update the state of bug 31337 to 13.830 - <quote>requires testing</quote>. 13.831 -</para> 13.832 -</listitem></itemizedlist> 13.833 - 13.834 -<sect3> 13.835 -<title>Configuring the <literal role="hook">bugzilla</literal> hook</title> 13.836 -<para>\label{sec:hook:bugzilla:config} 13.837 -</para> 13.838 - 13.839 -<para>You should configure this hook in your server's <filename role="special"> /.hgrc</filename>\ as an 13.840 -<literal role="hook">incoming</literal> hook, for example as follows: 13.841 -</para> 13.842 -<programlisting> 13.843 -<para> [hooks] 13.844 - incoming.bugzilla = python:hgext.bugzilla.hook 13.845 -</para> 13.846 -</programlisting> 13.847 - 13.848 -<para>Because of the specialised nature of this hook, and because Bugzilla 13.849 -was not written with this kind of integration in mind, configuring 13.850 -this hook is a somewhat involved process. 13.851 -</para> 13.852 - 13.853 -<para>Before you begin, you must install the MySQL bindings for Python on 13.854 -the host(s) where you'll be running the hook. If this is not 13.855 -available as a binary package for your system, you can download it 13.856 -from <citation>web:mysql-python</citation>. 13.857 -</para> 13.858 - 13.859 -<para>Configuration information for this hook lives in the 13.860 -<literal role="rc-bugzilla">bugzilla</literal> section of your <filename role="special"> /.hgrc</filename>. 13.861 -</para> 13.862 -<itemizedlist> 13.863 -<listitem><para><envar role="rc-item-bugzilla">version</envar>: The version of Bugzilla installed on 13.864 - the server. The database schema that Bugzilla uses changes 13.865 - occasionally, so this hook has to know exactly which schema to use. 13.866 - At the moment, the only version supported is <literal>2.16</literal>. 13.867 -</para> 13.868 -</listitem> 13.869 -<listitem><para><envar role="rc-item-bugzilla">host</envar>: The hostname of the MySQL server that 13.870 - stores your Bugzilla data. The database must be configured to allow 13.871 - connections from whatever host you are running the <literal role="hook">bugzilla</literal> 13.872 - hook on. 13.873 -</para> 13.874 -</listitem> 13.875 -<listitem><para><envar role="rc-item-bugzilla">user</envar>: The username with which to connect to 13.876 - the MySQL server. The database must be configured to allow this 13.877 - user to connect from whatever host you are running the 13.878 - <literal role="hook">bugzilla</literal> hook on. This user must be able to access and 13.879 - modify Bugzilla tables. The default value of this item is 13.880 - <literal>bugs</literal>, which is the standard name of the Bugzilla user in a 13.881 - MySQL database. 13.882 -</para> 13.883 -</listitem> 13.884 -<listitem><para><envar role="rc-item-bugzilla">password</envar>: The MySQL password for the user you 13.885 - configured above. This is stored as plain text, so you should make 13.886 - sure that unauthorised users cannot read the <filename role="special"> /.hgrc</filename>\ file where you 13.887 - store this information. 13.888 -</para> 13.889 -</listitem> 13.890 -<listitem><para><envar role="rc-item-bugzilla">db</envar>: The name of the Bugzilla database on the 13.891 - MySQL server. The default value of this item is <literal>bugs</literal>, 13.892 - which is the standard name of the MySQL database where Bugzilla 13.893 - stores its data. 13.894 -</para> 13.895 -</listitem> 13.896 -<listitem><para><envar role="rc-item-bugzilla">notify</envar>: If you want Bugzilla to send out a 13.897 - notification email to subscribers after this hook has added a 13.898 - comment to a bug, you will need this hook to run a command whenever 13.899 - it updates the database. The command to run depends on where you 13.900 - have installed Bugzilla, but it will typically look something like 13.901 - this, if you have Bugzilla installed in 13.902 - <filename class="directory">/var/www/html/bugzilla</filename>: 13.903 -</para> 13.904 -</listitem><programlisting> 13.905 -<listitem><para> cd /var/www/html/bugzilla && ./processmail %s nobody@nowhere.com 13.906 -</para> 13.907 -</listitem></programlisting> 13.908 -<listitem><para> The Bugzilla <literal>processmail</literal> program expects to be given a 13.909 - bug ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID) and an 13.910 - email address. It also expects to be able to write to some files in 13.911 - the directory that it runs in. If Bugzilla and this hook are not 13.912 - installed on the same machine, you will need to find a way to run 13.913 - <literal>processmail</literal> on the server where Bugzilla is installed. 13.914 -</para> 13.915 -</listitem></itemizedlist> 13.916 - 13.917 -</sect3> 13.918 -<sect3> 13.919 -<title>Mapping committer names to Bugzilla user names</title> 13.920 - 13.921 -<para>By default, the <literal role="hg-ext">bugzilla</literal> hook tries to use the email address 13.922 -of a changeset's committer as the Bugzilla user name with which to 13.923 -update a bug. If this does not suit your needs, you can map committer 13.924 -email addresses to Bugzilla user names using a <literal role="rc-usermap">usermap</literal> 13.925 -section. 13.926 -</para> 13.927 - 13.928 -<para>Each item in the <literal role="rc-usermap">usermap</literal> section contains an email address 13.929 -on the left, and a Bugzilla user name on the right. 13.930 -</para> 13.931 -<programlisting> 13.932 -<para> [usermap] 13.933 - jane.user@example.com = jane 13.934 -</para> 13.935 -</programlisting> 13.936 -<para>You can either keep the <literal role="rc-usermap">usermap</literal> data in a normal <filename role="special"> /.hgrc</filename>, or 13.937 -tell the <literal role="hg-ext">bugzilla</literal> hook to read the information from an 13.938 -external <filename>usermap</filename> file. In the latter case, you can store 13.939 -<filename>usermap</filename> data by itself in (for example) a user-modifiable 13.940 -repository. This makes it possible to let your users maintain their 13.941 -own <envar role="rc-item-bugzilla">usermap</envar> entries. The main <filename role="special"> /.hgrc</filename>\ file might 13.942 -look like this: 13.943 -</para> 13.944 -<programlisting> 13.945 -<para> # regular hgrc file refers to external usermap file 13.946 - [bugzilla] 13.947 - usermap = /home/hg/repos/userdata/bugzilla-usermap.conf 13.948 -</para> 13.949 -</programlisting> 13.950 -<para>While the <filename>usermap</filename> file that it refers to might look like 13.951 -this: 13.952 -</para> 13.953 -<programlisting> 13.954 -<para> # bugzilla-usermap.conf - inside a hg repository 13.955 - [usermap] 13.956 - stephanie@example.com = steph 13.957 -</para> 13.958 -</programlisting> 13.959 - 13.960 -</sect3> 13.961 -<sect3> 13.962 -<title>Configuring the text that gets added to a bug</title> 13.963 - 13.964 -<para>You can configure the text that this hook adds as a comment; you 13.965 -specify it in the form of a Mercurial template. Several <filename role="special"> /.hgrc</filename>\ 13.966 -entries (still in the <literal role="rc-bugzilla">bugzilla</literal> section) control this 13.967 -behaviour. 13.968 -</para> 13.969 -<itemizedlist> 13.970 -<listitem><para><literal>strip</literal>: The number of leading path elements to strip 13.971 - from a repository's path name to construct a partial path for a URL. 13.972 - For example, if the repositories on your server live under 13.973 - <filename class="directory">/home/hg/repos</filename>, and you have a repository whose path is 13.974 - <filename class="directory">/home/hg/repos/app/tests</filename>, then setting <literal>strip</literal> to 13.975 - <literal>4</literal> will give a partial path of <filename class="directory">app/tests</filename>. The 13.976 - hook will make this partial path available when expanding a 13.977 - template, as <literal>webroot</literal>. 13.978 -</para> 13.979 -</listitem> 13.980 -<listitem><para><literal>template</literal>: The text of the template to use. In addition 13.981 - to the usual changeset-related variables, this template can use 13.982 - <literal>hgweb</literal> (the value of the <literal>hgweb</literal> configuration item 13.983 - above) and <literal>webroot</literal> (the path constructed using 13.984 - <literal>strip</literal> above). 13.985 -</para> 13.986 -</listitem></itemizedlist> 13.987 - 13.988 -<para>In addition, you can add a <envar role="rc-item-web">baseurl</envar> item to the 13.989 -<literal role="rc-web">web</literal> section of your <filename role="special"> /.hgrc</filename>. The <literal role="hg-ext">bugzilla</literal> hook will 13.990 -make this available when expanding a template, as the base string to 13.991 -use when constructing a URL that will let users browse from a Bugzilla 13.992 -comment to view a changeset. Example: 13.993 -</para> 13.994 -<programlisting> 13.995 -<para> [web] 13.996 - baseurl = http://hg.domain.com/ 13.997 -</para> 13.998 -</programlisting> 13.999 - 13.1000 -<para>Here is an example set of <literal role="hg-ext">bugzilla</literal> hook config information. 13.1001 -</para> 13.1002 -<programlisting> 13.1003 -<para> [bugzilla] 13.1004 - host = bugzilla.example.com 13.1005 - password = mypassword 13.1006 - version = 2.16 13.1007 - # server-side repos live in /home/hg/repos, so strip 4 leading 13.1008 - # separators 13.1009 - strip = 4 13.1010 - hgweb = http://hg.example.com/ 13.1011 - usermap = /home/hg/repos/notify/bugzilla.conf 13.1012 - template = Changeset {node|short}, made by {author} in the {webroot} 13.1013 - repo, refers to this bug.\\nFor complete details, see 13.1014 - {hgweb}{webroot}?cmd=changeset;node={node|short}\\nChangeset 13.1015 - description:\\n\\t{desc|tabindent} 13.1016 -</para> 13.1017 -</programlisting> 13.1018 - 13.1019 -</sect3> 13.1020 -<sect3> 13.1021 -<title>Testing and troubleshooting</title> 13.1022 - 13.1023 -<para>The most common problems with configuring the <literal role="hg-ext">bugzilla</literal> hook 13.1024 -relate to running Bugzilla's <filename>processmail</filename> script and mapping 13.1025 -committer names to user names. 13.1026 -</para> 13.1027 - 13.1028 -<para>Recall from section <xref linkend="sec:hook:bugzilla:config"/> above that the user 13.1029 -that runs the Mercurial process on the server is also the one that 13.1030 -will run the <filename>processmail</filename> script. The 13.1031 -<filename>processmail</filename> script sometimes causes Bugzilla to write to 13.1032 -files in its configuration directory, and Bugzilla's configuration 13.1033 -files are usually owned by the user that your web server runs under. 13.1034 -</para> 13.1035 - 13.1036 -<para>You can cause <filename>processmail</filename> to be run with the suitable 13.1037 -user's identity using the <command>sudo</command> command. Here is an example 13.1038 -entry for a <filename>sudoers</filename> file. 13.1039 -</para> 13.1040 -<programlisting> 13.1041 -<para> hg_user = (httpd_user) NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s 13.1042 -</para> 13.1043 -</programlisting> 13.1044 -<para>This allows the <literal>hg_user</literal> user to run a 13.1045 -<filename>processmail-wrapper</filename> program under the identity of 13.1046 -<literal>httpd_user</literal>. 13.1047 -</para> 13.1048 - 13.1049 -<para>This indirection through a wrapper script is necessary, because 13.1050 -<filename>processmail</filename> expects to be run with its current directory 13.1051 -set to wherever you installed Bugzilla; you can't specify that kind of 13.1052 -constraint in a <filename>sudoers</filename> file. The contents of the wrapper 13.1053 -script are simple: 13.1054 -</para> 13.1055 -<programlisting> 13.1056 -<para> #!/bin/sh 13.1057 - cd `dirname $0` && ./processmail "$1" nobody@example.com 13.1058 -</para> 13.1059 -</programlisting> 13.1060 -<para>It doesn't seem to matter what email address you pass to 13.1061 -<filename>processmail</filename>. 13.1062 -</para> 13.1063 - 13.1064 -<para>If your <literal role="rc-usermap">usermap</literal> is not set up correctly, users will see an 13.1065 -error message from the <literal role="hg-ext">bugzilla</literal> hook when they push changes 13.1066 -to the server. The error message will look like this: 13.1067 -</para> 13.1068 -<programlisting> 13.1069 -<para> cannot find bugzilla user id for john.q.public@example.com 13.1070 -</para> 13.1071 -</programlisting> 13.1072 -<para>What this means is that the committer's address, 13.1073 -<literal>john.q.public@example.com</literal>, is not a valid Bugzilla user name, 13.1074 -nor does it have an entry in your <literal role="rc-usermap">usermap</literal> that maps it to 13.1075 -a valid Bugzilla user name. 13.1076 -</para> 13.1077 - 13.1078 -</sect3> 13.1079 -</sect2> 13.1080 -<sect2> 13.1081 -<title><literal role="hg-ext">notify</literal>&emdash;send email notifications</title> 13.1082 - 13.1083 -<para>Although Mercurial's built-in web server provides RSS feeds of changes 13.1084 -in every repository, many people prefer to receive change 13.1085 -notifications via email. The <literal role="hg-ext">notify</literal> hook lets you send out 13.1086 -notifications to a set of email addresses whenever changesets arrive 13.1087 -that those subscribers are interested in. 13.1088 -</para> 13.1089 - 13.1090 -<para>As with the <literal role="hg-ext">bugzilla</literal> hook, the <literal role="hg-ext">notify</literal> hook is 13.1091 -template-driven, so you can customise the contents of the notification 13.1092 -messages that it sends. 13.1093 -</para> 13.1094 - 13.1095 -<para>By default, the <literal role="hg-ext">notify</literal> hook includes a diff of every changeset 13.1096 -that it sends out; you can limit the size of the diff, or turn this 13.1097 -feature off entirely. It is useful for letting subscribers review 13.1098 -changes immediately, rather than clicking to follow a URL. 13.1099 -</para> 13.1100 - 13.1101 -<sect3> 13.1102 -<title>Configuring the <literal role="hg-ext">notify</literal> hook</title> 13.1103 - 13.1104 -<para>You can set up the <literal role="hg-ext">notify</literal> hook to send one email message per 13.1105 -incoming changeset, or one per incoming group of changesets (all those 13.1106 -that arrived in a single pull or push). 13.1107 -</para> 13.1108 -<programlisting> 13.1109 -<para> [hooks] 13.1110 - # send one email per group of changes 13.1111 - changegroup.notify = python:hgext.notify.hook 13.1112 - # send one email per change 13.1113 - incoming.notify = python:hgext.notify.hook 13.1114 -</para> 13.1115 -</programlisting> 13.1116 - 13.1117 -<para>Configuration information for this hook lives in the 13.1118 -<literal role="rc-notify">notify</literal> section of a <filename role="special"> /.hgrc</filename>\ file. 13.1119 -</para> 13.1120 -<itemizedlist> 13.1121 -<listitem><para><envar role="rc-item-notify">test</envar>: By default, this hook does not send out 13.1122 - email at all; instead, it prints the message that it <emphasis>would</emphasis> 13.1123 - send. Set this item to <literal>false</literal> to allow email to be sent. 13.1124 - The reason that sending of email is turned off by default is that it 13.1125 - takes several tries to configure this extension exactly as you would 13.1126 - like, and it would be bad form to spam subscribers with a number of 13.1127 - <quote>broken</quote> notifications while you debug your configuration. 13.1128 -</para> 13.1129 -</listitem> 13.1130 -<listitem><para><envar role="rc-item-notify">config</envar>: The path to a configuration file that 13.1131 - contains subscription information. This is kept separate from the 13.1132 - main <filename role="special"> /.hgrc</filename>\ so that you can maintain it in a repository of its own. 13.1133 - People can then clone that repository, update their subscriptions, 13.1134 - and push the changes back to your server. 13.1135 -</para> 13.1136 -</listitem> 13.1137 -<listitem><para><envar role="rc-item-notify">strip</envar>: The number of leading path separator 13.1138 - characters to strip from a repository's path, when deciding whether 13.1139 - a repository has subscribers. For example, if the repositories on 13.1140 - your server live in <filename class="directory">/home/hg/repos</filename>, and <literal role="hg-ext">notify</literal> is 13.1141 - considering a repository named <filename class="directory">/home/hg/repos/shared/test</filename>, 13.1142 - setting <envar role="rc-item-notify">strip</envar> to <literal>4</literal> will cause 13.1143 - <literal role="hg-ext">notify</literal> to trim the path it considers down to 13.1144 - <filename class="directory">shared/test</filename>, and it will match subscribers against that. 13.1145 -</para> 13.1146 -</listitem> 13.1147 -<listitem><para><envar role="rc-item-notify">template</envar>: The template text to use when sending 13.1148 - messages. This specifies both the contents of the message header 13.1149 - and its body. 13.1150 -</para> 13.1151 -</listitem> 13.1152 -<listitem><para><envar role="rc-item-notify">maxdiff</envar>: The maximum number of lines of diff 13.1153 - data to append to the end of a message. If a diff is longer than 13.1154 - this, it is truncated. By default, this is set to 300. Set this to 13.1155 - <literal>0</literal> to omit diffs from notification emails. 13.1156 -</para> 13.1157 -</listitem> 13.1158 -<listitem><para><envar role="rc-item-notify">sources</envar>: A list of sources of changesets to 13.1159 - consider. This lets you limit <literal role="hg-ext">notify</literal> to only sending out 13.1160 - email about changes that remote users pushed into this repository 13.1161 - via a server, for example. See section <xref linkend="sec:hook:sources"/> for 13.1162 - the sources you can specify here. 13.1163 -</para> 13.1164 -</listitem></itemizedlist> 13.1165 - 13.1166 -<para>If you set the <envar role="rc-item-web">baseurl</envar> item in the <literal role="rc-web">web</literal> 13.1167 -section, you can use it in a template; it will be available as 13.1168 -<literal>webroot</literal>. 13.1169 -</para> 13.1170 - 13.1171 -<para>Here is an example set of <literal role="hg-ext">notify</literal> configuration information. 13.1172 -</para> 13.1173 -<programlisting> 13.1174 -<para> [notify] 13.1175 - # really send email 13.1176 - test = false 13.1177 - # subscriber data lives in the notify repo 13.1178 - config = /home/hg/repos/notify/notify.conf 13.1179 - # repos live in /home/hg/repos on server, so strip 4 "/" chars 13.1180 - strip = 4 13.1181 - template = X-Hg-Repo: {webroot} 13.1182 - Subject: {webroot}: {desc|firstline|strip} 13.1183 - From: {author} 13.1184 -</para> 13.1185 - 13.1186 -<para> changeset {node|short} in {root} 13.1187 - details: {baseurl}{webroot}?cmd=changeset;node={node|short} 13.1188 - description: 13.1189 - {desc|tabindent|strip} 13.1190 -</para> 13.1191 - 13.1192 -<para> [web] 13.1193 - baseurl = http://hg.example.com/ 13.1194 -</para> 13.1195 -</programlisting> 13.1196 - 13.1197 -<para>This will produce a message that looks like the following: 13.1198 -</para> 13.1199 -<programlisting> 13.1200 -<para> X-Hg-Repo: tests/slave 13.1201 - Subject: tests/slave: Handle error case when slave has no buffers 13.1202 - Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT) 13.1203 -</para> 13.1204 - 13.1205 -<para> changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave 13.1206 - details: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 13.1207 - description: 13.1208 - Handle error case when slave has no buffers 13.1209 - diffs (54 lines): 13.1210 -</para> 13.1211 - 13.1212 -<para> diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h 13.1213 - &emdash; a/include/tests.h Wed Aug 02 15:19:52 2006 -0700 13.1214 - +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700 13.1215 - @@ -212,6 +212,15 @@ static __inline__ void test_headers(void *h) 13.1216 - [...snip...] 13.1217 -</para> 13.1218 -</programlisting> 13.1219 - 13.1220 -</sect3> 13.1221 -<sect3> 13.1222 -<title>Testing and troubleshooting</title> 13.1223 - 13.1224 -<para>Do not forget that by default, the <literal role="hg-ext">notify</literal> extension \emph{will 13.1225 - not send any mail} until you explicitly configure it to do so, by 13.1226 -setting <envar role="rc-item-notify">test</envar> to <literal>false</literal>. Until you do that, 13.1227 -it simply prints the message it <emphasis>would</emphasis> send. 13.1228 -</para> 13.1229 - 13.1230 -</sect3> 13.1231 -</sect2> 13.1232 -</sect1> 13.1233 -<sect1> 13.1234 -<title>Information for writers of hooks</title> 13.1235 -<para>\label{sec:hook:ref} 13.1236 -</para> 13.1237 - 13.1238 -<sect2> 13.1239 -<title>In-process hook execution</title> 13.1240 - 13.1241 -<para>An in-process hook is called with arguments of the following form: 13.1242 -</para> 13.1243 -<programlisting> 13.1244 -<para> def myhook(ui, repo, **kwargs): 13.1245 - pass 13.1246 -</para> 13.1247 -</programlisting> 13.1248 -<para>The <literal>ui</literal> parameter is a <literal role="py-mod-mercurial.ui">ui</literal> object. 13.1249 -The <literal>repo</literal> parameter is a 13.1250 -<literal role="py-mod-mercurial.localrepo">localrepository</literal> object. The 13.1251 -names and values of the <literal>**kwargs</literal> parameters depend on the 13.1252 -hook being invoked, with the following common features: 13.1253 -</para> 13.1254 -<itemizedlist> 13.1255 -<listitem><para>If a parameter is named <literal>node</literal> or 13.1256 - <literal>parent<emphasis>N</emphasis></literal>, it will contain a hexadecimal changeset ID. 13.1257 - The empty string is used to represent <quote>null changeset ID</quote> instead 13.1258 - of a string of zeroes. 13.1259 -</para> 13.1260 -</listitem> 13.1261 -<listitem><para>If a parameter is named <literal>url</literal>, it will contain the URL of 13.1262 - a remote repository, if that can be determined. 13.1263 -</para> 13.1264 -</listitem> 13.1265 -<listitem><para>Boolean-valued parameters are represented as Python 13.1266 - <literal>bool</literal> objects. 13.1267 -</para> 13.1268 -</listitem></itemizedlist> 13.1269 - 13.1270 -<para>An in-process hook is called without a change to the process's working 13.1271 -directory (unlike external hooks, which are run in the root of the 13.1272 -repository). It must not change the process's working directory, or 13.1273 -it will cause any calls it makes into the Mercurial API to fail. 13.1274 -</para> 13.1275 - 13.1276 -<para>If a hook returns a boolean <quote>false</quote> value, it is considered to have 13.1277 -succeeded. If it returns a boolean <quote>true</quote> value or raises an 13.1278 -exception, it is considered to have failed. A useful way to think of 13.1279 -the calling convention is <quote>tell me if you fail</quote>. 13.1280 -</para> 13.1281 - 13.1282 -<para>Note that changeset IDs are passed into Python hooks as hexadecimal 13.1283 -strings, not the binary hashes that Mercurial's APIs normally use. To 13.1284 -convert a hash from hex to binary, use the 13.1285 -\pymodfunc{mercurial.node}{bin} function. 13.1286 -</para> 13.1287 - 13.1288 -</sect2> 13.1289 -<sect2> 13.1290 -<title>External hook execution</title> 13.1291 - 13.1292 -<para>An external hook is passed to the shell of the user running Mercurial. 13.1293 -Features of that shell, such as variable substitution and command 13.1294 -redirection, are available. The hook is run in the root directory of 13.1295 -the repository (unlike in-process hooks, which are run in the same 13.1296 -directory that Mercurial was run in). 13.1297 -</para> 13.1298 - 13.1299 -<para>Hook parameters are passed to the hook as environment variables. Each 13.1300 -environment variable's name is converted in upper case and prefixed 13.1301 -with the string <quote><literal>HG_</literal></quote>. For example, if the name of a 13.1302 -parameter is <quote><literal>node</literal></quote>, the name of the environment variable 13.1303 -representing that parameter will be <quote><literal>HG_NODE</literal></quote>. 13.1304 -</para> 13.1305 - 13.1306 -<para>A boolean parameter is represented as the string <quote><literal>1</literal></quote> for 13.1307 -<quote>true</quote>, <quote><literal>0</literal></quote> for <quote>false</quote>. If an environment variable is 13.1308 -named <envar>HG_NODE</envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 13.1309 -contains a changeset ID represented as a hexadecimal string. The 13.1310 -empty string is used to represent <quote>null changeset ID</quote> instead of a 13.1311 -string of zeroes. If an environment variable is named 13.1312 -<envar>HG_URL</envar>, it will contain the URL of a remote repository, if 13.1313 -that can be determined. 13.1314 -</para> 13.1315 - 13.1316 -<para>If a hook exits with a status of zero, it is considered to have 13.1317 -succeeded. If it exits with a non-zero status, it is considered to 13.1318 -have failed. 13.1319 -</para> 13.1320 - 13.1321 -</sect2> 13.1322 -<sect2> 13.1323 -<title>Finding out where changesets come from</title> 13.1324 - 13.1325 -<para>A hook that involves the transfer of changesets between a local 13.1326 -repository and another may be able to find out information about the 13.1327 -<quote>far side</quote>. Mercurial knows <emphasis>how</emphasis> changes are being 13.1328 -transferred, and in many cases <emphasis>where</emphasis> they are being transferred 13.1329 -to or from. 13.1330 -</para> 13.1331 - 13.1332 -<sect3> 13.1333 -<title>Sources of changesets</title> 13.1334 -<para>\label{sec:hook:sources} 13.1335 -</para> 13.1336 - 13.1337 -<para>Mercurial will tell a hook what means are, or were, used to transfer 13.1338 -changesets between repositories. This is provided by Mercurial in a 13.1339 -Python parameter named <literal>source</literal>, or an environment variable named 13.1340 -<envar>HG_SOURCE</envar>. 13.1341 -</para> 13.1342 - 13.1343 -<itemizedlist> 13.1344 -<listitem><para><literal>serve</literal>: Changesets are transferred to or from a remote 13.1345 - repository over http or ssh. 13.1346 -</para> 13.1347 -</listitem> 13.1348 -<listitem><para><literal>pull</literal>: Changesets are being transferred via a pull from 13.1349 - one repository into another. 13.1350 -</para> 13.1351 -</listitem> 13.1352 -<listitem><para><literal>push</literal>: Changesets are being transferred via a push from 13.1353 - one repository into another. 13.1354 -</para> 13.1355 -</listitem> 13.1356 -<listitem><para><literal>bundle</literal>: Changesets are being transferred to or from a 13.1357 - bundle. 13.1358 -</para> 13.1359 -</listitem></itemizedlist> 13.1360 - 13.1361 -</sect3> 13.1362 -<sect3> 13.1363 -<title>Where changes are going&emdash;remote repository URLs</title> 13.1364 -<para>\label{sec:hook:url} 13.1365 -</para> 13.1366 - 13.1367 -<para>When possible, Mercurial will tell a hook the location of the <quote>far 13.1368 -side</quote> of an activity that transfers changeset data between 13.1369 -repositories. This is provided by Mercurial in a Python parameter 13.1370 -named <literal>url</literal>, or an environment variable named <envar>HG_URL</envar>. 13.1371 -</para> 13.1372 - 13.1373 -<para>This information is not always known. If a hook is invoked in a 13.1374 -repository that is being served via http or ssh, Mercurial cannot tell 13.1375 -where the remote repository is, but it may know where the client is 13.1376 -connecting from. In such cases, the URL will take one of the 13.1377 -following forms: 13.1378 -</para> 13.1379 -<itemizedlist> 13.1380 -<listitem><para><literal>remote:ssh:<emphasis>ip-address</emphasis></literal>&emdash;remote ssh client, at 13.1381 - the given IP address. 13.1382 -</para> 13.1383 -</listitem> 13.1384 -<listitem><para><literal>remote:http:<emphasis>ip-address</emphasis></literal>&emdash;remote http client, at 13.1385 - the given IP address. If the client is using SSL, this will be of 13.1386 - the form <literal>remote:https:<emphasis>ip-address</emphasis></literal>. 13.1387 -</para> 13.1388 -</listitem> 13.1389 -<listitem><para>Empty&emdash;no information could be discovered about the remote 13.1390 - client. 13.1391 -</para> 13.1392 -</listitem></itemizedlist> 13.1393 - 13.1394 -</sect3> 13.1395 -</sect2> 13.1396 -</sect1> 13.1397 -<sect1> 13.1398 -<title>Hook reference</title> 13.1399 - 13.1400 -<sect2> 13.1401 -<title><literal role="hook">changegroup</literal>&emdash;after remote changesets added</title> 13.1402 -<para>\label{sec:hook:changegroup} 13.1403 -</para> 13.1404 - 13.1405 -<para>This hook is run after a group of pre-existing changesets has been 13.1406 -added to the repository, for example via a <command role="hg-cmd">hg pull</command> or 13.1407 -<command role="hg-cmd">hg unbundle</command>. This hook is run once per operation that added one 13.1408 -or more changesets. This is in contrast to the <literal role="hook">incoming</literal> hook, 13.1409 -which is run once per changeset, regardless of whether the changesets 13.1410 -arrive in a group. 13.1411 -</para> 13.1412 - 13.1413 -<para>Some possible uses for this hook include kicking off an automated 13.1414 -build or test of the added changesets, updating a bug database, or 13.1415 -notifying subscribers that a repository contains new changes. 13.1416 -</para> 13.1417 - 13.1418 -<para>Parameters to this hook: 13.1419 -</para> 13.1420 -<itemizedlist> 13.1421 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 13.1422 - changeset in the group that was added. All changesets between this 13.1423 - and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by 13.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>. 13.1425 -</para> 13.1426 -</listitem> 13.1427 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 13.1428 - section <xref linkend="sec:hook:sources"/> for details. 13.1429 -</para> 13.1430 -</listitem> 13.1431 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1432 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1433 -</para> 13.1434 -</listitem></itemizedlist> 13.1435 - 13.1436 -<para>See also: <literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), 13.1437 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>), 13.1438 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>) 13.1439 -</para> 13.1440 - 13.1441 -</sect2> 13.1442 -<sect2> 13.1443 -<title><literal role="hook">commit</literal>&emdash;after a new changeset is created</title> 13.1444 -<para>\label{sec:hook:commit} 13.1445 -</para> 13.1446 - 13.1447 -<para>This hook is run after a new changeset has been created. 13.1448 -</para> 13.1449 - 13.1450 -<para>Parameters to this hook: 13.1451 -</para> 13.1452 -<itemizedlist> 13.1453 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the newly 13.1454 - committed changeset. 13.1455 -</para> 13.1456 -</listitem> 13.1457 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 13.1458 - parent of the newly committed changeset. 13.1459 -</para> 13.1460 -</listitem> 13.1461 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 13.1462 - parent of the newly committed changeset. 13.1463 -</para> 13.1464 -</listitem></itemizedlist> 13.1465 - 13.1466 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>), 13.1467 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>) 13.1468 -</para> 13.1469 - 13.1470 -</sect2> 13.1471 -<sect2> 13.1472 -<title><literal role="hook">incoming</literal>&emdash;after one remote changeset is added</title> 13.1473 -<para>\label{sec:hook:incoming} 13.1474 -</para> 13.1475 - 13.1476 -<para>This hook is run after a pre-existing changeset has been added to the 13.1477 -repository, for example via a <command role="hg-cmd">hg push</command>. If a group of changesets 13.1478 -was added in a single operation, this hook is called once for each 13.1479 -added changeset. 13.1480 -</para> 13.1481 - 13.1482 -<para>You can use this hook for the same purposes as the <literal role="hook">changegroup</literal> 13.1483 -hook (section <xref linkend="sec:hook:changegroup"/>); it's simply more convenient 13.1484 -sometimes to run a hook once per group of changesets, while other 13.1485 -times it's handier once per changeset. 13.1486 -</para> 13.1487 - 13.1488 -<para>Parameters to this hook: 13.1489 -</para> 13.1490 -<itemizedlist> 13.1491 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the newly added 13.1492 - changeset. 13.1493 -</para> 13.1494 -</listitem> 13.1495 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 13.1496 - section <xref linkend="sec:hook:sources"/> for details. 13.1497 -</para> 13.1498 -</listitem> 13.1499 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1500 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1501 -</para> 13.1502 -</listitem></itemizedlist> 13.1503 - 13.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"/>) 13.1505 -</para> 13.1506 - 13.1507 -</sect2> 13.1508 -<sect2> 13.1509 -<title><literal role="hook">outgoing</literal>&emdash;after changesets are propagated</title> 13.1510 -<para>\label{sec:hook:outgoing} 13.1511 -</para> 13.1512 - 13.1513 -<para>This hook is run after a group of changesets has been propagated out 13.1514 -of this repository, for example by a <command role="hg-cmd">hg push</command> or <command role="hg-cmd">hg bundle</command> 13.1515 -command. 13.1516 -</para> 13.1517 - 13.1518 -<para>One possible use for this hook is to notify administrators that 13.1519 -changes have been pulled. 13.1520 -</para> 13.1521 - 13.1522 -<para>Parameters to this hook: 13.1523 -</para> 13.1524 -<itemizedlist> 13.1525 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 13.1526 - changeset of the group that was sent. 13.1527 -</para> 13.1528 -</listitem> 13.1529 -<listitem><para><literal>source</literal>: A string. The source of the of the operation 13.1530 - (see section <xref linkend="sec:hook:sources"/>). If a remote client pulled 13.1531 - changes from this repository, <literal>source</literal> will be 13.1532 - <literal>serve</literal>. If the client that obtained changes from this 13.1533 - repository was local, <literal>source</literal> will be <literal>bundle</literal>, 13.1534 - <literal>pull</literal>, or <literal>push</literal>, depending on the operation the 13.1535 - client performed. 13.1536 -</para> 13.1537 -</listitem> 13.1538 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1539 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1540 -</para> 13.1541 -</listitem></itemizedlist> 13.1542 - 13.1543 -<para>See also: <literal role="hook">preoutgoing</literal> (section <xref linkend="sec:hook:preoutgoing"/>) 13.1544 -</para> 13.1545 - 13.1546 -</sect2> 13.1547 -<sect2> 13.1548 -<title><literal role="hook">prechangegroup</literal>&emdash;before starting to add remote changesets</title> 13.1549 -<para>\label{sec:hook:prechangegroup} 13.1550 -</para> 13.1551 - 13.1552 -<para>This controlling hook is run before Mercurial begins to add a group of 13.1553 -changesets from another repository. 13.1554 -</para> 13.1555 - 13.1556 -<para>This hook does not have any information about the changesets to be 13.1557 -added, because it is run before transmission of those changesets is 13.1558 -allowed to begin. If this hook fails, the changesets will not be 13.1559 -transmitted. 13.1560 -</para> 13.1561 - 13.1562 -<para>One use for this hook is to prevent external changes from being added 13.1563 -to a repository. For example, you could use this to <quote>freeze</quote> a 13.1564 -server-hosted branch temporarily or permanently so that users cannot 13.1565 -push to it, while still allowing a local administrator to modify the 13.1566 -repository. 13.1567 -</para> 13.1568 - 13.1569 -<para>Parameters to this hook: 13.1570 -</para> 13.1571 -<itemizedlist> 13.1572 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 13.1573 - section <xref linkend="sec:hook:sources"/> for details. 13.1574 -</para> 13.1575 -</listitem> 13.1576 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1577 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1578 -</para> 13.1579 -</listitem></itemizedlist> 13.1580 - 13.1581 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>), 13.1582 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), , 13.1583 -<literal role="hook">pretxnchangegroup</literal> (section <xref linkend="sec:hook:pretxnchangegroup"/>) 13.1584 -</para> 13.1585 - 13.1586 -</sect2> 13.1587 -<sect2> 13.1588 -<title><literal role="hook">precommit</literal>&emdash;before starting to commit a changeset</title> 13.1589 -<para>\label{sec:hook:precommit} 13.1590 -</para> 13.1591 - 13.1592 -<para>This hook is run before Mercurial begins to commit a new changeset. 13.1593 -It is run before Mercurial has any of the metadata for the commit, 13.1594 -such as the files to be committed, the commit message, or the commit 13.1595 -date. 13.1596 -</para> 13.1597 - 13.1598 -<para>One use for this hook is to disable the ability to commit new 13.1599 -changesets, while still allowing incoming changesets. Another is to 13.1600 -run a build or test, and only allow the commit to begin if the build 13.1601 -or test succeeds. 13.1602 -</para> 13.1603 - 13.1604 -<para>Parameters to this hook: 13.1605 -</para> 13.1606 -<itemizedlist> 13.1607 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 13.1608 - parent of the working directory. 13.1609 -</para> 13.1610 -</listitem> 13.1611 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 13.1612 - parent of the working directory. 13.1613 -</para> 13.1614 -</listitem></itemizedlist> 13.1615 -<para>If the commit proceeds, the parents of the working directory will 13.1616 -become the parents of the new changeset. 13.1617 -</para> 13.1618 - 13.1619 -<para>See also: <literal role="hook">commit</literal> (section <xref linkend="sec:hook:commit"/>), 13.1620 -<literal role="hook">pretxncommit</literal> (section <xref linkend="sec:hook:pretxncommit"/>) 13.1621 -</para> 13.1622 - 13.1623 -</sect2> 13.1624 -<sect2> 13.1625 -<title><literal role="hook">preoutgoing</literal>&emdash;before starting to propagate changesets</title> 13.1626 -<para>\label{sec:hook:preoutgoing} 13.1627 -</para> 13.1628 - 13.1629 -<para>This hook is invoked before Mercurial knows the identities of the 13.1630 -changesets to be transmitted. 13.1631 -</para> 13.1632 - 13.1633 -<para>One use for this hook is to prevent changes from being transmitted to 13.1634 -another repository. 13.1635 -</para> 13.1636 - 13.1637 -<para>Parameters to this hook: 13.1638 -</para> 13.1639 -<itemizedlist> 13.1640 -<listitem><para><literal>source</literal>: A string. The source of the operation that is 13.1641 - attempting to obtain changes from this repository (see 13.1642 - section <xref linkend="sec:hook:sources"/>). See the documentation for the 13.1643 - <literal>source</literal> parameter to the <literal role="hook">outgoing</literal> hook, in 13.1644 - section <xref linkend="sec:hook:outgoing"/>, for possible values of this 13.1645 - parameter. 13.1646 -</para> 13.1647 -</listitem> 13.1648 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1649 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1650 -</para> 13.1651 -</listitem></itemizedlist> 13.1652 - 13.1653 -<para>See also: <literal role="hook">outgoing</literal> (section <xref linkend="sec:hook:outgoing"/>) 13.1654 -</para> 13.1655 - 13.1656 -</sect2> 13.1657 -<sect2> 13.1658 -<title><literal role="hook">pretag</literal>&emdash;before tagging a changeset</title> 13.1659 -<para>\label{sec:hook:pretag} 13.1660 -</para> 13.1661 - 13.1662 -<para>This controlling hook is run before a tag is created. If the hook 13.1663 -succeeds, creation of the tag proceeds. If the hook fails, the tag is 13.1664 -not created. 13.1665 -</para> 13.1666 - 13.1667 -<para>Parameters to this hook: 13.1668 -</para> 13.1669 -<itemizedlist> 13.1670 -<listitem><para><literal>local</literal>: A boolean. Whether the tag is local to this 13.1671 - repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or 13.1672 - managed by Mercurial (stored in <filename role="special">.hgtags</filename>). 13.1673 -</para> 13.1674 -</listitem> 13.1675 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the changeset to be tagged. 13.1676 -</para> 13.1677 -</listitem> 13.1678 -<listitem><para><literal>tag</literal>: A string. The name of the tag to be created. 13.1679 -</para> 13.1680 -</listitem></itemizedlist> 13.1681 - 13.1682 -<para>If the tag to be created is revision-controlled, the <literal role="hook">precommit</literal> 13.1683 -and <literal role="hook">pretxncommit</literal> hooks (sections <xref linkend="sec:hook:commit"/> 13.1684 -and <xref linkend="sec:hook:pretxncommit"/>) will also be run. 13.1685 -</para> 13.1686 - 13.1687 -<para>See also: <literal role="hook">tag</literal> (section <xref linkend="sec:hook:tag"/>) 13.1688 -</para> 13.1689 - 13.1690 -<para>\subsection{<literal role="hook">pretxnchangegroup</literal>&emdash;before completing addition of 13.1691 - remote changesets} 13.1692 -\label{sec:hook:pretxnchangegroup} 13.1693 -</para> 13.1694 - 13.1695 -<para>This controlling hook is run before a transaction&emdash;that manages the 13.1696 -addition of a group of new changesets from outside the 13.1697 -repository&emdash;completes. If the hook succeeds, the transaction 13.1698 -completes, and all of the changesets become permanent within this 13.1699 -repository. If the hook fails, the transaction is rolled back, and 13.1700 -the data for the changesets is erased. 13.1701 -</para> 13.1702 - 13.1703 -<para>This hook can access the metadata associated with the almost-added 13.1704 -changesets, but it should not do anything permanent with this data. 13.1705 -It must also not modify the working directory. 13.1706 -</para> 13.1707 - 13.1708 -<para>While this hook is running, if other Mercurial processes access this 13.1709 -repository, they will be able to see the almost-added changesets as if 13.1710 -they are permanent. This may lead to race conditions if you do not 13.1711 -take steps to avoid them. 13.1712 -</para> 13.1713 - 13.1714 -<para>This hook can be used to automatically vet a group of changesets. If 13.1715 -the hook fails, all of the changesets are <quote>rejected</quote> when the 13.1716 -transaction rolls back. 13.1717 -</para> 13.1718 - 13.1719 -<para>Parameters to this hook: 13.1720 -</para> 13.1721 -<itemizedlist> 13.1722 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the first 13.1723 - changeset in the group that was added. All changesets between this 13.1724 - and \index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were added by 13.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>. 13.1726 -</para> 13.1727 -</listitem> 13.1728 -<listitem><para><literal>source</literal>: A string. The source of these changes. See 13.1729 - section <xref linkend="sec:hook:sources"/> for details. 13.1730 -</para> 13.1731 -</listitem> 13.1732 -<listitem><para><literal>url</literal>: A URL. The location of the remote repository, if 13.1733 - known. See section <xref linkend="sec:hook:url"/> for more information. 13.1734 -</para> 13.1735 -</listitem></itemizedlist> 13.1736 - 13.1737 -<para>See also: <literal role="hook">changegroup</literal> (section <xref linkend="sec:hook:changegroup"/>), 13.1738 -<literal role="hook">incoming</literal> (section <xref linkend="sec:hook:incoming"/>), 13.1739 -<literal role="hook">prechangegroup</literal> (section <xref linkend="sec:hook:prechangegroup"/>) 13.1740 -</para> 13.1741 - 13.1742 -</sect2> 13.1743 -<sect2> 13.1744 -<title><literal role="hook">pretxncommit</literal>&emdash;before completing commit of new changeset</title> 13.1745 -<para>\label{sec:hook:pretxncommit} 13.1746 -</para> 13.1747 - 13.1748 -<para>This controlling hook is run before a transaction&emdash;that manages a new 13.1749 -commit&emdash;completes. If the hook succeeds, the transaction completes 13.1750 -and the changeset becomes permanent within this repository. If the 13.1751 -hook fails, the transaction is rolled back, and the commit data is 13.1752 -erased. 13.1753 -</para> 13.1754 - 13.1755 -<para>This hook can access the metadata associated with the almost-new 13.1756 -changeset, but it should not do anything permanent with this data. It 13.1757 -must also not modify the working directory. 13.1758 -</para> 13.1759 - 13.1760 -<para>While this hook is running, if other Mercurial processes access this 13.1761 -repository, they will be able to see the almost-new changeset as if it 13.1762 -is permanent. This may lead to race conditions if you do not take 13.1763 -steps to avoid them. 13.1764 -</para> 13.1765 - 13.1766 -<para>Parameters to this hook: 13.1767 -</para> 13.1768 -<itemizedlist> 13.1769 -<listitem><para><literal>node</literal>: A changeset ID. The changeset ID of the newly 13.1770 - committed changeset. 13.1771 -</para> 13.1772 -</listitem> 13.1773 -<listitem><para><literal>parent1</literal>: A changeset ID. The changeset ID of the first 13.1774 - parent of the newly committed changeset. 13.1775 -</para> 13.1776 -</listitem> 13.1777 -<listitem><para><literal>parent2</literal>: A changeset ID. The changeset ID of the second 13.1778 - parent of the newly committed changeset. 13.1779 -</para> 13.1780 -</listitem></itemizedlist> 13.1781 - 13.1782 -<para>See also: <literal role="hook">precommit</literal> (section <xref linkend="sec:hook:precommit"/>) 13.1783 -</para> 13.1784 - 13.1785 -</sect2> 13.1786 -<sect2> 13.1787 -<title><literal role="hook">preupdate</literal>&emdash;before updating or merging working directory</title> 13.1788 -<para>\label{sec:hook:preupdate} 13.1789 -</para> 13.1790 - 13.1791 -<para>This controlling hook is run before an update or merge of the working 13.1792 -directory begins. It is run only if Mercurial's normal pre-update 13.1793 -checks determine that the update or merge can proceed. If the hook 13.1794 -succeeds, the update or merge may proceed; if it fails, the update or 13.1795 -merge does not start. 13.1796 -</para> 13.1797 - 13.1798 -<para>Parameters to this hook: 13.1799 -</para> 13.1800 -<itemizedlist> 13.1801 -<listitem><para><literal>parent1</literal>: A changeset ID. The ID of the parent that the 13.1802 - working directory is to be updated to. If the working directory is 13.1803 - being merged, it will not change this parent. 13.1804 -</para> 13.1805 -</listitem> 13.1806 -<listitem><para><literal>parent2</literal>: A changeset ID. Only set if the working 13.1807 - directory is being merged. The ID of the revision that the working 13.1808 - directory is being merged with. 13.1809 -</para> 13.1810 -</listitem></itemizedlist> 13.1811 - 13.1812 -<para>See also: <literal role="hook">update</literal> (section <xref linkend="sec:hook:update"/>) 13.1813 -</para> 13.1814 - 13.1815 -</sect2> 13.1816 -<sect2> 13.1817 -<title><literal role="hook">tag</literal>&emdash;after tagging a changeset</title> 13.1818 -<para>\label{sec:hook:tag} 13.1819 -</para> 13.1820 - 13.1821 -<para>This hook is run after a tag has been created. 13.1822 -</para> 13.1823 - 13.1824 -<para>Parameters to this hook: 13.1825 -</para> 13.1826 -<itemizedlist> 13.1827 -<listitem><para><literal>local</literal>: A boolean. Whether the new tag is local to this 13.1828 - repository instance (i.e. stored in <filename role="special">.hg/localtags</filename>) or 13.1829 - managed by Mercurial (stored in <filename role="special">.hgtags</filename>). 13.1830 -</para> 13.1831 -</listitem> 13.1832 -<listitem><para><literal>node</literal>: A changeset ID. The ID of the changeset that was 13.1833 - tagged. 13.1834 -</para> 13.1835 -</listitem> 13.1836 -<listitem><para><literal>tag</literal>: A string. The name of the tag that was created. 13.1837 -</para> 13.1838 -</listitem></itemizedlist> 13.1839 - 13.1840 -<para>If the created tag is revision-controlled, the <literal role="hook">commit</literal> hook 13.1841 -(section <xref linkend="sec:hook:commit"/>) is run before this hook. 13.1842 -</para> 13.1843 - 13.1844 -<para>See also: <literal role="hook">pretag</literal> (section <xref linkend="sec:hook:pretag"/>) 13.1845 -</para> 13.1846 - 13.1847 -</sect2> 13.1848 -<sect2> 13.1849 -<title><literal role="hook">update</literal>&emdash;after updating or merging working directory</title> 13.1850 -<para>\label{sec:hook:update} 13.1851 -</para> 13.1852 - 13.1853 -<para>This hook is run after an update or merge of the working directory 13.1854 -completes. Since a merge can fail (if the external <command>hgmerge</command> 13.1855 -command fails to resolve conflicts in a file), this hook communicates 13.1856 -whether the update or merge completed cleanly. 13.1857 -</para> 13.1858 - 13.1859 -<itemizedlist> 13.1860 -<listitem><para><literal>error</literal>: A boolean. Indicates whether the update or 13.1861 - merge completed successfully. 13.1862 -</para> 13.1863 -</listitem> 13.1864 -<listitem><para><literal>parent1</literal>: A changeset ID. The ID of the parent that the 13.1865 - working directory was updated to. If the working directory was 13.1866 - merged, it will not have changed this parent. 13.1867 -</para> 13.1868 -</listitem> 13.1869 -<listitem><para><literal>parent2</literal>: A changeset ID. Only set if the working 13.1870 - directory was merged. The ID of the revision that the working 13.1871 - directory was merged with. 13.1872 -</para> 13.1873 -</listitem></itemizedlist> 13.1874 - 13.1875 -<para>See also: <literal role="hook">preupdate</literal> (section <xref linkend="sec:hook:preupdate"/>) 13.1876 -</para> 13.1877 - 13.1878 -</sect2> 13.1879 -</sect1> 13.1880 +<chapter id="chap:hook"> 13.1881 + <?dbhtml filename="handling-repository-events-with-hooks.html"?> 13.1882 + <title>Handling repository events with hooks</title> 13.1883 + 13.1884 + <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform 13.1885 + automated actions in response to events that occur in a 13.1886 + repository. In some cases, you can even control Mercurial's 13.1887 + response to those events.</para> 13.1888 + 13.1889 + <para id="x_1e7">The name Mercurial uses for one of these actions is a 13.1890 + <emphasis>hook</emphasis>. Hooks are called 13.1891 + <quote>triggers</quote> in some revision control systems, but the 13.1892 + two names refer to the same idea.</para> 13.1893 + 13.1894 + <sect1> 13.1895 + <title>An overview of hooks in Mercurial</title> 13.1896 + 13.1897 + <para id="x_1e8">Here is a brief list of the hooks that Mercurial 13.1898 + supports. We will revisit each of these hooks in more detail 13.1899 + later, in <xref linkend="sec:hook:ref"/>.</para> 13.1900 + 13.1901 + <para id="x_1f6">Each of the hooks whose description begins with the word 13.1902 + <quote>Controlling</quote> has the ability to determine whether 13.1903 + an activity can proceed. If the hook succeeds, the activity may 13.1904 + proceed; if it fails, the activity is either not permitted or 13.1905 + undone, depending on the hook.</para> 13.1906 + 13.1907 + <itemizedlist> 13.1908 + <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This 13.1909 + is run after a group of changesets has been brought into the 13.1910 + repository from elsewhere.</para> 13.1911 + </listitem> 13.1912 + <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is 13.1913 + run after a new changeset has been created in the local 13.1914 + repository.</para> 13.1915 + </listitem> 13.1916 + <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is 13.1917 + run once for each new changeset that is brought into the 13.1918 + repository from elsewhere. Notice the difference from 13.1919 + <literal role="hook">changegroup</literal>, which is run 13.1920 + once per <emphasis>group</emphasis> of changesets brought 13.1921 + in.</para> 13.1922 + </listitem> 13.1923 + <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is 13.1924 + run after a group of changesets has been transmitted from 13.1925 + this repository.</para> 13.1926 + </listitem> 13.1927 + <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: 13.1928 + This is run before starting to bring a group of changesets 13.1929 + into the repository. 13.1930 + </para> 13.1931 + </listitem> 13.1932 + <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: 13.1933 + Controlling. This is run before starting a commit. 13.1934 + </para> 13.1935 + </listitem> 13.1936 + <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: 13.1937 + Controlling. This is run before starting to transmit a group 13.1938 + of changesets from this repository. 13.1939 + </para> 13.1940 + </listitem> 13.1941 + <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: 13.1942 + Controlling. This is run before creating a tag. 13.1943 + </para> 13.1944 + </listitem> 13.1945 + <listitem><para id="x_1f1"><literal 13.1946 + role="hook">pretxnchangegroup</literal>: Controlling. This 13.1947 + is run after a group of changesets has been brought into the 13.1948 + local repository from another, but before the transaction 13.1949 + completes that will make the changes permanent in the 13.1950 + repository. 13.1951 + </para> 13.1952 + </listitem> 13.1953 + <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: 13.1954 + Controlling. This is run after a new changeset has been 13.1955 + created in the local repository, but before the transaction 13.1956 + completes that will make it permanent. 13.1957 + </para> 13.1958 + </listitem> 13.1959 + <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: 13.1960 + Controlling. This is run before starting an update or merge 13.1961 + of the working directory. 13.1962 + </para> 13.1963 + </listitem> 13.1964 + <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run 13.1965 + after a tag is created. 13.1966 + </para> 13.1967 + </listitem> 13.1968 + <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is 13.1969 + run after an update or merge of the working directory has 13.1970 + finished. 13.1971 + </para> 13.1972 + </listitem></itemizedlist> 13.1973 + 13.1974 + </sect1> 13.1975 + <sect1> 13.1976 + <title>Hooks and security</title> 13.1977 + 13.1978 + <sect2> 13.1979 + <title>Hooks are run with your privileges</title> 13.1980 + 13.1981 + <para id="x_1f7">When you run a Mercurial command in a repository, and the 13.1982 + command causes a hook to run, that hook runs on 13.1983 + <emphasis>your</emphasis> system, under 13.1984 + <emphasis>your</emphasis> user account, with 13.1985 + <emphasis>your</emphasis> privilege level. Since hooks are 13.1986 + arbitrary pieces of executable code, you should treat them 13.1987 + with an appropriate level of suspicion. Do not install a hook 13.1988 + unless you are confident that you know who created it and what 13.1989 + it does. 13.1990 + </para> 13.1991 + 13.1992 + <para id="x_1f8">In some cases, you may be exposed to hooks that you did 13.1993 + not install yourself. If you work with Mercurial on an 13.1994 + unfamiliar system, Mercurial will run hooks defined in that 13.1995 + system's global <filename role="special">~/.hgrc</filename> 13.1996 + file. 13.1997 + </para> 13.1998 + 13.1999 + <para id="x_1f9">If you are working with a repository owned by another 13.2000 + user, Mercurial can run hooks defined in that user's 13.2001 + repository, but it will still run them as <quote>you</quote>. 13.2002 + For example, if you <command role="hg-cmd">hg pull</command> 13.2003 + from that repository, and its <filename 13.2004 + role="special">.hg/hgrc</filename> defines a local <literal 13.2005 + role="hook">outgoing</literal> hook, that hook will run 13.2006 + under your user account, even though you don't own that 13.2007 + repository. 13.2008 + </para> 13.2009 + 13.2010 + <note> 13.2011 + <para id="x_1fa"> This only applies if you are pulling from a repository 13.2012 + on a local or network filesystem. If you're pulling over 13.2013 + http or ssh, any <literal role="hook">outgoing</literal> 13.2014 + hook will run under whatever account is executing the server 13.2015 + process, on the server. 13.2016 + </para> 13.2017 + </note> 13.2018 + 13.2019 + <para id="x_1fb">To see what hooks are defined in a repository, 13.2020 + use the <command role="hg-cmd">hg showconfig hooks</command> 13.2021 + command. If you are working in one repository, but talking to 13.2022 + another that you do not own (e.g. using <command 13.2023 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 13.2024 + incoming</command>), remember that it is the other 13.2025 + repository's hooks you should be checking, not your own. 13.2026 + </para> 13.2027 + </sect2> 13.2028 + 13.2029 + <sect2> 13.2030 + <title>Hooks do not propagate</title> 13.2031 + 13.2032 + <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do 13.2033 + not propagate when you clone, or pull from, a repository. The 13.2034 + reason for this is simple: a hook is a completely arbitrary 13.2035 + piece of executable code. It runs under your user identity, 13.2036 + with your privilege level, on your machine. 13.2037 + </para> 13.2038 + 13.2039 + <para id="x_1fd">It would be extremely reckless for any distributed 13.2040 + revision control system to implement revision-controlled 13.2041 + hooks, as this would offer an easily exploitable way to 13.2042 + subvert the accounts of users of the revision control system. 13.2043 + </para> 13.2044 + 13.2045 + <para id="x_1fe">Since Mercurial does not propagate hooks, if you are 13.2046 + collaborating with other people on a common project, you 13.2047 + should not assume that they are using the same Mercurial hooks 13.2048 + as you are, or that theirs are correctly configured. You 13.2049 + should document the hooks you expect people to use. 13.2050 + </para> 13.2051 + 13.2052 + <para id="x_1ff">In a corporate intranet, this is somewhat easier to 13.2053 + control, as you can for example provide a 13.2054 + <quote>standard</quote> installation of Mercurial on an NFS 13.2055 + filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 13.2056 + see. However, this too has its limits; see below. 13.2057 + </para> 13.2058 + </sect2> 13.2059 + 13.2060 + <sect2> 13.2061 + <title>Hooks can be overridden</title> 13.2062 + 13.2063 + <para id="x_200">Mercurial allows you to override a hook definition by 13.2064 + redefining the hook. You can disable it by setting its value 13.2065 + to the empty string, or change its behavior as you wish. 13.2066 + </para> 13.2067 + 13.2068 + <para id="x_201">If you deploy a system- or site-wide <filename 13.2069 + role="special">~/.hgrc</filename> file that defines some 13.2070 + hooks, you should thus understand that your users can disable 13.2071 + or override those hooks. 13.2072 + </para> 13.2073 + </sect2> 13.2074 + 13.2075 + <sect2> 13.2076 + <title>Ensuring that critical hooks are run</title> 13.2077 + 13.2078 + <para id="x_202">Sometimes you may want to enforce a policy that you do not 13.2079 + want others to be able to work around. For example, you may 13.2080 + have a requirement that every changeset must pass a rigorous 13.2081 + set of tests. Defining this requirement via a hook in a 13.2082 + site-wide <filename role="special">~/.hgrc</filename> won't 13.2083 + work for remote users on laptops, and of course local users 13.2084 + can subvert it at will by overriding the hook. 13.2085 + </para> 13.2086 + 13.2087 + <para id="x_203">Instead, you can set up your policies for use of Mercurial 13.2088 + so that people are expected to propagate changes through a 13.2089 + well-known <quote>canonical</quote> server that you have 13.2090 + locked down and configured appropriately. 13.2091 + </para> 13.2092 + 13.2093 + <para id="x_204">One way to do this is via a combination of social 13.2094 + engineering and technology. Set up a restricted-access 13.2095 + account; users can push changes over the network to 13.2096 + repositories managed by this account, but they cannot log into 13.2097 + the account and run normal shell commands. In this scenario, 13.2098 + a user can commit a changeset that contains any old garbage 13.2099 + they want. 13.2100 + </para> 13.2101 + 13.2102 + <para id="x_205">When someone pushes a changeset to the server that 13.2103 + everyone pulls from, the server will test the changeset before 13.2104 + it accepts it as permanent, and reject it if it fails to pass 13.2105 + the test suite. If people only pull changes from this 13.2106 + filtering server, it will serve to ensure that all changes 13.2107 + that people pull have been automatically vetted. 13.2108 + </para> 13.2109 + 13.2110 + </sect2> 13.2111 + </sect1> 13.2112 + 13.2113 + <sect1 id="sec:hook:simple"> 13.2114 + <title>A short tutorial on using hooks</title> 13.2115 + 13.2116 + <para id="x_212">It is easy to write a Mercurial hook. Let's start with a 13.2117 + hook that runs when you finish a <command role="hg-cmd">hg 13.2118 + commit</command>, and simply prints the hash of the changeset 13.2119 + you just created. The hook is called <literal 13.2120 + role="hook">commit</literal>. 13.2121 + </para> 13.2122 + 13.2123 + <para id="x_213">All hooks follow the pattern in this example.</para> 13.2124 + 13.2125 +&interaction.hook.simple.init; 13.2126 + 13.2127 + <para id="x_214">You add an entry to the <literal 13.2128 + role="rc-hooks">hooks</literal> section of your <filename 13.2129 + role="special">~/.hgrc</filename>. On the left is the name of 13.2130 + the event to trigger on; on the right is the action to take. As 13.2131 + you can see, you can run an arbitrary shell command in a hook. 13.2132 + Mercurial passes extra information to the hook using environment 13.2133 + variables (look for <envar>HG_NODE</envar> in the example). 13.2134 + </para> 13.2135 + 13.2136 + <sect2> 13.2137 + <title>Performing multiple actions per event</title> 13.2138 + 13.2139 + <para id="x_215">Quite often, you will want to define more than one hook 13.2140 + for a particular kind of event, as shown below.</para> 13.2141 + 13.2142 +&interaction.hook.simple.ext; 13.2143 + 13.2144 + <para id="x_216">Mercurial lets you do this by adding an 13.2145 + <emphasis>extension</emphasis> to the end of a hook's name. 13.2146 + You extend a hook's name by giving the name of the hook, 13.2147 + followed by a full stop (the 13.2148 + <quote><literal>.</literal></quote> character), followed by 13.2149 + some more text of your choosing. For example, Mercurial will 13.2150 + run both <literal>commit.foo</literal> and 13.2151 + <literal>commit.bar</literal> when the 13.2152 + <literal>commit</literal> event occurs. 13.2153 + </para> 13.2154 + 13.2155 + <para id="x_217">To give a well-defined order of execution when there are 13.2156 + multiple hooks defined for an event, Mercurial sorts hooks by 13.2157 + extension, and executes the hook commands in this sorted 13.2158 + order. In the above example, it will execute 13.2159 + <literal>commit.bar</literal> before 13.2160 + <literal>commit.foo</literal>, and <literal>commit</literal> 13.2161 + before both. 13.2162 + </para> 13.2163 + 13.2164 + <para id="x_218">It is a good idea to use a somewhat descriptive 13.2165 + extension when you define a new hook. This will help you to 13.2166 + remember what the hook was for. If the hook fails, you'll get 13.2167 + an error message that contains the hook name and extension, so 13.2168 + using a descriptive extension could give you an immediate hint 13.2169 + as to why the hook failed (see <xref 13.2170 + linkend="sec:hook:perm"/> for an example). 13.2171 + </para> 13.2172 + 13.2173 + </sect2> 13.2174 + <sect2 id="sec:hook:perm"> 13.2175 + <title>Controlling whether an activity can proceed</title> 13.2176 + 13.2177 + <para id="x_219">In our earlier examples, we used the <literal 13.2178 + role="hook">commit</literal> hook, which is run after a 13.2179 + commit has completed. This is one of several Mercurial hooks 13.2180 + that run after an activity finishes. Such hooks have no way 13.2181 + of influencing the activity itself. 13.2182 + </para> 13.2183 + 13.2184 + <para id="x_21a">Mercurial defines a number of events that occur before an 13.2185 + activity starts; or after it starts, but before it finishes. 13.2186 + Hooks that trigger on these events have the added ability to 13.2187 + choose whether the activity can continue, or will abort. 13.2188 + </para> 13.2189 + 13.2190 + <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs 13.2191 + after a commit has all but completed. In other words, the 13.2192 + metadata representing the changeset has been written out to 13.2193 + disk, but the transaction has not yet been allowed to 13.2194 + complete. The <literal role="hook">pretxncommit</literal> 13.2195 + hook has the ability to decide whether the transaction can 13.2196 + complete, or must be rolled back. 13.2197 + </para> 13.2198 + 13.2199 + <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook 13.2200 + exits with a status code of zero, the transaction is allowed 13.2201 + to complete; the commit finishes; and the <literal 13.2202 + role="hook">commit</literal> hook is run. If the <literal 13.2203 + role="hook">pretxncommit</literal> hook exits with a 13.2204 + non-zero status code, the transaction is rolled back; the 13.2205 + metadata representing the changeset is erased; and the 13.2206 + <literal role="hook">commit</literal> hook is not run. 13.2207 + </para> 13.2208 + 13.2209 +&interaction.hook.simple.pretxncommit; 13.2210 + 13.2211 + <para id="x_21d">The hook in the example above checks that a commit comment 13.2212 + contains a bug ID. If it does, the commit can complete. If 13.2213 + not, the commit is rolled back. 13.2214 + </para> 13.2215 + 13.2216 + </sect2> 13.2217 + </sect1> 13.2218 + <sect1> 13.2219 + <title>Writing your own hooks</title> 13.2220 + 13.2221 + <para id="x_21e">When you are writing a hook, you might find it useful to run 13.2222 + Mercurial either with the <option 13.2223 + role="hg-opt-global">-v</option> option, or the <envar 13.2224 + role="rc-item-ui">verbose</envar> config item set to 13.2225 + <quote>true</quote>. When you do so, Mercurial will print a 13.2226 + message before it calls each hook. 13.2227 + </para> 13.2228 + 13.2229 + <sect2 id="sec:hook:lang"> 13.2230 + <title>Choosing how your hook should run</title> 13.2231 + 13.2232 + <para id="x_21f">You can write a hook either as a normal 13.2233 + program&emdash;typically a shell script&emdash;or as a Python 13.2234 + function that is executed within the Mercurial process. 13.2235 + </para> 13.2236 + 13.2237 + <para id="x_220">Writing a hook as an external program has the advantage 13.2238 + that it requires no knowledge of Mercurial's internals. You 13.2239 + can call normal Mercurial commands to get any added 13.2240 + information you need. The trade-off is that external hooks 13.2241 + are slower than in-process hooks. 13.2242 + </para> 13.2243 + 13.2244 + <para id="x_221">An in-process Python hook has complete access to the 13.2245 + Mercurial API, and does not <quote>shell out</quote> to 13.2246 + another process, so it is inherently faster than an external 13.2247 + hook. It is also easier to obtain much of the information 13.2248 + that a hook requires by using the Mercurial API than by 13.2249 + running Mercurial commands. 13.2250 + </para> 13.2251 + 13.2252 + <para id="x_222">If you are comfortable with Python, or require high 13.2253 + performance, writing your hooks in Python may be a good 13.2254 + choice. However, when you have a straightforward hook to 13.2255 + write and you don't need to care about performance (probably 13.2256 + the majority of hooks), a shell script is perfectly fine. 13.2257 + </para> 13.2258 + 13.2259 + </sect2> 13.2260 + <sect2 id="sec:hook:param"> 13.2261 + <title>Hook parameters</title> 13.2262 + 13.2263 + <para id="x_223">Mercurial calls each hook with a set of well-defined 13.2264 + parameters. In Python, a parameter is passed as a keyword 13.2265 + argument to your hook function. For an external program, a 13.2266 + parameter is passed as an environment variable. 13.2267 + </para> 13.2268 + 13.2269 + <para id="x_224">Whether your hook is written in Python or as a shell 13.2270 + script, the hook-specific parameter names and values will be 13.2271 + the same. A boolean parameter will be represented as a 13.2272 + boolean value in Python, but as the number 1 (for 13.2273 + <quote>true</quote>) or 0 (for <quote>false</quote>) as an 13.2274 + environment variable for an external hook. If a hook 13.2275 + parameter is named <literal>foo</literal>, the keyword 13.2276 + argument for a Python hook will also be named 13.2277 + <literal>foo</literal>, while the environment variable for an 13.2278 + external hook will be named <literal>HG_FOO</literal>. 13.2279 + </para> 13.2280 + </sect2> 13.2281 + 13.2282 + <sect2> 13.2283 + <title>Hook return values and activity control</title> 13.2284 + 13.2285 + <para id="x_225">A hook that executes successfully must exit with a status 13.2286 + of zero if external, or return boolean <quote>false</quote> if 13.2287 + in-process. Failure is indicated with a non-zero exit status 13.2288 + from an external hook, or an in-process hook returning boolean 13.2289 + <quote>true</quote>. If an in-process hook raises an 13.2290 + exception, the hook is considered to have failed. 13.2291 + </para> 13.2292 + 13.2293 + <para id="x_226">For a hook that controls whether an activity can proceed, 13.2294 + zero/false means <quote>allow</quote>, while 13.2295 + non-zero/true/exception means <quote>deny</quote>. 13.2296 + </para> 13.2297 + </sect2> 13.2298 + 13.2299 + <sect2> 13.2300 + <title>Writing an external hook</title> 13.2301 + 13.2302 + <para id="x_227">When you define an external hook in your <filename 13.2303 + role="special">~/.hgrc</filename> and the hook is run, its 13.2304 + value is passed to your shell, which interprets it. This 13.2305 + means that you can use normal shell constructs in the body of 13.2306 + the hook. 13.2307 + </para> 13.2308 + 13.2309 + <para id="x_228">An executable hook is always run with its current 13.2310 + directory set to a repository's root directory. 13.2311 + </para> 13.2312 + 13.2313 + <para id="x_229">Each hook parameter is passed in as an environment 13.2314 + variable; the name is upper-cased, and prefixed with the 13.2315 + string <quote><literal>HG_</literal></quote>. 13.2316 + </para> 13.2317 + 13.2318 + <para id="x_22a">With the exception of hook parameters, Mercurial does not 13.2319 + set or modify any environment variables when running a hook. 13.2320 + This is useful to remember if you are writing a site-wide hook 13.2321 + that may be run by a number of different users with differing 13.2322 + environment variables set. In multi-user situations, you 13.2323 + should not rely on environment variables being set to the 13.2324 + values you have in your environment when testing the hook. 13.2325 + </para> 13.2326 + </sect2> 13.2327 + 13.2328 + <sect2> 13.2329 + <title>Telling Mercurial to use an in-process hook</title> 13.2330 + 13.2331 + <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax 13.2332 + for defining an in-process hook is slightly different than for 13.2333 + an executable hook. The value of the hook must start with the 13.2334 + text <quote><literal>python:</literal></quote>, and continue 13.2335 + with the fully-qualified name of a callable object to use as 13.2336 + the hook's value. 13.2337 + </para> 13.2338 + 13.2339 + <para id="x_22c">The module in which a hook lives is automatically imported 13.2340 + when a hook is run. So long as you have the module name and 13.2341 + <envar>PYTHONPATH</envar> right, it should <quote>just 13.2342 + work</quote>. 13.2343 + </para> 13.2344 + 13.2345 + <para id="x_22d">The following <filename role="special">~/.hgrc</filename> 13.2346 + example snippet illustrates the syntax and meaning of the 13.2347 + notions we just described. 13.2348 + </para> 13.2349 + <programlisting>[hooks] 13.2350 +commit.example = python:mymodule.submodule.myhook</programlisting> 13.2351 + <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> 13.2352 + hook, it imports <literal>mymodule.submodule</literal>, looks 13.2353 + for the callable object named <literal>myhook</literal>, and 13.2354 + calls it. 13.2355 + </para> 13.2356 + </sect2> 13.2357 + 13.2358 + <sect2> 13.2359 + <title>Writing an in-process hook</title> 13.2360 + 13.2361 + <para id="x_22f">The simplest in-process hook does nothing, but illustrates 13.2362 + the basic shape of the hook API: 13.2363 + </para> 13.2364 + <programlisting>def myhook(ui, repo, **kwargs): 13.2365 + pass</programlisting> 13.2366 + <para id="x_230">The first argument to a Python hook is always a <literal 13.2367 + role="py-mod-mercurial.ui">ui</literal> object. The second 13.2368 + is a repository object; at the moment, it is always an 13.2369 + instance of <literal 13.2370 + role="py-mod-mercurial.localrepo">localrepository</literal>. 13.2371 + Following these two arguments are other keyword arguments. 13.2372 + Which ones are passed in depends on the hook being called, but 13.2373 + a hook can ignore arguments it doesn't care about by dropping 13.2374 + them into a keyword argument dict, as with 13.2375 + <literal>**kwargs</literal> above. 13.2376 + </para> 13.2377 + 13.2378 + </sect2> 13.2379 + </sect1> 13.2380 + <sect1> 13.2381 + <title>Some hook examples</title> 13.2382 + 13.2383 + <sect2> 13.2384 + <title>Writing meaningful commit messages</title> 13.2385 + 13.2386 + <para id="x_231">It's hard to imagine a useful commit message being very 13.2387 + short. The simple <literal role="hook">pretxncommit</literal> 13.2388 + hook of the example below will prevent you from committing a 13.2389 + changeset with a message that is less than ten bytes long. 13.2390 + </para> 13.2391 + 13.2392 +&interaction.hook.msglen.go; 13.2393 + </sect2> 13.2394 + 13.2395 + <sect2> 13.2396 + <title>Checking for trailing whitespace</title> 13.2397 + 13.2398 + <para id="x_232">An interesting use of a commit-related hook is to help you 13.2399 + to write cleaner code. A simple example of <quote>cleaner 13.2400 + code</quote> is the dictum that a change should not add any 13.2401 + new lines of text that contain <quote>trailing 13.2402 + whitespace</quote>. Trailing whitespace is a series of 13.2403 + space and tab characters at the end of a line of text. In 13.2404 + most cases, trailing whitespace is unnecessary, invisible 13.2405 + noise, but it is occasionally problematic, and people often 13.2406 + prefer to get rid of it. 13.2407 + </para> 13.2408 + 13.2409 + <para id="x_233">You can use either the <literal 13.2410 + role="hook">precommit</literal> or <literal 13.2411 + role="hook">pretxncommit</literal> hook to tell whether you 13.2412 + have a trailing whitespace problem. If you use the <literal 13.2413 + role="hook">precommit</literal> hook, the hook will not know 13.2414 + which files you are committing, so it will have to check every 13.2415 + modified file in the repository for trailing white space. If 13.2416 + you want to commit a change to just the file 13.2417 + <filename>foo</filename>, but the file 13.2418 + <filename>bar</filename> contains trailing whitespace, doing a 13.2419 + check in the <literal role="hook">precommit</literal> hook 13.2420 + will prevent you from committing <filename>foo</filename> due 13.2421 + to the problem with <filename>bar</filename>. This doesn't 13.2422 + seem right. 13.2423 + </para> 13.2424 + 13.2425 + <para id="x_234">Should you choose the <literal 13.2426 + role="hook">pretxncommit</literal> hook, the check won't 13.2427 + occur until just before the transaction for the commit 13.2428 + completes. This will allow you to check for problems only the 13.2429 + exact files that are being committed. However, if you entered 13.2430 + the commit message interactively and the hook fails, the 13.2431 + transaction will roll back; you'll have to re-enter the commit 13.2432 + message after you fix the trailing whitespace and run <command 13.2433 + role="hg-cmd">hg commit</command> again. 13.2434 + </para> 13.2435 + 13.2436 + &interaction.ch09-hook.ws.simple; 13.2437 + 13.2438 + <para id="x_235">In this example, we introduce a simple <literal 13.2439 + role="hook">pretxncommit</literal> hook that checks for 13.2440 + trailing whitespace. This hook is short, but not very 13.2441 + helpful. It exits with an error status if a change adds a 13.2442 + line with trailing whitespace to any file, but does not print 13.2443 + any information that might help us to identify the offending 13.2444 + file or line. It also has the nice property of not paying 13.2445 + attention to unmodified lines; only lines that introduce new 13.2446 + trailing whitespace cause problems. 13.2447 + </para> 13.2448 + 13.2449 + &ch09-check_whitespace.py.lst; 13.2450 + 13.2451 + <para id="x_236">The above version is much more complex, but also more 13.2452 + useful. It parses a unified diff to see if any lines add 13.2453 + trailing whitespace, and prints the name of the file and the 13.2454 + line number of each such occurrence. Even better, if the 13.2455 + change adds trailing whitespace, this hook saves the commit 13.2456 + comment and prints the name of the save file before exiting 13.2457 + and telling Mercurial to roll the transaction back, so you can 13.2458 + use the <option role="hg-opt-commit">-l filename</option> 13.2459 + option to <command role="hg-cmd">hg commit</command> to reuse 13.2460 + the saved commit message once you've corrected the problem. 13.2461 + </para> 13.2462 + 13.2463 + &interaction.ch09-hook.ws.better; 13.2464 + 13.2465 + <para id="x_237">As a final aside, note in the example above the 13.2466 + use of <command>sed</command>'s in-place editing feature to 13.2467 + get rid of trailing whitespace from a file. This is concise 13.2468 + and useful enough that I will reproduce it here (using 13.2469 + <command>perl</command> for good measure).</para> 13.2470 + <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> 13.2471 + 13.2472 + </sect2> 13.2473 + </sect1> 13.2474 + <sect1> 13.2475 + <title>Bundled hooks</title> 13.2476 + 13.2477 + <para id="x_238">Mercurial ships with several bundled hooks. You can find 13.2478 + them in the <filename class="directory">hgext</filename> 13.2479 + directory of a Mercurial source tree. If you are using a 13.2480 + Mercurial binary package, the hooks will be located in the 13.2481 + <filename class="directory">hgext</filename> directory of 13.2482 + wherever your package installer put Mercurial. 13.2483 + </para> 13.2484 + 13.2485 + <sect2> 13.2486 + <title><literal role="hg-ext">acl</literal>&emdash;access 13.2487 + control for parts of a repository</title> 13.2488 + 13.2489 + <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets 13.2490 + you control which remote users are allowed to push changesets 13.2491 + to a networked server. You can protect any portion of a 13.2492 + repository (including the entire repo), so that a specific 13.2493 + remote user can push changes that do not affect the protected 13.2494 + portion. 13.2495 + </para> 13.2496 + 13.2497 + <para id="x_23a">This extension implements access control based on the 13.2498 + identity of the user performing a push, 13.2499 + <emphasis>not</emphasis> on who committed the changesets 13.2500 + they're pushing. It makes sense to use this hook only if you 13.2501 + have a locked-down server environment that authenticates 13.2502 + remote users, and you want to be sure that only specific users 13.2503 + are allowed to push changes to that server. 13.2504 + </para> 13.2505 + 13.2506 + <sect3> 13.2507 + <title>Configuring the <literal role="hook">acl</literal> 13.2508 + hook</title> 13.2509 + 13.2510 + <para id="x_23b">In order to manage incoming changesets, the <literal 13.2511 + role="hg-ext">acl</literal> hook must be used as a 13.2512 + <literal role="hook">pretxnchangegroup</literal> hook. This 13.2513 + lets it see which files are modified by each incoming 13.2514 + changeset, and roll back a group of changesets if they 13.2515 + modify <quote>forbidden</quote> files. Example: 13.2516 + </para> 13.2517 + <programlisting>[hooks] 13.2518 +pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> 13.2519 + 13.2520 + <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is 13.2521 + configured using three sections. 13.2522 + </para> 13.2523 + 13.2524 + <para id="x_23d">The <literal role="rc-acl">acl</literal> section has 13.2525 + only one entry, <envar role="rc-item-acl">sources</envar>, 13.2526 + which lists the sources of incoming changesets that the hook 13.2527 + should pay attention to. You don't normally need to 13.2528 + configure this section. 13.2529 + </para> 13.2530 + <itemizedlist> 13.2531 + <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: 13.2532 + Control incoming changesets that are arriving from a 13.2533 + remote repository over http or ssh. This is the default 13.2534 + value of <envar role="rc-item-acl">sources</envar>, and 13.2535 + usually the only setting you'll need for this 13.2536 + configuration item. 13.2537 + </para> 13.2538 + </listitem> 13.2539 + <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: 13.2540 + Control incoming changesets that are arriving via a pull 13.2541 + from a local repository. 13.2542 + </para> 13.2543 + </listitem> 13.2544 + <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: 13.2545 + Control incoming changesets that are arriving via a push 13.2546 + from a local repository. 13.2547 + </para> 13.2548 + </listitem> 13.2549 + <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: 13.2550 + Control incoming changesets that are arriving from 13.2551 + another repository via a bundle. 13.2552 + </para> 13.2553 + </listitem></itemizedlist> 13.2554 + 13.2555 + <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> 13.2556 + section controls the users that are allowed to add 13.2557 + changesets to the repository. If this section is not 13.2558 + present, all users that are not explicitly denied are 13.2559 + allowed. If this section is present, all users that are not 13.2560 + explicitly allowed are denied (so an empty section means 13.2561 + that all users are denied). 13.2562 + </para> 13.2563 + 13.2564 + <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> 13.2565 + section determines which users are denied from adding 13.2566 + changesets to the repository. If this section is not 13.2567 + present or is empty, no users are denied. 13.2568 + </para> 13.2569 + 13.2570 + <para id="x_244">The syntaxes for the <literal 13.2571 + role="rc-acl.allow">acl.allow</literal> and <literal 13.2572 + role="rc-acl.deny">acl.deny</literal> sections are 13.2573 + identical. On the left of each entry is a glob pattern that 13.2574 + matches files or directories, relative to the root of the 13.2575 + repository; on the right, a user name. 13.2576 + </para> 13.2577 + 13.2578 + <para id="x_245">In the following example, the user 13.2579 + <literal>docwriter</literal> can only push changes to the 13.2580 + <filename class="directory">docs</filename> subtree of the 13.2581 + repository, while <literal>intern</literal> can push changes 13.2582 + to any file or directory except <filename 13.2583 + class="directory">source/sensitive</filename>. 13.2584 + </para> 13.2585 + <programlisting>[acl.allow] 13.2586 +docs/** = docwriter 13.2587 +[acl.deny] 13.2588 +source/sensitive/** = intern</programlisting> 13.2589 + 13.2590 + </sect3> 13.2591 + <sect3> 13.2592 + <title>Testing and troubleshooting</title> 13.2593 + 13.2594 + <para id="x_246">If you want to test the <literal 13.2595 + role="hg-ext">acl</literal> hook, run it with Mercurial's 13.2596 + debugging output enabled. Since you'll probably be running 13.2597 + it on a server where it's not convenient (or sometimes 13.2598 + possible) to pass in the <option 13.2599 + role="hg-opt-global">--debug</option> option, don't forget 13.2600 + that you can enable debugging output in your <filename 13.2601 + role="special">~/.hgrc</filename>: 13.2602 + </para> 13.2603 + <programlisting>[ui] 13.2604 +debug = true</programlisting> 13.2605 + <para id="x_247">With this enabled, the <literal 13.2606 + role="hg-ext">acl</literal> hook will print enough 13.2607 + information to let you figure out why it is allowing or 13.2608 + forbidding pushes from specific users. 13.2609 + </para> 13.2610 + 13.2611 + </sect3> </sect2> 13.2612 + 13.2613 + <sect2> 13.2614 + <title><literal 13.2615 + role="hg-ext">bugzilla</literal>&emdash;integration with 13.2616 + Bugzilla</title> 13.2617 + 13.2618 + <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension 13.2619 + adds a comment to a Bugzilla bug whenever it finds a reference 13.2620 + to that bug ID in a commit comment. You can install this hook 13.2621 + on a shared server, so that any time a remote user pushes 13.2622 + changes to this server, the hook gets run. 13.2623 + </para> 13.2624 + 13.2625 + <para id="x_249">It adds a comment to the bug that looks like this (you can 13.2626 + configure the contents of the comment&emdash;see below): 13.2627 + </para> 13.2628 + <programlisting>Changeset aad8b264143a, made by Joe User 13.2629 + <joe.user@domain.com> in the frobnitz repository, refers 13.2630 + to this bug. For complete details, see 13.2631 + http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 13.2632 + Changeset description: Fix bug 10483 by guarding against some 13.2633 + NULL pointers</programlisting> 13.2634 + <para id="x_24a">The value of this hook is that it automates the process of 13.2635 + updating a bug any time a changeset refers to it. If you 13.2636 + configure the hook properly, it makes it easy for people to 13.2637 + browse straight from a Bugzilla bug to a changeset that refers 13.2638 + to that bug. 13.2639 + </para> 13.2640 + 13.2641 + <para id="x_24b">You can use the code in this hook as a starting point for 13.2642 + some more exotic Bugzilla integration recipes. Here are a few 13.2643 + possibilities: 13.2644 + </para> 13.2645 + <itemizedlist> 13.2646 + <listitem><para id="x_24c">Require that every changeset pushed to the 13.2647 + server have a valid bug ID in its commit comment. In this 13.2648 + case, you'd want to configure the hook as a <literal 13.2649 + role="hook">pretxncommit</literal> hook. This would 13.2650 + allow the hook to reject changes that didn't contain bug 13.2651 + IDs. 13.2652 + </para> 13.2653 + </listitem> 13.2654 + <listitem><para id="x_24d">Allow incoming changesets to automatically 13.2655 + modify the <emphasis>state</emphasis> of a bug, as well as 13.2656 + simply adding a comment. For example, the hook could 13.2657 + recognise the string <quote>fixed bug 31337</quote> as 13.2658 + indicating that it should update the state of bug 31337 to 13.2659 + <quote>requires testing</quote>. 13.2660 + </para> 13.2661 + </listitem></itemizedlist> 13.2662 + 13.2663 + <sect3 id="sec:hook:bugzilla:config"> 13.2664 + <title>Configuring the <literal role="hook">bugzilla</literal> 13.2665 + hook</title> 13.2666 + 13.2667 + <para id="x_24e">You should configure this hook in your server's 13.2668 + <filename role="special">~/.hgrc</filename> as an <literal 13.2669 + role="hook">incoming</literal> hook, for example as 13.2670 + follows: 13.2671 + </para> 13.2672 + <programlisting>[hooks] 13.2673 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> 13.2674 + 13.2675 + <para id="x_24f">Because of the specialised nature of this hook, and 13.2676 + because Bugzilla was not written with this kind of 13.2677 + integration in mind, configuring this hook is a somewhat 13.2678 + involved process. 13.2679 + </para> 13.2680 + 13.2681 + <para id="x_250">Before you begin, you must install the MySQL bindings 13.2682 + for Python on the host(s) where you'll be running the hook. 13.2683 + If this is not available as a binary package for your 13.2684 + system, you can download it from 13.2685 + <citation>web:mysql-python</citation>. 13.2686 + </para> 13.2687 + 13.2688 + <para id="x_251">Configuration information for this hook lives in the 13.2689 + <literal role="rc-bugzilla">bugzilla</literal> section of 13.2690 + your <filename role="special">~/.hgrc</filename>. 13.2691 + </para> 13.2692 + <itemizedlist> 13.2693 + <listitem><para id="x_252"><envar 13.2694 + role="rc-item-bugzilla">version</envar>: The version 13.2695 + of Bugzilla installed on the server. The database 13.2696 + schema that Bugzilla uses changes occasionally, so this 13.2697 + hook has to know exactly which schema to use.</para> 13.2698 + </listitem> 13.2699 + <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: 13.2700 + The hostname of the MySQL server that stores your 13.2701 + Bugzilla data. The database must be configured to allow 13.2702 + connections from whatever host you are running the 13.2703 + <literal role="hook">bugzilla</literal> hook on. 13.2704 + </para> 13.2705 + </listitem> 13.2706 + <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: 13.2707 + The username with which to connect to the MySQL server. 13.2708 + The database must be configured to allow this user to 13.2709 + connect from whatever host you are running the <literal 13.2710 + role="hook">bugzilla</literal> hook on. This user 13.2711 + must be able to access and modify Bugzilla tables. The 13.2712 + default value of this item is <literal>bugs</literal>, 13.2713 + which is the standard name of the Bugzilla user in a 13.2714 + MySQL database. 13.2715 + </para> 13.2716 + </listitem> 13.2717 + <listitem><para id="x_255"><envar 13.2718 + role="rc-item-bugzilla">password</envar>: The MySQL 13.2719 + password for the user you configured above. This is 13.2720 + stored as plain text, so you should make sure that 13.2721 + unauthorised users cannot read the <filename 13.2722 + role="special">~/.hgrc</filename> file where you 13.2723 + store this information. 13.2724 + </para> 13.2725 + </listitem> 13.2726 + <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: 13.2727 + The name of the Bugzilla database on the MySQL server. 13.2728 + The default value of this item is 13.2729 + <literal>bugs</literal>, which is the standard name of 13.2730 + the MySQL database where Bugzilla stores its data. 13.2731 + </para> 13.2732 + </listitem> 13.2733 + <listitem><para id="x_257"><envar 13.2734 + role="rc-item-bugzilla">notify</envar>: If you want 13.2735 + Bugzilla to send out a notification email to subscribers 13.2736 + after this hook has added a comment to a bug, you will 13.2737 + need this hook to run a command whenever it updates the 13.2738 + database. The command to run depends on where you have 13.2739 + installed Bugzilla, but it will typically look something 13.2740 + like this, if you have Bugzilla installed in <filename 13.2741 + class="directory">/var/www/html/bugzilla</filename>: 13.2742 + </para> 13.2743 + <programlisting>cd /var/www/html/bugzilla && 13.2744 + ./processmail %s nobody@nowhere.com</programlisting> 13.2745 + </listitem> 13.2746 + <listitem><para id="x_258"> The Bugzilla 13.2747 + <literal>processmail</literal> program expects to be 13.2748 + given a bug ID (the hook replaces 13.2749 + <quote><literal>%s</literal></quote> with the bug ID) 13.2750 + and an email address. It also expects to be able to 13.2751 + write to some files in the directory that it runs in. 13.2752 + If Bugzilla and this hook are not installed on the same 13.2753 + machine, you will need to find a way to run 13.2754 + <literal>processmail</literal> on the server where 13.2755 + Bugzilla is installed. 13.2756 + </para> 13.2757 + </listitem></itemizedlist> 13.2758 + 13.2759 + </sect3> 13.2760 + <sect3> 13.2761 + <title>Mapping committer names to Bugzilla user names</title> 13.2762 + 13.2763 + <para id="x_259">By default, the <literal 13.2764 + role="hg-ext">bugzilla</literal> hook tries to use the 13.2765 + email address of a changeset's committer as the Bugzilla 13.2766 + user name with which to update a bug. If this does not suit 13.2767 + your needs, you can map committer email addresses to 13.2768 + Bugzilla user names using a <literal 13.2769 + role="rc-usermap">usermap</literal> section. 13.2770 + </para> 13.2771 + 13.2772 + <para id="x_25a">Each item in the <literal 13.2773 + role="rc-usermap">usermap</literal> section contains an 13.2774 + email address on the left, and a Bugzilla user name on the 13.2775 + right. 13.2776 + </para> 13.2777 + <programlisting>[usermap] 13.2778 +jane.user@example.com = jane</programlisting> 13.2779 + <para id="x_25b">You can either keep the <literal 13.2780 + role="rc-usermap">usermap</literal> data in a normal 13.2781 + <filename role="special">~/.hgrc</filename>, or tell the 13.2782 + <literal role="hg-ext">bugzilla</literal> hook to read the 13.2783 + information from an external <filename>usermap</filename> 13.2784 + file. In the latter case, you can store 13.2785 + <filename>usermap</filename> data by itself in (for example) 13.2786 + a user-modifiable repository. This makes it possible to let 13.2787 + your users maintain their own <envar 13.2788 + role="rc-item-bugzilla">usermap</envar> entries. The main 13.2789 + <filename role="special">~/.hgrc</filename> file might look 13.2790 + like this: 13.2791 + </para> 13.2792 + <programlisting># regular hgrc file refers to external usermap file 13.2793 +[bugzilla] 13.2794 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 13.2795 + <para id="x_25c">While the <filename>usermap</filename> file that it 13.2796 + refers to might look like this: 13.2797 + </para> 13.2798 + <programlisting># bugzilla-usermap.conf - inside a hg repository 13.2799 +[usermap] stephanie@example.com = steph</programlisting> 13.2800 + 13.2801 + </sect3> 13.2802 + <sect3> 13.2803 + <title>Configuring the text that gets added to a bug</title> 13.2804 + 13.2805 + <para id="x_25d">You can configure the text that this hook adds as a 13.2806 + comment; you specify it in the form of a Mercurial template. 13.2807 + Several <filename role="special">~/.hgrc</filename> entries 13.2808 + (still in the <literal role="rc-bugzilla">bugzilla</literal> 13.2809 + section) control this behavior. 13.2810 + </para> 13.2811 + <itemizedlist> 13.2812 + <listitem><para id="x_25e"><literal>strip</literal>: The number of 13.2813 + leading path elements to strip from a repository's path 13.2814 + name to construct a partial path for a URL. For example, 13.2815 + if the repositories on your server live under <filename 13.2816 + class="directory">/home/hg/repos</filename>, and you 13.2817 + have a repository whose path is <filename 13.2818 + class="directory">/home/hg/repos/app/tests</filename>, 13.2819 + then setting <literal>strip</literal> to 13.2820 + <literal>4</literal> will give a partial path of 13.2821 + <filename class="directory">app/tests</filename>. The 13.2822 + hook will make this partial path available when 13.2823 + expanding a template, as <literal>webroot</literal>. 13.2824 + </para> 13.2825 + </listitem> 13.2826 + <listitem><para id="x_25f"><literal>template</literal>: The text of the 13.2827 + template to use. In addition to the usual 13.2828 + changeset-related variables, this template can use 13.2829 + <literal>hgweb</literal> (the value of the 13.2830 + <literal>hgweb</literal> configuration item above) and 13.2831 + <literal>webroot</literal> (the path constructed using 13.2832 + <literal>strip</literal> above). 13.2833 + </para> 13.2834 + </listitem></itemizedlist> 13.2835 + 13.2836 + <para id="x_260">In addition, you can add a <envar 13.2837 + role="rc-item-web">baseurl</envar> item to the <literal 13.2838 + role="rc-web">web</literal> section of your <filename 13.2839 + role="special">~/.hgrc</filename>. The <literal 13.2840 + role="hg-ext">bugzilla</literal> hook will make this 13.2841 + available when expanding a template, as the base string to 13.2842 + use when constructing a URL that will let users browse from 13.2843 + a Bugzilla comment to view a changeset. Example: 13.2844 + </para> 13.2845 + <programlisting>[web] 13.2846 +baseurl = http://hg.domain.com/</programlisting> 13.2847 + 13.2848 + <para id="x_261">Here is an example set of <literal 13.2849 + role="hg-ext">bugzilla</literal> hook config information. 13.2850 + </para> 13.2851 + 13.2852 + &ch10-bugzilla-config.lst; 13.2853 + 13.2854 + </sect3> 13.2855 + <sect3> 13.2856 + <title>Testing and troubleshooting</title> 13.2857 + 13.2858 + <para id="x_262">The most common problems with configuring the <literal 13.2859 + role="hg-ext">bugzilla</literal> hook relate to running 13.2860 + Bugzilla's <filename>processmail</filename> script and 13.2861 + mapping committer names to user names. 13.2862 + </para> 13.2863 + 13.2864 + <para id="x_263">Recall from <xref 13.2865 + linkend="sec:hook:bugzilla:config"/> above that the user 13.2866 + that runs the Mercurial process on the server is also the 13.2867 + one that will run the <filename>processmail</filename> 13.2868 + script. The <filename>processmail</filename> script 13.2869 + sometimes causes Bugzilla to write to files in its 13.2870 + configuration directory, and Bugzilla's configuration files 13.2871 + are usually owned by the user that your web server runs 13.2872 + under. 13.2873 + </para> 13.2874 + 13.2875 + <para id="x_264">You can cause <filename>processmail</filename> to be run 13.2876 + with the suitable user's identity using the 13.2877 + <command>sudo</command> command. Here is an example entry 13.2878 + for a <filename>sudoers</filename> file. 13.2879 + </para> 13.2880 + <programlisting>hg_user = (httpd_user) 13.2881 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> 13.2882 + <para id="x_265">This allows the <literal>hg_user</literal> user to run a 13.2883 + <filename>processmail-wrapper</filename> program under the 13.2884 + identity of <literal>httpd_user</literal>. 13.2885 + </para> 13.2886 + 13.2887 + <para id="x_266">This indirection through a wrapper script is necessary, 13.2888 + because <filename>processmail</filename> expects to be run 13.2889 + with its current directory set to wherever you installed 13.2890 + Bugzilla; you can't specify that kind of constraint in a 13.2891 + <filename>sudoers</filename> file. The contents of the 13.2892 + wrapper script are simple: 13.2893 + </para> 13.2894 + <programlisting>#!/bin/sh 13.2895 +cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> 13.2896 + <para id="x_267">It doesn't seem to matter what email address you pass to 13.2897 + <filename>processmail</filename>. 13.2898 + </para> 13.2899 + 13.2900 + <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is 13.2901 + not set up correctly, users will see an error message from 13.2902 + the <literal role="hg-ext">bugzilla</literal> hook when they 13.2903 + push changes to the server. The error message will look 13.2904 + like this: 13.2905 + </para> 13.2906 + <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> 13.2907 + <para id="x_269">What this means is that the committer's address, 13.2908 + <literal>john.q.public@example.com</literal>, is not a valid 13.2909 + Bugzilla user name, nor does it have an entry in your 13.2910 + <literal role="rc-usermap">usermap</literal> that maps it to 13.2911 + a valid Bugzilla user name. 13.2912 + </para> 13.2913 + 13.2914 + </sect3> </sect2> 13.2915 + 13.2916 + <sect2> 13.2917 + <title><literal role="hg-ext">notify</literal>&emdash;send email 13.2918 + notifications</title> 13.2919 + 13.2920 + <para id="x_26a">Although Mercurial's built-in web server provides RSS 13.2921 + feeds of changes in every repository, many people prefer to 13.2922 + receive change notifications via email. The <literal 13.2923 + role="hg-ext">notify</literal> hook lets you send out 13.2924 + notifications to a set of email addresses whenever changesets 13.2925 + arrive that those subscribers are interested in. 13.2926 + </para> 13.2927 + 13.2928 + <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> 13.2929 + hook, the <literal role="hg-ext">notify</literal> hook is 13.2930 + template-driven, so you can customise the contents of the 13.2931 + notification messages that it sends. 13.2932 + </para> 13.2933 + 13.2934 + <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> 13.2935 + hook includes a diff of every changeset that it sends out; you 13.2936 + can limit the size of the diff, or turn this feature off 13.2937 + entirely. It is useful for letting subscribers review changes 13.2938 + immediately, rather than clicking to follow a URL. 13.2939 + </para> 13.2940 + 13.2941 + <sect3> 13.2942 + <title>Configuring the <literal role="hg-ext">notify</literal> 13.2943 + hook</title> 13.2944 + 13.2945 + <para id="x_26d">You can set up the <literal 13.2946 + role="hg-ext">notify</literal> hook to send one email 13.2947 + message per incoming changeset, or one per incoming group of 13.2948 + changesets (all those that arrived in a single pull or 13.2949 + push). 13.2950 + </para> 13.2951 + <programlisting>[hooks] 13.2952 +# send one email per group of changes 13.2953 +changegroup.notify = python:hgext.notify.hook 13.2954 +# send one email per change 13.2955 +incoming.notify = python:hgext.notify.hook</programlisting> 13.2956 + 13.2957 + <para id="x_26e">Configuration information for this hook lives in the 13.2958 + <literal role="rc-notify">notify</literal> section of a 13.2959 + <filename role="special">~/.hgrc</filename> file. 13.2960 + </para> 13.2961 + <itemizedlist> 13.2962 + <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: 13.2963 + By default, this hook does not send out email at all; 13.2964 + instead, it prints the message that it 13.2965 + <emphasis>would</emphasis> send. Set this item to 13.2966 + <literal>false</literal> to allow email to be sent. The 13.2967 + reason that sending of email is turned off by default is 13.2968 + that it takes several tries to configure this extension 13.2969 + exactly as you would like, and it would be bad form to 13.2970 + spam subscribers with a number of <quote>broken</quote> 13.2971 + notifications while you debug your configuration. 13.2972 + </para> 13.2973 + </listitem> 13.2974 + <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: 13.2975 + The path to a configuration file that contains 13.2976 + subscription information. This is kept separate from 13.2977 + the main <filename role="special">~/.hgrc</filename> so 13.2978 + that you can maintain it in a repository of its own. 13.2979 + People can then clone that repository, update their 13.2980 + subscriptions, and push the changes back to your server. 13.2981 + </para> 13.2982 + </listitem> 13.2983 + <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: 13.2984 + The number of leading path separator characters to strip 13.2985 + from a repository's path, when deciding whether a 13.2986 + repository has subscribers. For example, if the 13.2987 + repositories on your server live in <filename 13.2988 + class="directory">/home/hg/repos</filename>, and 13.2989 + <literal role="hg-ext">notify</literal> is considering a 13.2990 + repository named <filename 13.2991 + class="directory">/home/hg/repos/shared/test</filename>, 13.2992 + setting <envar role="rc-item-notify">strip</envar> to 13.2993 + <literal>4</literal> will cause <literal 13.2994 + role="hg-ext">notify</literal> to trim the path it 13.2995 + considers down to <filename 13.2996 + class="directory">shared/test</filename>, and it will 13.2997 + match subscribers against that. 13.2998 + </para> 13.2999 + </listitem> 13.3000 + <listitem><para id="x_272"><envar 13.3001 + role="rc-item-notify">template</envar>: The template 13.3002 + text to use when sending messages. This specifies both 13.3003 + the contents of the message header and its body. 13.3004 + </para> 13.3005 + </listitem> 13.3006 + <listitem><para id="x_273"><envar 13.3007 + role="rc-item-notify">maxdiff</envar>: The maximum 13.3008 + number of lines of diff data to append to the end of a 13.3009 + message. If a diff is longer than this, it is 13.3010 + truncated. By default, this is set to 300. Set this to 13.3011 + <literal>0</literal> to omit diffs from notification 13.3012 + emails. 13.3013 + </para> 13.3014 + </listitem> 13.3015 + <listitem><para id="x_274"><envar 13.3016 + role="rc-item-notify">sources</envar>: A list of 13.3017 + sources of changesets to consider. This lets you limit 13.3018 + <literal role="hg-ext">notify</literal> to only sending 13.3019 + out email about changes that remote users pushed into 13.3020 + this repository via a server, for example. See 13.3021 + <xref linkend="sec:hook:sources"/> for the sources you 13.3022 + can specify here. 13.3023 + </para> 13.3024 + </listitem></itemizedlist> 13.3025 + 13.3026 + <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> 13.3027 + item in the <literal role="rc-web">web</literal> section, 13.3028 + you can use it in a template; it will be available as 13.3029 + <literal>webroot</literal>. 13.3030 + </para> 13.3031 + 13.3032 + <para id="x_276">Here is an example set of <literal 13.3033 + role="hg-ext">notify</literal> configuration information. 13.3034 + </para> 13.3035 + 13.3036 + &ch10-notify-config.lst; 13.3037 + 13.3038 + <para id="x_277">This will produce a message that looks like the 13.3039 + following: 13.3040 + </para> 13.3041 + 13.3042 + &ch10-notify-config-mail.lst; 13.3043 + 13.3044 + </sect3> 13.3045 + <sect3> 13.3046 + <title>Testing and troubleshooting</title> 13.3047 + 13.3048 + <para id="x_278">Do not forget that by default, the <literal 13.3049 + role="hg-ext">notify</literal> extension <emphasis>will not 13.3050 + send any mail</emphasis> until you explicitly configure it to do so, 13.3051 + by setting <envar role="rc-item-notify">test</envar> to 13.3052 + <literal>false</literal>. Until you do that, it simply 13.3053 + prints the message it <emphasis>would</emphasis> send. 13.3054 + </para> 13.3055 + 13.3056 + </sect3> 13.3057 + </sect2> 13.3058 + </sect1> 13.3059 + <sect1 id="sec:hook:ref"> 13.3060 + <title>Information for writers of hooks</title> 13.3061 + 13.3062 + <sect2> 13.3063 + <title>In-process hook execution</title> 13.3064 + 13.3065 + <para id="x_279">An in-process hook is called with arguments of the 13.3066 + following form: 13.3067 + </para> 13.3068 + <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> 13.3069 + <para id="x_27a">The <literal>ui</literal> parameter is a <literal 13.3070 + role="py-mod-mercurial.ui">ui</literal> object. The 13.3071 + <literal>repo</literal> parameter is a <literal 13.3072 + role="py-mod-mercurial.localrepo">localrepository</literal> 13.3073 + object. The names and values of the 13.3074 + <literal>**kwargs</literal> parameters depend on the hook 13.3075 + being invoked, with the following common features: 13.3076 + </para> 13.3077 + <itemizedlist> 13.3078 + <listitem><para id="x_27b">If a parameter is named 13.3079 + <literal>node</literal> or <literal>parentN</literal>, it 13.3080 + will contain a hexadecimal changeset ID. The empty string 13.3081 + is used to represent <quote>null changeset ID</quote> 13.3082 + instead of a string of zeroes. 13.3083 + </para> 13.3084 + </listitem> 13.3085 + <listitem><para id="x_27c">If a parameter is named 13.3086 + <literal>url</literal>, it will contain the URL of a 13.3087 + remote repository, if that can be determined. 13.3088 + </para> 13.3089 + </listitem> 13.3090 + <listitem><para id="x_27d">Boolean-valued parameters are represented as 13.3091 + Python <literal>bool</literal> objects. 13.3092 + </para> 13.3093 + </listitem></itemizedlist> 13.3094 + 13.3095 + <para id="x_27e">An in-process hook is called without a change to the 13.3096 + process's working directory (unlike external hooks, which are 13.3097 + run in the root of the repository). It must not change the 13.3098 + process's working directory, or it will cause any calls it 13.3099 + makes into the Mercurial API to fail. 13.3100 + </para> 13.3101 + 13.3102 + <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it 13.3103 + is considered to have succeeded. If it returns a boolean 13.3104 + <quote>true</quote> value or raises an exception, it is 13.3105 + considered to have failed. A useful way to think of the 13.3106 + calling convention is <quote>tell me if you fail</quote>. 13.3107 + </para> 13.3108 + 13.3109 + <para id="x_280">Note that changeset IDs are passed into Python hooks as 13.3110 + hexadecimal strings, not the binary hashes that Mercurial's 13.3111 + APIs normally use. To convert a hash from hex to binary, use 13.3112 + the <literal>bin</literal> function. 13.3113 + </para> 13.3114 + </sect2> 13.3115 + 13.3116 + <sect2> 13.3117 + <title>External hook execution</title> 13.3118 + 13.3119 + <para id="x_281">An external hook is passed to the shell of the user 13.3120 + running Mercurial. Features of that shell, such as variable 13.3121 + substitution and command redirection, are available. The hook 13.3122 + is run in the root directory of the repository (unlike 13.3123 + in-process hooks, which are run in the same directory that 13.3124 + Mercurial was run in). 13.3125 + </para> 13.3126 + 13.3127 + <para id="x_282">Hook parameters are passed to the hook as environment 13.3128 + variables. Each environment variable's name is converted in 13.3129 + upper case and prefixed with the string 13.3130 + <quote><literal>HG_</literal></quote>. For example, if the 13.3131 + name of a parameter is <quote><literal>node</literal></quote>, 13.3132 + the name of the environment variable representing that 13.3133 + parameter will be <quote><literal>HG_NODE</literal></quote>. 13.3134 + </para> 13.3135 + 13.3136 + <para id="x_283">A boolean parameter is represented as the string 13.3137 + <quote><literal>1</literal></quote> for <quote>true</quote>, 13.3138 + <quote><literal>0</literal></quote> for <quote>false</quote>. 13.3139 + If an environment variable is named <envar>HG_NODE</envar>, 13.3140 + <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 13.3141 + contains a changeset ID represented as a hexadecimal string. 13.3142 + The empty string is used to represent <quote>null changeset 13.3143 + ID</quote> instead of a string of zeroes. If an environment 13.3144 + variable is named <envar>HG_URL</envar>, it will contain the 13.3145 + URL of a remote repository, if that can be determined. 13.3146 + </para> 13.3147 + 13.3148 + <para id="x_284">If a hook exits with a status of zero, it is considered to 13.3149 + have succeeded. If it exits with a non-zero status, it is 13.3150 + considered to have failed. 13.3151 + </para> 13.3152 + </sect2> 13.3153 + 13.3154 + <sect2> 13.3155 + <title>Finding out where changesets come from</title> 13.3156 + 13.3157 + <para id="x_285">A hook that involves the transfer of changesets between a 13.3158 + local repository and another may be able to find out 13.3159 + information about the <quote>far side</quote>. Mercurial 13.3160 + knows <emphasis>how</emphasis> changes are being transferred, 13.3161 + and in many cases <emphasis>where</emphasis> they are being 13.3162 + transferred to or from. 13.3163 + </para> 13.3164 + 13.3165 + <sect3 id="sec:hook:sources"> 13.3166 + <title>Sources of changesets</title> 13.3167 + 13.3168 + <para id="x_286">Mercurial will tell a hook what means are, or were, used 13.3169 + to transfer changesets between repositories. This is 13.3170 + provided by Mercurial in a Python parameter named 13.3171 + <literal>source</literal>, or an environment variable named 13.3172 + <envar>HG_SOURCE</envar>. 13.3173 + </para> 13.3174 + 13.3175 + <itemizedlist> 13.3176 + <listitem><para id="x_287"><literal>serve</literal>: Changesets are 13.3177 + transferred to or from a remote repository over http or 13.3178 + ssh. 13.3179 + </para> 13.3180 + </listitem> 13.3181 + <listitem><para id="x_288"><literal>pull</literal>: Changesets are 13.3182 + being transferred via a pull from one repository into 13.3183 + another. 13.3184 + </para> 13.3185 + </listitem> 13.3186 + <listitem><para id="x_289"><literal>push</literal>: Changesets are 13.3187 + being transferred via a push from one repository into 13.3188 + another. 13.3189 + </para> 13.3190 + </listitem> 13.3191 + <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are 13.3192 + being transferred to or from a bundle. 13.3193 + </para> 13.3194 + </listitem></itemizedlist> 13.3195 + </sect3> 13.3196 + 13.3197 + <sect3 id="sec:hook:url"> 13.3198 + <title>Where changes are going&emdash;remote repository 13.3199 + URLs</title> 13.3200 + 13.3201 + <para id="x_28b">When possible, Mercurial will tell a hook the location 13.3202 + of the <quote>far side</quote> of an activity that transfers 13.3203 + changeset data between repositories. This is provided by 13.3204 + Mercurial in a Python parameter named 13.3205 + <literal>url</literal>, or an environment variable named 13.3206 + <envar>HG_URL</envar>. 13.3207 + </para> 13.3208 + 13.3209 + <para id="x_28c">This information is not always known. If a hook is 13.3210 + invoked in a repository that is being served via http or 13.3211 + ssh, Mercurial cannot tell where the remote repository is, 13.3212 + but it may know where the client is connecting from. In 13.3213 + such cases, the URL will take one of the following forms: 13.3214 + </para> 13.3215 + <itemizedlist> 13.3216 + <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 13.3217 + ssh client, at the IP address 13.3218 + <literal>1.2.3.4</literal>. 13.3219 + </para> 13.3220 + </listitem> 13.3221 + <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 13.3222 + http client, at the IP address 13.3223 + <literal>1.2.3.4</literal>. If the client is using SSL, 13.3224 + this will be of the form 13.3225 + <literal>remote:https:1.2.3.4</literal>. 13.3226 + </para> 13.3227 + </listitem> 13.3228 + <listitem><para id="x_28f">Empty&emdash;no information could be 13.3229 + discovered about the remote client. 13.3230 + </para> 13.3231 + </listitem></itemizedlist> 13.3232 + </sect3> 13.3233 + </sect2> 13.3234 + </sect1> 13.3235 + <sect1> 13.3236 + <title>Hook reference</title> 13.3237 + 13.3238 + <sect2 id="sec:hook:changegroup"> 13.3239 + <title><literal role="hook">changegroup</literal>&emdash;after 13.3240 + remote changesets added</title> 13.3241 + 13.3242 + <para id="x_290">This hook is run after a group of pre-existing changesets 13.3243 + has been added to the repository, for example via a <command 13.3244 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 13.3245 + unbundle</command>. This hook is run once per operation 13.3246 + that added one or more changesets. This is in contrast to the 13.3247 + <literal role="hook">incoming</literal> hook, which is run 13.3248 + once per changeset, regardless of whether the changesets 13.3249 + arrive in a group. 13.3250 + </para> 13.3251 + 13.3252 + <para id="x_291">Some possible uses for this hook include kicking off an 13.3253 + automated build or test of the added changesets, updating a 13.3254 + bug database, or notifying subscribers that a repository 13.3255 + contains new changes. 13.3256 + </para> 13.3257 + 13.3258 + <para id="x_292">Parameters to this hook: 13.3259 + </para> 13.3260 + <itemizedlist> 13.3261 + <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The 13.3262 + changeset ID of the first changeset in the group that was 13.3263 + added. All changesets between this and 13.3264 + <literal role="tag">tip</literal>, inclusive, were added by a single 13.3265 + <command role="hg-cmd">hg pull</command>, <command 13.3266 + role="hg-cmd">hg push</command> or <command 13.3267 + role="hg-cmd">hg unbundle</command>. 13.3268 + </para> 13.3269 + </listitem> 13.3270 + <listitem><para id="x_294"><literal>source</literal>: A 13.3271 + string. The source of these changes. See <xref 13.3272 + linkend="sec:hook:sources"/> for details. 13.3273 + </para> 13.3274 + </listitem> 13.3275 + <listitem><para id="x_295"><literal>url</literal>: A URL. The 13.3276 + location of the remote repository, if known. See <xref 13.3277 + linkend="sec:hook:url"/> for more information. 13.3278 + </para> 13.3279 + </listitem></itemizedlist> 13.3280 + 13.3281 + <para id="x_296">See also: <literal 13.3282 + role="hook">incoming</literal> (<xref 13.3283 + linkend="sec:hook:incoming"/>), <literal 13.3284 + role="hook">prechangegroup</literal> (<xref 13.3285 + linkend="sec:hook:prechangegroup"/>), <literal 13.3286 + role="hook">pretxnchangegroup</literal> (<xref 13.3287 + linkend="sec:hook:pretxnchangegroup"/>) 13.3288 + </para> 13.3289 + </sect2> 13.3290 + 13.3291 + <sect2 id="sec:hook:commit"> 13.3292 + <title><literal role="hook">commit</literal>&emdash;after a new 13.3293 + changeset is created</title> 13.3294 + 13.3295 + <para id="x_297">This hook is run after a new changeset has been created. 13.3296 + </para> 13.3297 + 13.3298 + <para id="x_298">Parameters to this hook: 13.3299 + </para> 13.3300 + <itemizedlist> 13.3301 + <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The 13.3302 + changeset ID of the newly committed changeset. 13.3303 + </para> 13.3304 + </listitem> 13.3305 + <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. 13.3306 + The changeset ID of the first parent of the newly 13.3307 + committed changeset. 13.3308 + </para> 13.3309 + </listitem> 13.3310 + <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. 13.3311 + The changeset ID of the second parent of the newly 13.3312 + committed changeset. 13.3313 + </para> 13.3314 + </listitem></itemizedlist> 13.3315 + 13.3316 + <para id="x_29c">See also: <literal 13.3317 + role="hook">precommit</literal> (<xref 13.3318 + linkend="sec:hook:precommit"/>), <literal 13.3319 + role="hook">pretxncommit</literal> (<xref 13.3320 + linkend="sec:hook:pretxncommit"/>) 13.3321 + </para> 13.3322 + </sect2> 13.3323 + 13.3324 + <sect2 id="sec:hook:incoming"> 13.3325 + <title><literal role="hook">incoming</literal>&emdash;after one 13.3326 + remote changeset is added</title> 13.3327 + 13.3328 + <para id="x_29d">This hook is run after a pre-existing changeset has been 13.3329 + added to the repository, for example via a <command 13.3330 + role="hg-cmd">hg push</command>. If a group of changesets 13.3331 + was added in a single operation, this hook is called once for 13.3332 + each added changeset. 13.3333 + </para> 13.3334 + 13.3335 + <para id="x_29e">You can use this hook for the same purposes as 13.3336 + the <literal role="hook">changegroup</literal> hook (<xref 13.3337 + linkend="sec:hook:changegroup"/>); it's simply more 13.3338 + convenient sometimes to run a hook once per group of 13.3339 + changesets, while other times it's handier once per changeset. 13.3340 + </para> 13.3341 + 13.3342 + <para id="x_29f">Parameters to this hook: 13.3343 + </para> 13.3344 + <itemizedlist> 13.3345 + <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The 13.3346 + ID of the newly added changeset. 13.3347 + </para> 13.3348 + </listitem> 13.3349 + <listitem><para id="x_2a1"><literal>source</literal>: A 13.3350 + string. The source of these changes. See <xref 13.3351 + linkend="sec:hook:sources"/> for details. 13.3352 + </para> 13.3353 + </listitem> 13.3354 + <listitem><para id="x_2a2"><literal>url</literal>: A URL. The 13.3355 + location of the remote repository, if known. See <xref 13.3356 + linkend="sec:hook:url"/> for more information. 13.3357 + </para> 13.3358 + </listitem></itemizedlist> 13.3359 + 13.3360 + <para id="x_2a3">See also: <literal 13.3361 + role="hook">changegroup</literal> (<xref 13.3362 + linkend="sec:hook:changegroup"/>) <literal 13.3363 + role="hook">prechangegroup</literal> (<xref 13.3364 + linkend="sec:hook:prechangegroup"/>), <literal 13.3365 + role="hook">pretxnchangegroup</literal> (<xref 13.3366 + linkend="sec:hook:pretxnchangegroup"/>) 13.3367 + </para> 13.3368 + </sect2> 13.3369 + 13.3370 + <sect2 id="sec:hook:outgoing"> 13.3371 + <title><literal role="hook">outgoing</literal>&emdash;after 13.3372 + changesets are propagated</title> 13.3373 + 13.3374 + <para id="x_2a4">This hook is run after a group of changesets has been 13.3375 + propagated out of this repository, for example by a <command 13.3376 + role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 13.3377 + bundle</command> command. 13.3378 + </para> 13.3379 + 13.3380 + <para id="x_2a5">One possible use for this hook is to notify administrators 13.3381 + that changes have been pulled. 13.3382 + </para> 13.3383 + 13.3384 + <para id="x_2a6">Parameters to this hook: 13.3385 + </para> 13.3386 + <itemizedlist> 13.3387 + <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The 13.3388 + changeset ID of the first changeset of the group that was 13.3389 + sent. 13.3390 + </para> 13.3391 + </listitem> 13.3392 + <listitem><para id="x_2a8"><literal>source</literal>: A string. The 13.3393 + source of the of the operation (see <xref 13.3394 + linkend="sec:hook:sources"/>). If a remote 13.3395 + client pulled changes from this repository, 13.3396 + <literal>source</literal> will be 13.3397 + <literal>serve</literal>. If the client that obtained 13.3398 + changes from this repository was local, 13.3399 + <literal>source</literal> will be 13.3400 + <literal>bundle</literal>, <literal>pull</literal>, or 13.3401 + <literal>push</literal>, depending on the operation the 13.3402 + client performed. 13.3403 + </para> 13.3404 + </listitem> 13.3405 + <listitem><para id="x_2a9"><literal>url</literal>: A URL. The 13.3406 + location of the remote repository, if known. See <xref 13.3407 + linkend="sec:hook:url"/> for more information. 13.3408 + </para> 13.3409 + </listitem></itemizedlist> 13.3410 + 13.3411 + <para id="x_2aa">See also: <literal 13.3412 + role="hook">preoutgoing</literal> (<xref 13.3413 + linkend="sec:hook:preoutgoing"/>) 13.3414 + </para> 13.3415 + </sect2> 13.3416 + 13.3417 + <sect2 id="sec:hook:prechangegroup"> 13.3418 + <title><literal 13.3419 + role="hook">prechangegroup</literal>&emdash;before starting 13.3420 + to add remote changesets</title> 13.3421 + 13.3422 + <para id="x_2ab">This controlling hook is run before Mercurial begins to 13.3423 + add a group of changesets from another repository. 13.3424 + </para> 13.3425 + 13.3426 + <para id="x_2ac">This hook does not have any information about the 13.3427 + changesets to be added, because it is run before transmission 13.3428 + of those changesets is allowed to begin. If this hook fails, 13.3429 + the changesets will not be transmitted. 13.3430 + </para> 13.3431 + 13.3432 + <para id="x_2ad">One use for this hook is to prevent external changes from 13.3433 + being added to a repository. For example, you could use this 13.3434 + to <quote>freeze</quote> a server-hosted branch temporarily or 13.3435 + permanently so that users cannot push to it, while still 13.3436 + allowing a local administrator to modify the repository. 13.3437 + </para> 13.3438 + 13.3439 + <para id="x_2ae">Parameters to this hook: 13.3440 + </para> 13.3441 + <itemizedlist> 13.3442 + <listitem><para id="x_2af"><literal>source</literal>: A string. The 13.3443 + source of these changes. See <xref 13.3444 + linkend="sec:hook:sources"/> for details. 13.3445 + </para> 13.3446 + </listitem> 13.3447 + <listitem><para id="x_2b0"><literal>url</literal>: A URL. The 13.3448 + location of the remote repository, if known. See <xref 13.3449 + linkend="sec:hook:url"/> for more information. 13.3450 + </para> 13.3451 + </listitem></itemizedlist> 13.3452 + 13.3453 + <para id="x_2b1">See also: <literal 13.3454 + role="hook">changegroup</literal> (<xref 13.3455 + linkend="sec:hook:changegroup"/>), <literal 13.3456 + role="hook">incoming</literal> (<xref 13.3457 + linkend="sec:hook:incoming"/>), <literal 13.3458 + role="hook">pretxnchangegroup</literal> (<xref 13.3459 + linkend="sec:hook:pretxnchangegroup"/>) 13.3460 + </para> 13.3461 + </sect2> 13.3462 + 13.3463 + <sect2 id="sec:hook:precommit"> 13.3464 + <title><literal role="hook">precommit</literal>&emdash;before 13.3465 + starting to commit a changeset</title> 13.3466 + 13.3467 + <para id="x_2b2">This hook is run before Mercurial begins to commit a new 13.3468 + changeset. It is run before Mercurial has any of the metadata 13.3469 + for the commit, such as the files to be committed, the commit 13.3470 + message, or the commit date. 13.3471 + </para> 13.3472 + 13.3473 + <para id="x_2b3">One use for this hook is to disable the ability to commit 13.3474 + new changesets, while still allowing incoming changesets. 13.3475 + Another is to run a build or test, and only allow the commit 13.3476 + to begin if the build or test succeeds. 13.3477 + </para> 13.3478 + 13.3479 + <para id="x_2b4">Parameters to this hook: 13.3480 + </para> 13.3481 + <itemizedlist> 13.3482 + <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. 13.3483 + The changeset ID of the first parent of the working 13.3484 + directory. 13.3485 + </para> 13.3486 + </listitem> 13.3487 + <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. 13.3488 + The changeset ID of the second parent of the working 13.3489 + directory. 13.3490 + </para> 13.3491 + </listitem></itemizedlist> 13.3492 + <para id="x_2b7">If the commit proceeds, the parents of the working 13.3493 + directory will become the parents of the new changeset. 13.3494 + </para> 13.3495 + 13.3496 + <para id="x_2b8">See also: <literal role="hook">commit</literal> 13.3497 + (<xref linkend="sec:hook:commit"/>), <literal 13.3498 + role="hook">pretxncommit</literal> (<xref 13.3499 + linkend="sec:hook:pretxncommit"/>) 13.3500 + </para> 13.3501 + </sect2> 13.3502 + 13.3503 + <sect2 id="sec:hook:preoutgoing"> 13.3504 + <title><literal role="hook">preoutgoing</literal>&emdash;before 13.3505 + starting to propagate changesets</title> 13.3506 + 13.3507 + <para id="x_2b9">This hook is invoked before Mercurial knows the identities 13.3508 + of the changesets to be transmitted. 13.3509 + </para> 13.3510 + 13.3511 + <para id="x_2ba">One use for this hook is to prevent changes from being 13.3512 + transmitted to another repository. 13.3513 + </para> 13.3514 + 13.3515 + <para id="x_2bb">Parameters to this hook: 13.3516 + </para> 13.3517 + <itemizedlist> 13.3518 + <listitem><para id="x_2bc"><literal>source</literal>: A 13.3519 + string. The source of the operation that is attempting to 13.3520 + obtain changes from this repository (see <xref 13.3521 + linkend="sec:hook:sources"/>). See the documentation 13.3522 + for the <literal>source</literal> parameter to the 13.3523 + <literal role="hook">outgoing</literal> hook, in 13.3524 + <xref linkend="sec:hook:outgoing"/>, for possible values 13.3525 + of this parameter. 13.3526 + </para> 13.3527 + </listitem> 13.3528 + <listitem><para id="x_2bd"><literal>url</literal>: A URL. The 13.3529 + location of the remote repository, if known. See <xref 13.3530 + linkend="sec:hook:url"/> for more information. 13.3531 + </para> 13.3532 + </listitem></itemizedlist> 13.3533 + 13.3534 + <para id="x_2be">See also: <literal 13.3535 + role="hook">outgoing</literal> (<xref 13.3536 + linkend="sec:hook:outgoing"/>) 13.3537 + </para> 13.3538 + </sect2> 13.3539 + 13.3540 + <sect2 id="sec:hook:pretag"> 13.3541 + <title><literal role="hook">pretag</literal>&emdash;before 13.3542 + tagging a changeset</title> 13.3543 + 13.3544 + <para id="x_2bf">This controlling hook is run before a tag is created. If 13.3545 + the hook succeeds, creation of the tag proceeds. If the hook 13.3546 + fails, the tag is not created. 13.3547 + </para> 13.3548 + 13.3549 + <para id="x_2c0">Parameters to this hook: 13.3550 + </para> 13.3551 + <itemizedlist> 13.3552 + <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether 13.3553 + the tag is local to this repository instance (i.e. stored 13.3554 + in <filename role="special">.hg/localtags</filename>) or 13.3555 + managed by Mercurial (stored in <filename 13.3556 + role="special">.hgtags</filename>). 13.3557 + </para> 13.3558 + </listitem> 13.3559 + <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The 13.3560 + ID of the changeset to be tagged. 13.3561 + </para> 13.3562 + </listitem> 13.3563 + <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of 13.3564 + the tag to be created. 13.3565 + </para> 13.3566 + </listitem></itemizedlist> 13.3567 + 13.3568 + <para id="x_2c4">If the tag to be created is 13.3569 + revision-controlled, the <literal 13.3570 + role="hook">precommit</literal> and <literal 13.3571 + role="hook">pretxncommit</literal> hooks (<xref 13.3572 + linkend="sec:hook:commit"/> and <xref 13.3573 + linkend="sec:hook:pretxncommit"/>) will also be run. 13.3574 + </para> 13.3575 + 13.3576 + <para id="x_2c5">See also: <literal role="hook">tag</literal> 13.3577 + (<xref linkend="sec:hook:tag"/>) 13.3578 + </para> 13.3579 + </sect2> 13.3580 + 13.3581 + <sect2 id="sec:hook:pretxnchangegroup"> 13.3582 + <title><literal 13.3583 + role="hook">pretxnchangegroup</literal>&emdash;before 13.3584 + completing addition of remote changesets</title> 13.3585 + 13.3586 + <para id="x_2c6">This controlling hook is run before a 13.3587 + transaction&emdash;that manages the addition of a group of new 13.3588 + changesets from outside the repository&emdash;completes. If 13.3589 + the hook succeeds, the transaction completes, and all of the 13.3590 + changesets become permanent within this repository. If the 13.3591 + hook fails, the transaction is rolled back, and the data for 13.3592 + the changesets is erased. 13.3593 + </para> 13.3594 + 13.3595 + <para id="x_2c7">This hook can access the metadata associated with the 13.3596 + almost-added changesets, but it should not do anything 13.3597 + permanent with this data. It must also not modify the working 13.3598 + directory. 13.3599 + </para> 13.3600 + 13.3601 + <para id="x_2c8">While this hook is running, if other Mercurial processes 13.3602 + access this repository, they will be able to see the 13.3603 + almost-added changesets as if they are permanent. This may 13.3604 + lead to race conditions if you do not take steps to avoid 13.3605 + them. 13.3606 + </para> 13.3607 + 13.3608 + <para id="x_2c9">This hook can be used to automatically vet a group of 13.3609 + changesets. If the hook fails, all of the changesets are 13.3610 + <quote>rejected</quote> when the transaction rolls back. 13.3611 + </para> 13.3612 + 13.3613 + <para id="x_2ca">Parameters to this hook: 13.3614 + </para> 13.3615 + <itemizedlist> 13.3616 + <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The 13.3617 + changeset ID of the first changeset in the group that was 13.3618 + added. All changesets between this and 13.3619 + <literal role="tag">tip</literal>, 13.3620 + inclusive, were added by a single <command 13.3621 + role="hg-cmd">hg pull</command>, <command 13.3622 + role="hg-cmd">hg push</command> or <command 13.3623 + role="hg-cmd">hg unbundle</command>. 13.3624 + </para> 13.3625 + </listitem> 13.3626 + <listitem><para id="x_2cc"><literal>source</literal>: A 13.3627 + string. The source of these changes. See <xref 13.3628 + linkend="sec:hook:sources"/> for details. 13.3629 + </para> 13.3630 + </listitem> 13.3631 + <listitem><para id="x_2cd"><literal>url</literal>: A URL. The 13.3632 + location of the remote repository, if known. See <xref 13.3633 + linkend="sec:hook:url"/> for more information. 13.3634 + </para> 13.3635 + </listitem></itemizedlist> 13.3636 + 13.3637 + <para id="x_2ce">See also: <literal 13.3638 + role="hook">changegroup</literal> (<xref 13.3639 + linkend="sec:hook:changegroup"/>), <literal 13.3640 + role="hook">incoming</literal> (<xref 13.3641 + linkend="sec:hook:incoming"/>), <literal 13.3642 + role="hook">prechangegroup</literal> (<xref 13.3643 + linkend="sec:hook:prechangegroup"/>) 13.3644 + </para> 13.3645 + </sect2> 13.3646 + 13.3647 + <sect2 id="sec:hook:pretxncommit"> 13.3648 + <title><literal role="hook">pretxncommit</literal>&emdash;before 13.3649 + completing commit of new changeset</title> 13.3650 + 13.3651 + <para id="x_2cf">This controlling hook is run before a 13.3652 + transaction&emdash;that manages a new commit&emdash;completes. 13.3653 + If the hook succeeds, the transaction completes and the 13.3654 + changeset becomes permanent within this repository. If the 13.3655 + hook fails, the transaction is rolled back, and the commit 13.3656 + data is erased. 13.3657 + </para> 13.3658 + 13.3659 + <para id="x_2d0">This hook can access the metadata associated with the 13.3660 + almost-new changeset, but it should not do anything permanent 13.3661 + with this data. It must also not modify the working 13.3662 + directory. 13.3663 + </para> 13.3664 + 13.3665 + <para id="x_2d1">While this hook is running, if other Mercurial processes 13.3666 + access this repository, they will be able to see the 13.3667 + almost-new changeset as if it is permanent. This may lead to 13.3668 + race conditions if you do not take steps to avoid them. 13.3669 + </para> 13.3670 + 13.3671 + <para id="x_2d2">Parameters to this hook:</para> 13.3672 + 13.3673 + <itemizedlist> 13.3674 + <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 13.3675 + changeset ID of the newly committed changeset. 13.3676 + </para> 13.3677 + </listitem> 13.3678 + <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. 13.3679 + The changeset ID of the first parent of the newly 13.3680 + committed changeset. 13.3681 + </para> 13.3682 + </listitem> 13.3683 + <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. 13.3684 + The changeset ID of the second parent of the newly 13.3685 + committed changeset. 13.3686 + </para> 13.3687 + </listitem></itemizedlist> 13.3688 + 13.3689 + <para id="x_2d6">See also: <literal 13.3690 + role="hook">precommit</literal> (<xref 13.3691 + linkend="sec:hook:precommit"/>) 13.3692 + </para> 13.3693 + </sect2> 13.3694 + 13.3695 + <sect2 id="sec:hook:preupdate"> 13.3696 + <title><literal role="hook">preupdate</literal>&emdash;before 13.3697 + updating or merging working directory</title> 13.3698 + 13.3699 + <para id="x_2d7">This controlling hook is run before an update 13.3700 + or merge of the working directory begins. It is run only if 13.3701 + Mercurial's normal pre-update checks determine that the update 13.3702 + or merge can proceed. If the hook succeeds, the update or 13.3703 + merge may proceed; if it fails, the update or merge does not 13.3704 + start. 13.3705 + </para> 13.3706 + 13.3707 + <para id="x_2d8">Parameters to this hook: 13.3708 + </para> 13.3709 + <itemizedlist> 13.3710 + <listitem><para id="x_2d9"><literal>parent1</literal>: A 13.3711 + changeset ID. The ID of the parent that the working 13.3712 + directory is to be updated to. If the working directory 13.3713 + is being merged, it will not change this parent. 13.3714 + </para> 13.3715 + </listitem> 13.3716 + <listitem><para id="x_2da"><literal>parent2</literal>: A 13.3717 + changeset ID. Only set if the working directory is being 13.3718 + merged. The ID of the revision that the working directory 13.3719 + is being merged with. 13.3720 + </para> 13.3721 + </listitem></itemizedlist> 13.3722 + 13.3723 + <para id="x_2db">See also: <literal role="hook">update</literal> 13.3724 + (<xref linkend="sec:hook:update"/>)</para> 13.3725 + </sect2> 13.3726 + 13.3727 + <sect2 id="sec:hook:tag"> 13.3728 + <title><literal role="hook">tag</literal>&emdash;after tagging a 13.3729 + changeset</title> 13.3730 + 13.3731 + <para id="x_2dc">This hook is run after a tag has been created. 13.3732 + </para> 13.3733 + 13.3734 + <para id="x_2dd">Parameters to this hook: 13.3735 + </para> 13.3736 + <itemizedlist> 13.3737 + <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether 13.3738 + the new tag is local to this repository instance (i.e. 13.3739 + stored in <filename 13.3740 + role="special">.hg/localtags</filename>) or managed by 13.3741 + Mercurial (stored in <filename 13.3742 + role="special">.hgtags</filename>). 13.3743 + </para> 13.3744 + </listitem> 13.3745 + <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The 13.3746 + ID of the changeset that was tagged. 13.3747 + </para> 13.3748 + </listitem> 13.3749 + <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of 13.3750 + the tag that was created. 13.3751 + </para> 13.3752 + </listitem></itemizedlist> 13.3753 + 13.3754 + <para id="x_2e1">If the created tag is revision-controlled, the <literal 13.3755 + role="hook">commit</literal> hook (section <xref 13.3756 + linkend="sec:hook:commit"/>) is run before this hook. 13.3757 + </para> 13.3758 + 13.3759 + <para id="x_2e2">See also: <literal role="hook">pretag</literal> 13.3760 + (<xref linkend="sec:hook:pretag"/>) 13.3761 + </para> 13.3762 + </sect2> 13.3763 + 13.3764 + <sect2 id="sec:hook:update"> 13.3765 + <title><literal role="hook">update</literal>&emdash;after 13.3766 + updating or merging working directory</title> 13.3767 + 13.3768 + <para id="x_2e3">This hook is run after an update or merge of the working 13.3769 + directory completes. Since a merge can fail (if the external 13.3770 + <command>hgmerge</command> command fails to resolve conflicts 13.3771 + in a file), this hook communicates whether the update or merge 13.3772 + completed cleanly. 13.3773 + </para> 13.3774 + 13.3775 + <itemizedlist> 13.3776 + <listitem><para id="x_2e4"><literal>error</literal>: A boolean. 13.3777 + Indicates whether the update or merge completed 13.3778 + successfully. 13.3779 + </para> 13.3780 + </listitem> 13.3781 + <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. 13.3782 + The ID of the parent that the working directory was 13.3783 + updated to. If the working directory was merged, it will 13.3784 + not have changed this parent. 13.3785 + </para> 13.3786 + </listitem> 13.3787 + <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. 13.3788 + Only set if the working directory was merged. The ID of 13.3789 + the revision that the working directory was merged with. 13.3790 + </para> 13.3791 + </listitem></itemizedlist> 13.3792 + 13.3793 + <para id="x_2e7">See also: <literal role="hook">preupdate</literal> 13.3794 + (<xref linkend="sec:hook:preupdate"/>) 13.3795 + </para> 13.3796 + 13.3797 + </sect2> 13.3798 + </sect1> 13.3799 </chapter> 13.3800 13.3801 <!-- 13.3802 local variables: 13.3803 sgml-parent-document: ("00book.xml" "book" "chapter") 13.3804 end: 13.3805 ---> 13.3806 \ No newline at end of file 13.3807 +-->
14.1 --- a/fr/ch11-template.xml Sat Sep 12 17:58:26 2009 +0200 14.2 +++ b/fr/ch11-template.xml Sat Sep 12 17:58:56 2009 +0200 14.3 @@ -1,689 +1,685 @@ 14.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 14.5 14.6 -<chapter> 14.7 -<title>Customising the output of Mercurial</title> 14.8 -<para>\label{chap:template}</para> 14.9 - 14.10 -<para>Mercurial provides a powerful mechanism to let you control how it 14.11 -displays information. The mechanism is based on templates. You can 14.12 -use templates to generate specific output for a single command, or to 14.13 -customise the entire appearance of the built-in web interface.</para> 14.14 - 14.15 -<sect1> 14.16 -<title>Using precanned output styles</title> 14.17 -<para>\label{sec:style}</para> 14.18 - 14.19 -<para>Packaged with Mercurial are some output styles that you can use 14.20 -immediately. A style is simply a precanned template that someone 14.21 -wrote and installed somewhere that Mercurial can find.</para> 14.22 - 14.23 -<para>Before we take a look at Mercurial's bundled styles, let's review its 14.24 -normal output.</para> 14.25 - 14.26 -<para><!-- &interaction.template.simple.normal; --></para> 14.27 - 14.28 -<para>This is somewhat informative, but it takes up a lot of space&emdash;five 14.29 -lines of output per changeset. The <literal>compact</literal> style reduces 14.30 -this to three lines, presented in a sparse manner.</para> 14.31 - 14.32 -<para><!-- &interaction.template.simple.compact; --></para> 14.33 - 14.34 -<para>The <literal>changelog</literal> style hints at the expressive power of 14.35 -Mercurial's templating engine. This style attempts to follow the GNU 14.36 -Project's changelog guidelines<citation>web:changelog</citation>. 14.37 -</para> 14.38 - 14.39 -<para><!-- &interaction.template.simple.changelog; --> 14.40 -</para> 14.41 - 14.42 -<para>You will not be shocked to learn that Mercurial's default output style 14.43 -is named <literal>default</literal>. 14.44 -</para> 14.45 - 14.46 -<sect2> 14.47 -<title>Setting a default style</title> 14.48 - 14.49 -<para>You can modify the output style that Mercurial will use for every 14.50 -command by editing your <filename role="special"> /.hgrc</filename>\ file, naming the style you would 14.51 -prefer to use. 14.52 -</para> 14.53 - 14.54 -<programlisting> 14.55 -<para> [ui] 14.56 - style = compact 14.57 -</para> 14.58 -</programlisting> 14.59 - 14.60 -<para>If you write a style of your own, you can use it by either providing 14.61 -the path to your style file, or copying your style file into a 14.62 -location where Mercurial can find it (typically the <literal>templates</literal> 14.63 -subdirectory of your Mercurial install directory). 14.64 -</para> 14.65 - 14.66 -</sect2> 14.67 -</sect1> 14.68 -<sect1> 14.69 -<title>Commands that support styles and templates</title> 14.70 - 14.71 -<para>All of Mercurial's <quote><literal>log</literal>-like</quote> commands let you use styles 14.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 14.73 -<command role="hg-cmd">hg tip</command>. 14.74 -</para> 14.75 - 14.76 -<para>As I write this manual, these are so far the only commands that 14.77 -support styles and templates. Since these are the most important 14.78 -commands that need customisable output, there has been little pressure 14.79 -from the Mercurial user community to add style and template support to 14.80 -other commands. 14.81 -</para> 14.82 - 14.83 -</sect1> 14.84 -<sect1> 14.85 -<title>The basics of templating</title> 14.86 - 14.87 -<para>At its simplest, a Mercurial template is a piece of text. Some of the 14.88 -text never changes, while other parts are <emphasis>expanded</emphasis>, or replaced 14.89 -with new text, when necessary. 14.90 -</para> 14.91 - 14.92 -<para>Before we continue, let's look again at a simple example of 14.93 -Mercurial's normal output. 14.94 -</para> 14.95 - 14.96 -<para><!-- &interaction.template.simple.normal; --> 14.97 -</para> 14.98 - 14.99 -<para>Now, let's run the same command, but using a template to change its 14.100 -output. 14.101 -</para> 14.102 - 14.103 -<para><!-- &interaction.template.simple.simplest; --> 14.104 -</para> 14.105 - 14.106 -<para>The example above illustrates the simplest possible template; it's 14.107 -just a piece of static text, printed once for each changeset. The 14.108 -<option role="hg-opt-log">--template</option> option to the <command role="hg-cmd">hg log</command> command tells 14.109 -Mercurial to use the given text as the template when printing each 14.110 -changeset. 14.111 -</para> 14.112 - 14.113 -<para>Notice that the template string above ends with the text 14.114 -<quote><literal>\n</literal></quote>. This is an <emphasis>escape sequence</emphasis>, telling Mercurial 14.115 -to print a newline at the end of each template item. If you omit this 14.116 -newline, Mercurial will run each piece of output together. See 14.117 -section <xref linkend="sec:template:escape"/> for more details of escape sequences. 14.118 -</para> 14.119 - 14.120 -<para>A template that prints a fixed string of text all the time isn't very 14.121 -useful; let's try something a bit more complex. 14.122 -</para> 14.123 - 14.124 -<para><!-- &interaction.template.simple.simplesub; --> 14.125 -</para> 14.126 - 14.127 -<para>As you can see, the string <quote><literal>{desc}</literal></quote> in the template has been 14.128 -replaced in the output with the description of each changeset. Every 14.129 -time Mercurial finds text enclosed in curly braces (<quote><literal>{</literal></quote> 14.130 -and <quote>\texttt{}}</quote>), it will try to replace the braces and text with 14.131 -the expansion of whatever is inside. To print a literal curly brace, 14.132 -you must escape it, as described in section <xref linkend="sec:template:escape"/>. 14.133 -</para> 14.134 - 14.135 -</sect1> 14.136 -<sect1> 14.137 -<title>Common template keywords</title> 14.138 -<para>\label{sec:template:keyword} 14.139 -</para> 14.140 - 14.141 -<para>You can start writing simple templates immediately using the keywords 14.142 -below. 14.143 -</para> 14.144 - 14.145 -<itemizedlist> 14.146 -<listitem><para><literal role="template-keyword">author</literal>: String. The unmodified author of the changeset. 14.147 -</para> 14.148 -</listitem> 14.149 -<listitem><para><literal role="template-keyword">branches</literal>: String. The name of the branch on which 14.150 - the changeset was committed. Will be empty if the branch name was 14.151 - <literal>default</literal>. 14.152 -</para> 14.153 -</listitem> 14.154 -<listitem><para><literal role="template-keyword">date</literal>: Date information. The date when the changeset 14.155 - was committed. This is <emphasis>not</emphasis> human-readable; you must pass it 14.156 - through a filter that will render it appropriately. See 14.157 - section <xref linkend="sec:template:filter"/> for more information on filters. 14.158 - The date is expressed as a pair of numbers. The first number is a 14.159 - Unix UTC timestamp (seconds since January 1, 1970); the second is 14.160 - the offset of the committer's timezone from UTC, in seconds. 14.161 -</para> 14.162 -</listitem> 14.163 -<listitem><para><literal role="template-keyword">desc</literal>: String. The text of the changeset description. 14.164 -</para> 14.165 -</listitem> 14.166 -<listitem><para><literal role="template-keyword">files</literal>: List of strings. All files modified, added, or 14.167 - removed by this changeset. 14.168 -</para> 14.169 -</listitem> 14.170 -<listitem><para><literal role="template-keyword">file_adds</literal>: List of strings. Files added by this 14.171 - changeset. 14.172 -</para> 14.173 -</listitem> 14.174 -<listitem><para><literal role="template-keyword">file_dels</literal>: List of strings. Files removed by this 14.175 - changeset. 14.176 -</para> 14.177 -</listitem> 14.178 -<listitem><para><literal role="template-keyword">node</literal>: String. The changeset identification hash, as a 14.179 - 40-character hexadecimal string. 14.180 -</para> 14.181 -</listitem> 14.182 -<listitem><para><literal role="template-keyword">parents</literal>: List of strings. The parents of the 14.183 - changeset. 14.184 -</para> 14.185 -</listitem> 14.186 -<listitem><para><literal role="template-keyword">rev</literal>: Integer. The repository-local changeset revision 14.187 - number. 14.188 -</para> 14.189 -</listitem> 14.190 -<listitem><para><literal role="template-keyword">tags</literal>: List of strings. Any tags associated with the 14.191 - changeset. 14.192 -</para> 14.193 -</listitem></itemizedlist> 14.194 - 14.195 -<para>A few simple experiments will show us what to expect when we use these 14.196 -keywords; you can see the results in 14.197 -figure <xref linkend="fig:template:keywords"/>. 14.198 -</para> 14.199 - 14.200 -<informalfigure> 14.201 -<para> <!-- &interaction.template.simple.keywords; --> 14.202 - <caption><para>Template keywords in use</para></caption> 14.203 - \label{fig:template:keywords} 14.204 -</para> 14.205 -</informalfigure> 14.206 - 14.207 -<para>As we noted above, the date keyword does not produce human-readable 14.208 -output, so we must treat it specially. This involves using a 14.209 -<emphasis>filter</emphasis>, about which more in section <xref linkend="sec:template:filter"/>. 14.210 -</para> 14.211 - 14.212 -<para><!-- &interaction.template.simple.datekeyword; --> 14.213 -</para> 14.214 - 14.215 -</sect1> 14.216 -<sect1> 14.217 -<title>Escape sequences</title> 14.218 -<para>\label{sec:template:escape} 14.219 -</para> 14.220 - 14.221 -<para>Mercurial's templating engine recognises the most commonly used escape 14.222 -sequences in strings. When it sees a backslash (<quote><literal>\</literal></quote>) 14.223 -character, it looks at the following character and substitutes the two 14.224 -characters with a single replacement, as described below. 14.225 -</para> 14.226 - 14.227 -<itemizedlist> 14.228 -<listitem><para><literal>\textbackslash\textbackslash</literal>: Backslash, <quote><literal>\</literal></quote>, 14.229 - ASCII 134. 14.230 -</para> 14.231 -</listitem> 14.232 -<listitem><para><literal>\textbackslash n</literal>: Newline, ASCII 12. 14.233 -</para> 14.234 -</listitem> 14.235 -<listitem><para><literal>\textbackslash r</literal>: Carriage return, ASCII 15. 14.236 -</para> 14.237 -</listitem> 14.238 -<listitem><para><literal>\textbackslash t</literal>: Tab, ASCII 11. 14.239 -</para> 14.240 -</listitem> 14.241 -<listitem><para><literal>\textbackslash v</literal>: Vertical tab, ASCII 13. 14.242 -</para> 14.243 -</listitem> 14.244 -<listitem><para><literal>\textbackslash {</literal>: Open curly brace, <quote><literal>{</literal></quote>, ASCII 173. 14.245 -</para> 14.246 -</listitem> 14.247 -<listitem><para><literal>\textbackslash }</literal>: Close curly brace, <quote><literal>}</literal></quote>, ASCII 175. 14.248 -</para> 14.249 -</listitem></itemizedlist> 14.250 - 14.251 -<para>As indicated above, if you want the expansion of a template to contain 14.252 -a literal <quote><literal>\</literal></quote>, <quote><literal>{</literal></quote>, or <quote><literal>{</literal></quote> character, you 14.253 -must escape it. 14.254 -</para> 14.255 - 14.256 -</sect1> 14.257 -<sect1> 14.258 -<title>Filtering keywords to change their results</title> 14.259 -<para>\label{sec:template:filter} 14.260 -</para> 14.261 - 14.262 -<para>Some of the results of template expansion are not immediately easy to 14.263 -use. Mercurial lets you specify an optional chain of <emphasis>filters</emphasis> 14.264 -to modify the result of expanding a keyword. You have already seen a 14.265 -common filter, <literal role="template-kw-filt-date">isodate</literal>, in action above, to make a 14.266 -date readable. 14.267 -</para> 14.268 - 14.269 -<para>Below is a list of the most commonly used filters that Mercurial 14.270 -supports. While some filters can be applied to any text, others can 14.271 -only be used in specific circumstances. The name of each filter is 14.272 -followed first by an indication of where it can be used, then a 14.273 -description of its effect. 14.274 -</para> 14.275 - 14.276 -<itemizedlist> 14.277 -<listitem><para><literal role="template-filter">addbreaks</literal>: Any text. Add an XHTML <quote><literal><br/></literal></quote> 14.278 - tag before the end of every line except the last. For example, 14.279 - <quote><literal>foo\nbar</literal></quote> becomes <quote><literal>foo<br/>\nbar</literal></quote>. 14.280 -</para> 14.281 -</listitem> 14.282 -<listitem><para><literal role="template-kw-filt-date">age</literal>: <literal role="template-keyword">date</literal> keyword. Render the 14.283 - age of the date, relative to the current time. Yields a string like 14.284 - <quote><literal>10 minutes</literal></quote>. 14.285 -</para> 14.286 -</listitem> 14.287 -<listitem><para><literal role="template-filter">basename</literal>: Any text, but most useful for the 14.288 - <literal role="template-keyword">files</literal> keyword and its relatives. Treat the text as a 14.289 - path, and return the basename. For example, <quote><literal>foo/bar/baz</literal></quote> 14.290 - becomes <quote><literal>baz</literal></quote>. 14.291 -</para> 14.292 -</listitem> 14.293 -<listitem><para><literal role="template-kw-filt-date">date</literal>: <literal role="template-keyword">date</literal> keyword. Render a date 14.294 - in a similar format to the Unix <literal role="template-keyword">date</literal> command, but with 14.295 - timezone included. Yields a string like 14.296 - <quote><literal>Mon Sep 04 15:13:13 2006 -0700</literal></quote>. 14.297 -</para> 14.298 -</listitem> 14.299 -<listitem><para><literal role="template-kw-filt-author">domain</literal>: Any text, but most useful for the 14.300 - <literal role="template-keyword">author</literal> keyword. Finds the first string that looks like 14.301 - an email address, and extract just the domain component. For 14.302 - example, <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 14.303 - <quote><literal>serpentine.com</literal></quote>. 14.304 -</para> 14.305 -</listitem> 14.306 -<listitem><para><literal role="template-kw-filt-author">email</literal>: Any text, but most useful for the 14.307 - <literal role="template-keyword">author</literal> keyword. Extract the first string that looks like 14.308 - an email address. For example, 14.309 - <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 14.310 - <quote><literal>bos@serpentine.com</literal></quote>. 14.311 -</para> 14.312 -</listitem> 14.313 -<listitem><para><literal role="template-filter">escape</literal>: Any text. Replace the special XML/XHTML 14.314 - characters <quote><literal>&</literal></quote>, <quote><literal><</literal></quote> and <quote><literal>></literal></quote> with 14.315 - XML entities. 14.316 -</para> 14.317 -</listitem> 14.318 -<listitem><para><literal role="template-filter">fill68</literal>: Any text. Wrap the text to fit in 68 14.319 - columns. This is useful before you pass text through the 14.320 - <literal role="template-filter">tabindent</literal> filter, and still want it to fit in an 14.321 - 80-column fixed-font window. 14.322 -</para> 14.323 -</listitem> 14.324 -<listitem><para><literal role="template-filter">fill76</literal>: Any text. Wrap the text to fit in 76 14.325 - columns. 14.326 -</para> 14.327 -</listitem> 14.328 -<listitem><para><literal role="template-filter">firstline</literal>: Any text. Yield the first line of text, 14.329 - without any trailing newlines. 14.330 -</para> 14.331 -</listitem> 14.332 -<listitem><para><literal role="template-kw-filt-date">hgdate</literal>: <literal role="template-keyword">date</literal> keyword. Render the 14.333 - date as a pair of readable numbers. Yields a string like 14.334 - <quote><literal>1157407993 25200</literal></quote>. 14.335 -</para> 14.336 -</listitem> 14.337 -<listitem><para><literal role="template-kw-filt-date">isodate</literal>: <literal role="template-keyword">date</literal> keyword. Render the 14.338 - date as a text string in ISO 8601 format. Yields a string like 14.339 - <quote><literal>2006-09-04 15:13:13 -0700</literal></quote>. 14.340 -</para> 14.341 -</listitem> 14.342 -<listitem><para><literal role="template-filter">obfuscate</literal>: Any text, but most useful for the 14.343 - <literal role="template-keyword">author</literal> keyword. Yield the input text rendered as a 14.344 - sequence of XML entities. This helps to defeat some particularly 14.345 - stupid screen-scraping email harvesting spambots. 14.346 -</para> 14.347 -</listitem> 14.348 -<listitem><para><literal role="template-kw-filt-author">person</literal>: Any text, but most useful for the 14.349 - <literal role="template-keyword">author</literal> keyword. Yield the text before an email address. 14.350 - For example, <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> 14.351 - becomes <quote><literal>Bryan O'Sullivan</literal></quote>. 14.352 -</para> 14.353 -</listitem> 14.354 -<listitem><para><literal role="template-kw-filt-date">rfc822date</literal>: <literal role="template-keyword">date</literal> keyword. Render a 14.355 - date using the same format used in email headers. Yields a string 14.356 - like <quote><literal>Mon, 04 Sep 2006 15:13:13 -0700</literal></quote>. 14.357 -</para> 14.358 -</listitem> 14.359 -<listitem><para><literal role="template-kw-filt-node">short</literal>: Changeset hash. Yield the short form 14.360 - of a changeset hash, i.e. a 12-character hexadecimal string. 14.361 -</para> 14.362 -</listitem> 14.363 -<listitem><para><literal role="template-kw-filt-date">shortdate</literal>: <literal role="template-keyword">date</literal> keyword. Render 14.364 - the year, month, and day of the date. Yields a string like 14.365 - <quote><literal>2006-09-04</literal></quote>. 14.366 -</para> 14.367 -</listitem> 14.368 -<listitem><para><literal role="template-filter">strip</literal>: Any text. Strip all leading and trailing 14.369 - whitespace from the string. 14.370 -</para> 14.371 -</listitem> 14.372 -<listitem><para><literal role="template-filter">tabindent</literal>: Any text. Yield the text, with every line 14.373 - except the first starting with a tab character. 14.374 -</para> 14.375 -</listitem> 14.376 -<listitem><para><literal role="template-filter">urlescape</literal>: Any text. Escape all characters that are 14.377 - considered <quote>special</quote> by URL parsers. For example, <literal>foo bar</literal> 14.378 - becomes <literal>foo%20bar</literal>. 14.379 -</para> 14.380 -</listitem> 14.381 -<listitem><para><literal role="template-kw-filt-author">user</literal>: Any text, but most useful for the 14.382 - <literal role="template-keyword">author</literal> keyword. Return the <quote>user</quote> portion of an email 14.383 - address. For example, 14.384 - <quote><literal>Bryan O'Sullivan <bos@serpentine.com></literal></quote> becomes 14.385 - <quote><literal>bos</literal></quote>. 14.386 -</para> 14.387 -</listitem></itemizedlist> 14.388 - 14.389 -<informalfigure> 14.390 -<para> <!-- &interaction.template.simple.manyfilters; --> 14.391 - <caption><para>Template filters in action</para></caption> 14.392 - \label{fig:template:filters} 14.393 -</para> 14.394 -</informalfigure> 14.395 - 14.396 -<note> 14.397 -<para> If you try to apply a filter to a piece of data that it cannot 14.398 - process, Mercurial will fail and print a Python exception. For 14.399 - example, trying to run the output of the <literal role="template-keyword">desc</literal> keyword 14.400 - into the <literal role="template-kw-filt-date">isodate</literal> filter is not a good idea. 14.401 -</para> 14.402 -</note> 14.403 - 14.404 -<sect2> 14.405 -<title>Combining filters</title> 14.406 - 14.407 -<para>It is easy to combine filters to yield output in the form you would 14.408 -like. The following chain of filters tidies up a description, then 14.409 -makes sure that it fits cleanly into 68 columns, then indents it by a 14.410 -further 8 characters (at least on Unix-like systems, where a tab is 14.411 -conventionally 8 characters wide). 14.412 -</para> 14.413 - 14.414 -<para><!-- &interaction.template.simple.combine; --> 14.415 -</para> 14.416 - 14.417 -<para>Note the use of <quote><literal>\t</literal></quote> (a tab character) in the template to 14.418 -force the first line to be indented; this is necessary since 14.419 -<literal role="template-keyword">tabindent</literal> indents all lines <emphasis>except</emphasis> the first. 14.420 -</para> 14.421 - 14.422 -<para>Keep in mind that the order of filters in a chain is significant. The 14.423 -first filter is applied to the result of the keyword; the second to 14.424 -the result of the first filter; and so on. For example, using 14.425 -<literal>fill68|tabindent</literal> gives very different results from 14.426 -<literal>tabindent|fill68</literal>. 14.427 -</para> 14.428 - 14.429 - 14.430 -</sect2> 14.431 -</sect1> 14.432 -<sect1> 14.433 -<title>From templates to styles</title> 14.434 - 14.435 -<para>A command line template provides a quick and simple way to format some 14.436 -output. Templates can become verbose, though, and it's useful to be 14.437 -able to give a template a name. A style file is a template with a 14.438 -name, stored in a file. 14.439 -</para> 14.440 - 14.441 -<para>More than that, using a style file unlocks the power of Mercurial's 14.442 -templating engine in ways that are not possible using the command line 14.443 -<option role="hg-opt-log">--template</option> option. 14.444 -</para> 14.445 - 14.446 -<sect2> 14.447 -<title>The simplest of style files</title> 14.448 - 14.449 -<para>Our simple style file contains just one line: 14.450 -</para> 14.451 - 14.452 -<para><!-- &interaction.template.simple.rev; --> 14.453 -</para> 14.454 - 14.455 -<para>This tells Mercurial, <quote>if you're printing a changeset, use the text 14.456 -on the right as the template</quote>. 14.457 -</para> 14.458 - 14.459 -</sect2> 14.460 -<sect2> 14.461 -<title>Style file syntax</title> 14.462 - 14.463 -<para>The syntax rules for a style file are simple. 14.464 -</para> 14.465 - 14.466 -<itemizedlist> 14.467 -<listitem><para>The file is processed one line at a time. 14.468 -</para> 14.469 -</listitem> 14.470 -</para> 14.471 -</listitem> 14.472 -<listitem><para>Leading and trailing white space are ignored. 14.473 -</para> 14.474 -</listitem> 14.475 -</para> 14.476 -</listitem> 14.477 -<listitem><para>Empty lines are skipped. 14.478 -</para> 14.479 -</listitem> 14.480 -</para> 14.481 -</listitem> 14.482 -<listitem><para>If a line starts with either of the characters <quote><literal>#</literal></quote> or 14.483 - <quote><literal>;</literal></quote>, the entire line is treated as a comment, and skipped 14.484 - as if empty. 14.485 -</para> 14.486 -</listitem> 14.487 -</para> 14.488 -</listitem> 14.489 -<listitem><para>A line starts with a keyword. This must start with an 14.490 - alphabetic character or underscore, and can subsequently contain any 14.491 - alphanumeric character or underscore. (In regexp notation, a 14.492 - keyword must match <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.) 14.493 -</para> 14.494 -</listitem> 14.495 -</para> 14.496 -</listitem> 14.497 -<listitem><para>The next element must be an <quote><literal>=</literal></quote> character, which can 14.498 - be preceded or followed by an arbitrary amount of white space. 14.499 -</para> 14.500 -</listitem> 14.501 -</para> 14.502 -</listitem> 14.503 -<listitem><para>If the rest of the line starts and ends with matching quote 14.504 - characters (either single or double quote), it is treated as a 14.505 - template body. 14.506 -</para> 14.507 -</listitem> 14.508 -</para> 14.509 -</listitem> 14.510 -<listitem><para>If the rest of the line <emphasis>does not</emphasis> start with a quote 14.511 - character, it is treated as the name of a file; the contents of this 14.512 - file will be read and used as a template body. 14.513 -</para> 14.514 -</listitem></itemizedlist> 14.515 - 14.516 -</sect2> 14.517 -</sect1> 14.518 -<sect1> 14.519 -<title>Style files by example</title> 14.520 - 14.521 -<para>To illustrate how to write a style file, we will construct a few by 14.522 -example. Rather than provide a complete style file and walk through 14.523 -it, we'll mirror the usual process of developing a style file by 14.524 -starting with something very simple, and walking through a series of 14.525 -successively more complete examples. 14.526 -</para> 14.527 - 14.528 -<sect2> 14.529 -<title>Identifying mistakes in style files</title> 14.530 - 14.531 -<para>If Mercurial encounters a problem in a style file you are working on, 14.532 -it prints a terse error message that, once you figure out what it 14.533 -means, is actually quite useful. 14.534 -</para> 14.535 - 14.536 -<para><!-- &interaction.template.svnstyle.syntax.input; --> 14.537 -</para> 14.538 - 14.539 -<para>Notice that <filename>broken.style</filename> attempts to define a 14.540 -<literal>changeset</literal> keyword, but forgets to give any content for it. 14.541 -When instructed to use this style file, Mercurial promptly complains. 14.542 -</para> 14.543 - 14.544 -<para><!-- &interaction.template.svnstyle.syntax.error; --> 14.545 -</para> 14.546 - 14.547 -<para>This error message looks intimidating, but it is not too hard to 14.548 -follow. 14.549 -</para> 14.550 - 14.551 -<itemizedlist> 14.552 -<listitem><para>The first component is simply Mercurial's way of saying <quote>I am 14.553 - giving up</quote>. 14.554 -</para> 14.555 -</listitem><programlisting> 14.556 -<listitem><para> <emphasis role="bold">abort:</emphasis> broken.style:1: parse error 14.557 -</para> 14.558 -</listitem></programlisting> 14.559 - 14.560 -</para> 14.561 -</listitem> 14.562 -<listitem><para>Next comes the name of the style file that contains the error. 14.563 -</para> 14.564 -</listitem><programlisting> 14.565 -<listitem><para> abort: <emphasis role="bold">broken.style</emphasis>:1: parse error 14.566 -</para> 14.567 -</listitem></programlisting> 14.568 - 14.569 -</para> 14.570 -</listitem> 14.571 -<listitem><para>Following the file name is the line number where the error was 14.572 - encountered. 14.573 -</para> 14.574 -</listitem><programlisting> 14.575 -<listitem><para> abort: broken.style:<emphasis role="bold">1</emphasis>: parse error 14.576 -</para> 14.577 -</listitem></programlisting> 14.578 - 14.579 -</para> 14.580 -</listitem> 14.581 -<listitem><para>Finally, a description of what went wrong. 14.582 -</para> 14.583 -</listitem><programlisting> 14.584 -<listitem><para> abort: broken.style:1: <emphasis role="bold">parse error</emphasis> 14.585 -</para> 14.586 -</listitem></programlisting> 14.587 -<listitem><para> The description of the problem is not always clear (as in this 14.588 - case), but even when it is cryptic, it is almost always trivial to 14.589 - visually inspect the offending line in the style file and see what 14.590 - is wrong. 14.591 -</para> 14.592 -</listitem></itemizedlist> 14.593 - 14.594 -</sect2> 14.595 -<sect2> 14.596 -<title>Uniquely identifying a repository</title> 14.597 - 14.598 -<para>If you would like to be able to identify a Mercurial repository 14.599 -<quote>fairly uniquely</quote> using a short string as an identifier, you can 14.600 -use the first revision in the repository. 14.601 -<!-- &interaction.template.svnstyle.id; --> 14.602 -This is not guaranteed to be unique, but it is nevertheless useful in 14.603 -many cases. 14.604 -</para> 14.605 -<itemizedlist> 14.606 -<listitem><para>It will not work in a completely empty repository, because such 14.607 - a repository does not have a revision zero. 14.608 -</para> 14.609 -</listitem> 14.610 -<listitem><para>Neither will it work in the (extremely rare) case where a 14.611 - repository is a merge of two or more formerly independent 14.612 - repositories, and you still have those repositories around. 14.613 -</para> 14.614 -</listitem></itemizedlist> 14.615 -<para>Here are some uses to which you could put this identifier: 14.616 -</para> 14.617 -<itemizedlist> 14.618 -<listitem><para>As a key into a table for a database that manages repositories 14.619 - on a server. 14.620 -</para> 14.621 -</listitem> 14.622 -<listitem><para>As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 14.623 - Save this information away when you run an automated build or other 14.624 - activity, so that you can <quote>replay</quote> the build later if necessary. 14.625 -</para> 14.626 -</listitem></itemizedlist> 14.627 - 14.628 -</sect2> 14.629 -<sect2> 14.630 -<title>Mimicking Subversion's output</title> 14.631 - 14.632 -<para>Let's try to emulate the default output format used by another 14.633 -revision control tool, Subversion. 14.634 -<!-- &interaction.template.svnstyle.short; --> 14.635 -</para> 14.636 - 14.637 -<para>Since Subversion's output style is fairly simple, it is easy to 14.638 -copy-and-paste a hunk of its output into a file, and replace the text 14.639 -produced above by Subversion with the template values we'd like to see 14.640 -expanded. 14.641 -<!-- &interaction.template.svnstyle.template; --> 14.642 -</para> 14.643 - 14.644 -<para>There are a few small ways in which this template deviates from the 14.645 -output produced by Subversion. 14.646 -</para> 14.647 -<itemizedlist> 14.648 -<listitem><para>Subversion prints a <quote>readable</quote> date (the <quote>\texttt{Wed, 27 Sep 14.649 - 2006}</quote> in the example output above) in parentheses. Mercurial's 14.650 - templating engine does not provide a way to display a date in this 14.651 - format without also printing the time and time zone. 14.652 -</para> 14.653 -</listitem> 14.654 -<listitem><para>We emulate Subversion's printing of <quote>separator</quote> lines full of 14.655 - <quote><literal>-</literal></quote> characters by ending the template with such a line. 14.656 - We use the templating engine's <literal role="template-keyword">header</literal> keyword to print a 14.657 - separator line as the first line of output (see below), thus 14.658 - achieving similar output to Subversion. 14.659 -</para> 14.660 -</listitem> 14.661 -<listitem><para>Subversion's output includes a count in the header of the number 14.662 - of lines in the commit message. We cannot replicate this in 14.663 - Mercurial; the templating engine does not currently provide a filter 14.664 - that counts the number of lines the template generates. 14.665 -</para> 14.666 -</listitem></itemizedlist> 14.667 -<para>It took me no more than a minute or two of work to replace literal 14.668 -text from an example of Subversion's output with some keywords and 14.669 -filters to give the template above. The style file simply refers to 14.670 -the template. 14.671 -<!-- &interaction.template.svnstyle.style; --> 14.672 -</para> 14.673 - 14.674 -<para>We could have included the text of the template file directly in the 14.675 -style file by enclosing it in quotes and replacing the newlines with 14.676 -<quote><literal>\n</literal></quote> sequences, but it would have made the style file too 14.677 -difficult to read. Readability is a good guide when you're trying to 14.678 -decide whether some text belongs in a style file, or in a template 14.679 -file that the style file points to. If the style file will look too 14.680 -big or cluttered if you insert a literal piece of text, drop it into a 14.681 -template instead. 14.682 -</para> 14.683 - 14.684 -</sect2> 14.685 -</sect1> 14.686 +<chapter id="chap:template"> 14.687 + <?dbhtml filename="customizing-the-output-of-mercurial.html"?> 14.688 + <title>Customizing the output of Mercurial</title> 14.689 + 14.690 + <para id="x_578">Mercurial provides a powerful mechanism to let you control how 14.691 + it displays information. The mechanism is based on templates. 14.692 + You can use templates to generate specific output for a single 14.693 + command, or to customize the entire appearance of the built-in web 14.694 + interface.</para> 14.695 + 14.696 + <sect1 id="sec:style"> 14.697 + <title>Using precanned output styles</title> 14.698 + 14.699 + <para id="x_579">Packaged with Mercurial are some output styles that you can 14.700 + use immediately. A style is simply a precanned template that 14.701 + someone wrote and installed somewhere that Mercurial can 14.702 + find.</para> 14.703 + 14.704 + <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's 14.705 + review its normal output.</para> 14.706 + 14.707 + &interaction.template.simple.normal; 14.708 + 14.709 + <para id="x_57b">This is somewhat informative, but it takes up a lot of 14.710 + space&emdash;five lines of output per changeset. The 14.711 + <literal>compact</literal> style reduces this to three lines, 14.712 + presented in a sparse manner.</para> 14.713 + 14.714 + &interaction.template.simple.compact; 14.715 + 14.716 + <para id="x_57c">The <literal>changelog</literal> style hints at the 14.717 + expressive power of Mercurial's templating engine. This style 14.718 + attempts to follow the GNU Project's changelog 14.719 + guidelines<citation>web:changelog</citation>.</para> 14.720 + 14.721 + &interaction.template.simple.changelog; 14.722 + 14.723 + <para id="x_57d">You will not be shocked to learn that Mercurial's default 14.724 + output style is named <literal>default</literal>.</para> 14.725 + 14.726 + <sect2> 14.727 + <title>Setting a default style</title> 14.728 + 14.729 + <para id="x_57e">You can modify the output style that Mercurial will use 14.730 + for every command by editing your <filename 14.731 + role="special">~/.hgrc</filename> file, naming the style 14.732 + you would prefer to use.</para> 14.733 + 14.734 + <programlisting>[ui] 14.735 +style = compact</programlisting> 14.736 + 14.737 + <para id="x_57f">If you write a style of your own, you can use it by either 14.738 + providing the path to your style file, or copying your style 14.739 + file into a location where Mercurial can find it (typically 14.740 + the <literal>templates</literal> subdirectory of your 14.741 + Mercurial install directory).</para> 14.742 + </sect2> 14.743 + </sect1> 14.744 + 14.745 + <sect1> 14.746 + <title>Commands that support styles and templates</title> 14.747 + 14.748 + <para id="x_580">All of Mercurial's 14.749 + <quote><literal>log</literal>-like</quote> commands let you use 14.750 + styles and templates: <command role="hg-cmd">hg 14.751 + incoming</command>, <command role="hg-cmd">hg log</command>, 14.752 + <command role="hg-cmd">hg outgoing</command>, and <command 14.753 + role="hg-cmd">hg tip</command>.</para> 14.754 + 14.755 + <para id="x_581">As I write this manual, these are so far the only commands 14.756 + that support styles and templates. Since these are the most 14.757 + important commands that need customizable output, there has been 14.758 + little pressure from the Mercurial user community to add style 14.759 + and template support to other commands.</para> 14.760 + </sect1> 14.761 + 14.762 + <sect1> 14.763 + <title>The basics of templating</title> 14.764 + 14.765 + <para id="x_582">At its simplest, a Mercurial template is a piece of text. 14.766 + Some of the text never changes, while other parts are 14.767 + <emphasis>expanded</emphasis>, or replaced with new text, when 14.768 + necessary.</para> 14.769 + 14.770 + <para id="x_583">Before we continue, let's look again at a simple example of 14.771 + Mercurial's normal output.</para> 14.772 + 14.773 + &interaction.template.simple.normal; 14.774 + 14.775 + <para id="x_584">Now, let's run the same command, but using a template to 14.776 + change its output.</para> 14.777 + 14.778 + &interaction.template.simple.simplest; 14.779 + 14.780 + <para id="x_585">The example above illustrates the simplest possible 14.781 + template; it's just a piece of static text, printed once for 14.782 + each changeset. The <option 14.783 + role="hg-opt-log">--template</option> option to the <command 14.784 + role="hg-cmd">hg log</command> command tells Mercurial to use 14.785 + the given text as the template when printing each 14.786 + changeset.</para> 14.787 + 14.788 + <para id="x_586">Notice that the template string above ends with the text 14.789 + <quote><literal>\n</literal></quote>. This is an 14.790 + <emphasis>escape sequence</emphasis>, telling Mercurial to print 14.791 + a newline at the end of each template item. If you omit this 14.792 + newline, Mercurial will run each piece of output together. See 14.793 + <xref linkend="sec:template:escape"/> for more details 14.794 + of escape sequences.</para> 14.795 + 14.796 + <para id="x_587">A template that prints a fixed string of text all the time 14.797 + isn't very useful; let's try something a bit more 14.798 + complex.</para> 14.799 + 14.800 + &interaction.template.simple.simplesub; 14.801 + 14.802 + <para id="x_588">As you can see, the string 14.803 + <quote><literal>{desc}</literal></quote> in the template has 14.804 + been replaced in the output with the description of each 14.805 + changeset. Every time Mercurial finds text enclosed in curly 14.806 + braces (<quote><literal>{</literal></quote> and 14.807 + <quote><literal>}</literal></quote>), it will try to replace the 14.808 + braces and text with the expansion of whatever is inside. To 14.809 + print a literal curly brace, you must escape it, as described in 14.810 + <xref linkend="sec:template:escape"/>.</para> 14.811 + </sect1> 14.812 + 14.813 + <sect1 id="sec:template:keyword"> 14.814 + <title>Common template keywords</title> 14.815 + 14.816 + <para id="x_589">You can start writing simple templates immediately using the 14.817 + keywords below.</para> 14.818 + 14.819 + <itemizedlist> 14.820 + <listitem><para id="x_58a"><literal 14.821 + role="template-keyword">author</literal>: String. The 14.822 + unmodified author of the changeset.</para> 14.823 + </listitem> 14.824 + <listitem><para id="x_58b"><literal 14.825 + role="template-keyword">branches</literal>: String. The 14.826 + name of the branch on which the changeset was committed. 14.827 + Will be empty if the branch name was 14.828 + <literal>default</literal>.</para> 14.829 + </listitem> 14.830 + <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: 14.831 + Date information. The date when the changeset was 14.832 + committed. This is <emphasis>not</emphasis> human-readable; 14.833 + you must pass it through a filter that will render it 14.834 + appropriately. See <xref 14.835 + linkend="sec:template:filter"/> for more information 14.836 + on filters. The date is expressed as a pair of numbers. The 14.837 + first number is a Unix UTC timestamp (seconds since January 14.838 + 1, 1970); the second is the offset of the committer's 14.839 + timezone from UTC, in seconds.</para> 14.840 + </listitem> 14.841 + <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: 14.842 + String. The text of the changeset description.</para> 14.843 + </listitem> 14.844 + <listitem><para id="x_58e"><literal 14.845 + role="template-keyword">files</literal>: List of strings. 14.846 + All files modified, added, or removed by this 14.847 + changeset.</para> 14.848 + </listitem> 14.849 + <listitem><para id="x_58f"><literal 14.850 + role="template-keyword">file_adds</literal>: List of 14.851 + strings. Files added by this changeset.</para> 14.852 + </listitem> 14.853 + <listitem><para id="x_590"><literal 14.854 + role="template-keyword">file_dels</literal>: List of 14.855 + strings. Files removed by this changeset.</para> 14.856 + </listitem> 14.857 + <listitem><para id="x_591"><literal role="template-keyword">node</literal>: 14.858 + String. The changeset identification hash, as a 14.859 + 40-character hexadecimal string.</para> 14.860 + </listitem> 14.861 + <listitem><para id="x_592"><literal 14.862 + role="template-keyword">parents</literal>: List of 14.863 + strings. The parents of the changeset.</para> 14.864 + </listitem> 14.865 + <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: 14.866 + Integer. The repository-local changeset revision 14.867 + number.</para> 14.868 + </listitem> 14.869 + <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: 14.870 + List of strings. Any tags associated with the 14.871 + changeset.</para> 14.872 + </listitem> 14.873 + </itemizedlist> 14.874 + 14.875 + <para id="x_595">A few simple experiments will show us what to expect when we 14.876 + use these keywords; you can see the results below.</para> 14.877 + 14.878 + &interaction.template.simple.keywords; 14.879 + 14.880 + <para id="x_596">As we noted above, the date keyword does not produce 14.881 + human-readable output, so we must treat it specially. This 14.882 + involves using a <emphasis>filter</emphasis>, about which more 14.883 + in <xref linkend="sec:template:filter"/>.</para> 14.884 + 14.885 + &interaction.template.simple.datekeyword; 14.886 + </sect1> 14.887 + 14.888 + <sect1 id="sec:template:escape"> 14.889 + <title>Escape sequences</title> 14.890 + 14.891 + <para id="x_597">Mercurial's templating engine recognises the most commonly 14.892 + used escape sequences in strings. When it sees a backslash 14.893 + (<quote><literal>\</literal></quote>) character, it looks at the 14.894 + following character and substitutes the two characters with a 14.895 + single replacement, as described below.</para> 14.896 + 14.897 + <itemizedlist> 14.898 + <listitem><para id="x_598"><literal>\</literal>: 14.899 + Backslash, <quote><literal>\</literal></quote>, ASCII 14.900 + 134.</para> 14.901 + </listitem> 14.902 + <listitem><para id="x_599"><literal>\n</literal>: Newline, 14.903 + ASCII 12.</para> 14.904 + </listitem> 14.905 + <listitem><para id="x_59a"><literal>\r</literal>: Carriage 14.906 + return, ASCII 15.</para> 14.907 + </listitem> 14.908 + <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII 14.909 + 11.</para> 14.910 + </listitem> 14.911 + <listitem><para id="x_59c"><literal>\v</literal>: Vertical 14.912 + tab, ASCII 13.</para> 14.913 + </listitem> 14.914 + <listitem><para id="x_59d"><literal>\{</literal>: Open curly 14.915 + brace, <quote><literal>{</literal></quote>, ASCII 14.916 + 173.</para> 14.917 + </listitem> 14.918 + <listitem><para id="x_59e"><literal>\}</literal>: Close curly 14.919 + brace, <quote><literal>}</literal></quote>, ASCII 14.920 + 175.</para> 14.921 + </listitem></itemizedlist> 14.922 + 14.923 + <para id="x_59f">As indicated above, if you want the expansion of a template 14.924 + to contain a literal <quote><literal>\</literal></quote>, 14.925 + <quote><literal>{</literal></quote>, or 14.926 + <quote><literal>{</literal></quote> character, you must escape 14.927 + it.</para> 14.928 + </sect1> 14.929 + 14.930 + <sect1 id="sec:template:filter"> 14.931 + <title>Filtering keywords to change their results</title> 14.932 + 14.933 + <para id="x_5a0">Some of the results of template expansion are not 14.934 + immediately easy to use. Mercurial lets you specify an optional 14.935 + chain of <emphasis>filters</emphasis> to modify the result of 14.936 + expanding a keyword. You have already seen a common filter, 14.937 + <literal role="template-kw-filt-date">isodate</literal>, in 14.938 + action above, to make a date readable.</para> 14.939 + 14.940 + <para id="x_5a1">Below is a list of the most commonly used filters that 14.941 + Mercurial supports. While some filters can be applied to any 14.942 + text, others can only be used in specific circumstances. The 14.943 + name of each filter is followed first by an indication of where 14.944 + it can be used, then a description of its effect.</para> 14.945 + 14.946 + <itemizedlist> 14.947 + <listitem><para id="x_5a2"><literal 14.948 + role="template-filter">addbreaks</literal>: Any text. Add 14.949 + an XHTML <quote><literal><br/></literal></quote> tag 14.950 + before the end of every line except the last. For example, 14.951 + <quote><literal>foo\nbar</literal></quote> becomes 14.952 + <quote><literal>foo<br/>\nbar</literal></quote>.</para> 14.953 + </listitem> 14.954 + <listitem><para id="x_5a3"><literal 14.955 + role="template-kw-filt-date">age</literal>: <literal 14.956 + role="template-keyword">date</literal> keyword. Render 14.957 + the age of the date, relative to the current time. Yields a 14.958 + string like <quote><literal>10 14.959 + minutes</literal></quote>.</para> 14.960 + </listitem> 14.961 + <listitem><para id="x_5a4"><literal 14.962 + role="template-filter">basename</literal>: Any text, but 14.963 + most useful for the <literal 14.964 + role="template-keyword">files</literal> keyword and its 14.965 + relatives. Treat the text as a path, and return the 14.966 + basename. For example, 14.967 + <quote><literal>foo/bar/baz</literal></quote> becomes 14.968 + <quote><literal>baz</literal></quote>.</para> 14.969 + </listitem> 14.970 + <listitem><para id="x_5a5"><literal 14.971 + role="template-kw-filt-date">date</literal>: <literal 14.972 + role="template-keyword">date</literal> keyword. Render a 14.973 + date in a similar format to the Unix <literal 14.974 + role="template-keyword">date</literal> command, but with 14.975 + timezone included. Yields a string like <quote><literal>Mon 14.976 + Sep 04 15:13:13 2006 -0700</literal></quote>.</para> 14.977 + </listitem> 14.978 + <listitem><para id="x_5a6"><literal 14.979 + role="template-kw-filt-author">domain</literal>: Any text, 14.980 + but most useful for the <literal 14.981 + role="template-keyword">author</literal> keyword. Finds 14.982 + the first string that looks like an email address, and 14.983 + extract just the domain component. For example, 14.984 + <quote><literal>Bryan O'Sullivan 14.985 + <bos@serpentine.com></literal></quote> becomes 14.986 + <quote><literal>serpentine.com</literal></quote>.</para> 14.987 + </listitem> 14.988 + <listitem><para id="x_5a7"><literal 14.989 + role="template-kw-filt-author">email</literal>: Any text, 14.990 + but most useful for the <literal 14.991 + role="template-keyword">author</literal> keyword. Extract 14.992 + the first string that looks like an email address. For 14.993 + example, <quote><literal>Bryan O'Sullivan 14.994 + <bos@serpentine.com></literal></quote> becomes 14.995 + <quote><literal>bos@serpentine.com</literal></quote>.</para> 14.996 + </listitem> 14.997 + <listitem><para id="x_5a8"><literal 14.998 + role="template-filter">escape</literal>: Any text. 14.999 + Replace the special XML/XHTML characters 14.1000 + <quote><literal>&</literal></quote>, 14.1001 + <quote><literal><</literal></quote> and 14.1002 + <quote><literal>></literal></quote> with XML 14.1003 + entities.</para> 14.1004 + </listitem> 14.1005 + <listitem><para id="x_5a9"><literal 14.1006 + role="template-filter">fill68</literal>: Any text. Wrap 14.1007 + the text to fit in 68 columns. This is useful before you 14.1008 + pass text through the <literal 14.1009 + role="template-filter">tabindent</literal> filter, and 14.1010 + still want it to fit in an 80-column fixed-font 14.1011 + window.</para> 14.1012 + </listitem> 14.1013 + <listitem><para id="x_5aa"><literal 14.1014 + role="template-filter">fill76</literal>: Any text. Wrap 14.1015 + the text to fit in 76 columns.</para> 14.1016 + </listitem> 14.1017 + <listitem><para id="x_5ab"><literal 14.1018 + role="template-filter">firstline</literal>: Any text. 14.1019 + Yield the first line of text, without any trailing 14.1020 + newlines.</para> 14.1021 + </listitem> 14.1022 + <listitem><para id="x_5ac"><literal 14.1023 + role="template-kw-filt-date">hgdate</literal>: <literal 14.1024 + role="template-keyword">date</literal> keyword. Render 14.1025 + the date as a pair of readable numbers. Yields a string 14.1026 + like <quote><literal>1157407993 14.1027 + 25200</literal></quote>.</para> 14.1028 + </listitem> 14.1029 + <listitem><para id="x_5ad"><literal 14.1030 + role="template-kw-filt-date">isodate</literal>: <literal 14.1031 + role="template-keyword">date</literal> keyword. Render 14.1032 + the date as a text string in ISO 8601 format. Yields a 14.1033 + string like <quote><literal>2006-09-04 15:13:13 14.1034 + -0700</literal></quote>.</para> 14.1035 + </listitem> 14.1036 + <listitem><para id="x_5ae"><literal 14.1037 + role="template-filter">obfuscate</literal>: Any text, but 14.1038 + most useful for the <literal 14.1039 + role="template-keyword">author</literal> keyword. Yield 14.1040 + the input text rendered as a sequence of XML entities. This 14.1041 + helps to defeat some particularly stupid screen-scraping 14.1042 + email harvesting spambots.</para> 14.1043 + </listitem> 14.1044 + <listitem><para id="x_5af"><literal 14.1045 + role="template-kw-filt-author">person</literal>: Any text, 14.1046 + but most useful for the <literal 14.1047 + role="template-keyword">author</literal> keyword. Yield 14.1048 + the text before an email address. For example, 14.1049 + <quote><literal>Bryan O'Sullivan 14.1050 + <bos@serpentine.com></literal></quote> becomes 14.1051 + <quote><literal>Bryan O'Sullivan</literal></quote>.</para> 14.1052 + </listitem> 14.1053 + <listitem><para id="x_5b0"><literal 14.1054 + role="template-kw-filt-date">rfc822date</literal>: 14.1055 + <literal role="template-keyword">date</literal> keyword. 14.1056 + Render a date using the same format used in email headers. 14.1057 + Yields a string like <quote><literal>Mon, 04 Sep 2006 14.1058 + 15:13:13 -0700</literal></quote>.</para> 14.1059 + </listitem> 14.1060 + <listitem><para id="x_5b1"><literal 14.1061 + role="template-kw-filt-node">short</literal>: Changeset 14.1062 + hash. Yield the short form of a changeset hash, i.e. a 14.1063 + 12-character hexadecimal string.</para> 14.1064 + </listitem> 14.1065 + <listitem><para id="x_5b2"><literal 14.1066 + role="template-kw-filt-date">shortdate</literal>: <literal 14.1067 + role="template-keyword">date</literal> keyword. Render 14.1068 + the year, month, and day of the date. Yields a string like 14.1069 + <quote><literal>2006-09-04</literal></quote>.</para> 14.1070 + </listitem> 14.1071 + <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: 14.1072 + Any text. Strip all leading and trailing whitespace from 14.1073 + the string.</para> 14.1074 + </listitem> 14.1075 + <listitem><para id="x_5b4"><literal 14.1076 + role="template-filter">tabindent</literal>: Any text. 14.1077 + Yield the text, with every line except the first starting 14.1078 + with a tab character.</para> 14.1079 + </listitem> 14.1080 + <listitem><para id="x_5b5"><literal 14.1081 + role="template-filter">urlescape</literal>: Any text. 14.1082 + Escape all characters that are considered 14.1083 + <quote>special</quote> by URL parsers. For example, 14.1084 + <literal>foo bar</literal> becomes 14.1085 + <literal>foo%20bar</literal>.</para> 14.1086 + </listitem> 14.1087 + <listitem><para id="x_5b6"><literal 14.1088 + role="template-kw-filt-author">user</literal>: Any text, 14.1089 + but most useful for the <literal 14.1090 + role="template-keyword">author</literal> keyword. Return 14.1091 + the <quote>user</quote> portion of an email address. For 14.1092 + example, <quote><literal>Bryan O'Sullivan 14.1093 + <bos@serpentine.com></literal></quote> becomes 14.1094 + <quote><literal>bos</literal></quote>.</para> 14.1095 + </listitem> 14.1096 + </itemizedlist> 14.1097 + 14.1098 + &interaction.template.simple.manyfilters; 14.1099 + 14.1100 + <note> 14.1101 + <para id="x_5b7"> If you try to apply a filter to a piece of data that it 14.1102 + cannot process, Mercurial will fail and print a Python 14.1103 + exception. For example, trying to run the output of the 14.1104 + <literal role="template-keyword">desc</literal> keyword into 14.1105 + the <literal role="template-kw-filt-date">isodate</literal> 14.1106 + filter is not a good idea.</para> 14.1107 + </note> 14.1108 + 14.1109 + <sect2> 14.1110 + <title>Combining filters</title> 14.1111 + 14.1112 + <para id="x_5b8">It is easy to combine filters to yield output in the form 14.1113 + you would like. The following chain of filters tidies up a 14.1114 + description, then makes sure that it fits cleanly into 68 14.1115 + columns, then indents it by a further 8 characters (at least 14.1116 + on Unix-like systems, where a tab is conventionally 8 14.1117 + characters wide).</para> 14.1118 + 14.1119 + &interaction.template.simple.combine; 14.1120 + 14.1121 + <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a 14.1122 + tab character) in the template to force the first line to be 14.1123 + indented; this is necessary since <literal 14.1124 + role="template-keyword">tabindent</literal> indents all 14.1125 + lines <emphasis>except</emphasis> the first.</para> 14.1126 + 14.1127 + <para id="x_5ba">Keep in mind that the order of filters in a chain is 14.1128 + significant. The first filter is applied to the result of the 14.1129 + keyword; the second to the result of the first filter; and so 14.1130 + on. For example, using <literal>fill68|tabindent</literal> 14.1131 + gives very different results from 14.1132 + <literal>tabindent|fill68</literal>.</para> 14.1133 + </sect2> 14.1134 + </sect1> 14.1135 + 14.1136 + <sect1> 14.1137 + <title>From templates to styles</title> 14.1138 + 14.1139 + <para id="x_5bb">A command line template provides a quick and simple way to 14.1140 + format some output. Templates can become verbose, though, and 14.1141 + it's useful to be able to give a template a name. A style file 14.1142 + is a template with a name, stored in a file.</para> 14.1143 + 14.1144 + <para id="x_5bc">More than that, using a style file unlocks the power of 14.1145 + Mercurial's templating engine in ways that are not possible 14.1146 + using the command line <option 14.1147 + role="hg-opt-log">--template</option> option.</para> 14.1148 + 14.1149 + <sect2> 14.1150 + <title>The simplest of style files</title> 14.1151 + 14.1152 + <para id="x_5bd">Our simple style file contains just one line:</para> 14.1153 + 14.1154 + &interaction.template.simple.rev; 14.1155 + 14.1156 + <para id="x_5be">This tells Mercurial, <quote>if you're printing a 14.1157 + changeset, use the text on the right as the 14.1158 + template</quote>.</para> 14.1159 + </sect2> 14.1160 + 14.1161 + <sect2> 14.1162 + <title>Style file syntax</title> 14.1163 + 14.1164 + <para id="x_5bf">The syntax rules for a style file are simple.</para> 14.1165 + 14.1166 + <itemizedlist> 14.1167 + <listitem><para id="x_5c0">The file is processed one line at a 14.1168 + time.</para> 14.1169 + </listitem> 14.1170 + <listitem><para id="x_5c1">Leading and trailing white space are 14.1171 + ignored.</para> 14.1172 + </listitem> 14.1173 + <listitem><para id="x_5c2">Empty lines are skipped.</para> 14.1174 + </listitem> 14.1175 + <listitem><para id="x_5c3">If a line starts with either of the characters 14.1176 + <quote><literal>#</literal></quote> or 14.1177 + <quote><literal>;</literal></quote>, the entire line is 14.1178 + treated as a comment, and skipped as if empty.</para> 14.1179 + </listitem> 14.1180 + <listitem><para id="x_5c4">A line starts with a keyword. This must start 14.1181 + with an alphabetic character or underscore, and can 14.1182 + subsequently contain any alphanumeric character or 14.1183 + underscore. (In regexp notation, a keyword must match 14.1184 + <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para> 14.1185 + </listitem> 14.1186 + <listitem><para id="x_5c5">The next element must be an 14.1187 + <quote><literal>=</literal></quote> character, which can 14.1188 + be preceded or followed by an arbitrary amount of white 14.1189 + space.</para> 14.1190 + </listitem> 14.1191 + <listitem><para id="x_5c6">If the rest of the line starts and ends with 14.1192 + matching quote characters (either single or double quote), 14.1193 + it is treated as a template body.</para> 14.1194 + </listitem> 14.1195 + <listitem><para id="x_5c7">If the rest of the line <emphasis>does 14.1196 + not</emphasis> start with a quote character, it is 14.1197 + treated as the name of a file; the contents of this file 14.1198 + will be read and used as a template body.</para> 14.1199 + </listitem></itemizedlist> 14.1200 + </sect2> 14.1201 + </sect1> 14.1202 + 14.1203 + <sect1> 14.1204 + <title>Style files by example</title> 14.1205 + 14.1206 + <para id="x_5c8">To illustrate how to write a style file, we will construct a 14.1207 + few by example. Rather than provide a complete style file and 14.1208 + walk through it, we'll mirror the usual process of developing a 14.1209 + style file by starting with something very simple, and walking 14.1210 + through a series of successively more complete examples.</para> 14.1211 + 14.1212 + <sect2> 14.1213 + <title>Identifying mistakes in style files</title> 14.1214 + 14.1215 + <para id="x_5c9">If Mercurial encounters a problem in a style file you are 14.1216 + working on, it prints a terse error message that, once you 14.1217 + figure out what it means, is actually quite useful.</para> 14.1218 + 14.1219 +&interaction.template.svnstyle.syntax.input; 14.1220 + 14.1221 + <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to 14.1222 + define a <literal>changeset</literal> keyword, but forgets to 14.1223 + give any content for it. When instructed to use this style 14.1224 + file, Mercurial promptly complains.</para> 14.1225 + 14.1226 + &interaction.template.svnstyle.syntax.error; 14.1227 + 14.1228 + <para id="x_5cb">This error message looks intimidating, but it is not too 14.1229 + hard to follow.</para> 14.1230 + 14.1231 + <itemizedlist> 14.1232 + <listitem><para id="x_5cc">The first component is simply Mercurial's way 14.1233 + of saying <quote>I am giving up</quote>.</para> 14.1234 + <programlisting>___abort___: broken.style:1: parse error</programlisting> 14.1235 + </listitem> 14.1236 + <listitem><para id="x_5cd">Next comes the name of the style file that 14.1237 + contains the error.</para> 14.1238 + <programlisting>abort: ___broken.style___:1: parse error</programlisting> 14.1239 + </listitem> 14.1240 + <listitem><para id="x_5ce">Following the file name is the line number 14.1241 + where the error was encountered.</para> 14.1242 + <programlisting>abort: broken.style:___1___: parse error</programlisting> 14.1243 + </listitem> 14.1244 + <listitem><para id="x_5cf">Finally, a description of what went 14.1245 + wrong.</para> 14.1246 + <programlisting>abort: broken.style:1: ___parse error___</programlisting> 14.1247 + </listitem> 14.1248 + <listitem><para id="x_5d0">The description of the problem is not always 14.1249 + clear (as in this case), but even when it is cryptic, it 14.1250 + is almost always trivial to visually inspect the offending 14.1251 + line in the style file and see what is wrong.</para> 14.1252 + </listitem> 14.1253 + </itemizedlist> 14.1254 + </sect2> 14.1255 + 14.1256 + <sect2> 14.1257 + <title>Uniquely identifying a repository</title> 14.1258 + 14.1259 + <para id="x_5d1">If you would like to be able to identify a Mercurial 14.1260 + repository <quote>fairly uniquely</quote> using a short string 14.1261 + as an identifier, you can use the first revision in the 14.1262 + repository.</para> 14.1263 + 14.1264 + &interaction.template.svnstyle.id; 14.1265 + 14.1266 + <para id="x_5d2">This is likely to be unique, and so it is 14.1267 + useful in many cases. There are a few caveats.</para> 14.1268 + <itemizedlist> 14.1269 + <listitem><para id="x_5d3">It will not work in a completely empty 14.1270 + repository, because such a repository does not have a 14.1271 + revision zero.</para> 14.1272 + </listitem> 14.1273 + <listitem><para id="x_5d4">Neither will it work in the (extremely rare) 14.1274 + case where a repository is a merge of two or more formerly 14.1275 + independent repositories, and you still have those 14.1276 + repositories around.</para> 14.1277 + </listitem></itemizedlist> 14.1278 + <para id="x_5d5">Here are some uses to which you could put this 14.1279 + identifier:</para> 14.1280 + <itemizedlist> 14.1281 + <listitem><para id="x_5d6">As a key into a table for a database that 14.1282 + manages repositories on a server.</para> 14.1283 + </listitem> 14.1284 + <listitem><para id="x_5d7">As half of a {<emphasis>repository 14.1285 + ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 14.1286 + Save this information away when you run an automated build 14.1287 + or other activity, so that you can <quote>replay</quote> 14.1288 + the build later if necessary.</para> 14.1289 + </listitem> 14.1290 + </itemizedlist> 14.1291 + </sect2> 14.1292 + 14.1293 + <sect2> 14.1294 + <title>Listing files on multiple lines</title> 14.1295 + 14.1296 + <para id="x_714">Suppose we want to list the files changed by a changeset, 14.1297 + one per line, with a little indentation before each file 14.1298 + name.</para> 14.1299 + 14.1300 + &interaction.ch10-multiline.go; 14.1301 + </sect2> 14.1302 + 14.1303 + <sect2> 14.1304 + <title>Mimicking Subversion's output</title> 14.1305 + 14.1306 + <para id="x_5d8">Let's try to emulate the default output format used by 14.1307 + another revision control tool, Subversion.</para> 14.1308 + 14.1309 + &interaction.template.svnstyle.short; 14.1310 + 14.1311 + <para id="x_5d9">Since Subversion's output style is fairly simple, it is 14.1312 + easy to copy-and-paste a hunk of its output into a file, and 14.1313 + replace the text produced above by Subversion with the 14.1314 + template values we'd like to see expanded.</para> 14.1315 + 14.1316 + &interaction.template.svnstyle.template; 14.1317 + 14.1318 + <para id="x_5da">There are a few small ways in which this template deviates 14.1319 + from the output produced by Subversion.</para> 14.1320 + <itemizedlist> 14.1321 + <listitem><para id="x_5db">Subversion prints a <quote>readable</quote> 14.1322 + date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the 14.1323 + example output above) in parentheses. Mercurial's 14.1324 + templating engine does not provide a way to display a date 14.1325 + in this format without also printing the time and time 14.1326 + zone.</para> 14.1327 + </listitem> 14.1328 + <listitem><para id="x_5dc">We emulate Subversion's printing of 14.1329 + <quote>separator</quote> lines full of 14.1330 + <quote><literal>-</literal></quote> characters by ending 14.1331 + the template with such a line. We use the templating 14.1332 + engine's <literal role="template-keyword">header</literal> 14.1333 + keyword to print a separator line as the first line of 14.1334 + output (see below), thus achieving similar output to 14.1335 + Subversion.</para> 14.1336 + </listitem> 14.1337 + <listitem><para id="x_5dd">Subversion's output includes a count in the 14.1338 + header of the number of lines in the commit message. We 14.1339 + cannot replicate this in Mercurial; the templating engine 14.1340 + does not currently provide a filter that counts the number 14.1341 + of lines the template generates.</para> 14.1342 + </listitem></itemizedlist> 14.1343 + <para id="x_5de">It took me no more than a minute or two of work to replace 14.1344 + literal text from an example of Subversion's output with some 14.1345 + keywords and filters to give the template above. The style 14.1346 + file simply refers to the template.</para> 14.1347 + 14.1348 + &interaction.template.svnstyle.style; 14.1349 + 14.1350 + <para id="x_5df">We could have included the text of the template file 14.1351 + directly in the style file by enclosing it in quotes and 14.1352 + replacing the newlines with 14.1353 + <quote><literal>\n</literal></quote> sequences, but it would 14.1354 + have made the style file too difficult to read. Readability 14.1355 + is a good guide when you're trying to decide whether some text 14.1356 + belongs in a style file, or in a template file that the style 14.1357 + file points to. If the style file will look too big or 14.1358 + cluttered if you insert a literal piece of text, drop it into 14.1359 + a template instead.</para> 14.1360 + </sect2> 14.1361 + </sect1> 14.1362 </chapter> 14.1363 14.1364 <!-- 14.1365 local variables: 14.1366 sgml-parent-document: ("00book.xml" "book" "chapter") 14.1367 end: 14.1368 ---> 14.1369 \ No newline at end of file 14.1370 +-->
15.1 --- a/fr/ch12-mq.xml Sat Sep 12 17:58:26 2009 +0200 15.2 +++ b/fr/ch12-mq.xml Sat Sep 12 17:58:56 2009 +0200 15.3 @@ -1,1309 +1,1368 @@ 15.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 15.5 15.6 -<chapter> 15.7 -<title>Managing change with Mercurial Queues</title> 15.8 -<para>\label{chap:mq}</para> 15.9 - 15.10 -<sect1> 15.11 -<title>The patch management problem</title> 15.12 -<para>\label{sec:mq:patch-mgmt}</para> 15.13 - 15.14 -<para>Here is a common scenario: you need to install a software package from 15.15 -source, but you find a bug that you must fix in the source before you 15.16 -can start using the package. You make your changes, forget about the 15.17 -package for a while, and a few months later you need to upgrade to a 15.18 -newer version of the package. If the newer version of the package 15.19 -still has the bug, you must extract your fix from the older source 15.20 -tree and apply it against the newer version. This is a tedious task, 15.21 -and it's easy to make mistakes.</para> 15.22 - 15.23 -<para>This is a simple case of the <quote>patch management</quote> problem. You have 15.24 -an <quote>upstream</quote> source tree that you can't change; you need to make 15.25 -some local changes on top of the upstream tree; and you'd like to be 15.26 -able to keep those changes separate, so that you can apply them to 15.27 -newer versions of the upstream source.</para> 15.28 - 15.29 -<para>The patch management problem arises in many situations. Probably the 15.30 -most visible is that a user of an open source software project will 15.31 -contribute a bug fix or new feature to the project's maintainers in the 15.32 -form of a patch.</para> 15.33 - 15.34 -<para>Distributors of operating systems that include open source software 15.35 -often need to make changes to the packages they distribute so that 15.36 -they will build properly in their environments.</para> 15.37 - 15.38 -<para>When you have few changes to maintain, it is easy to manage a single 15.39 -patch using the standard <command>diff</command> and <command>patch</command> programs 15.40 -(see section <xref linkend="sec:mq:patch"/> for a discussion of these tools). 15.41 -Once the number of changes grows, it starts to make sense to maintain 15.42 -patches as discrete <quote>chunks of work,</quote> so that for example a single 15.43 -patch will contain only one bug fix (the patch might modify several 15.44 -files, but it's doing <quote>only one thing</quote>), and you may have a number 15.45 -of such patches for different bugs you need fixed and local changes 15.46 -you require. In this situation, if you submit a bug fix patch to the 15.47 -upstream maintainers of a package and they include your fix in a 15.48 -subsequent release, you can simply drop that single patch when you're 15.49 -updating to the newer release.</para> 15.50 - 15.51 -<para>Maintaining a single patch against an upstream tree is a little 15.52 -tedious and error-prone, but not difficult. However, the complexity 15.53 -of the problem grows rapidly as the number of patches you have to 15.54 -maintain increases. With more than a tiny number of patches in hand, 15.55 -understanding which ones you have applied and maintaining them moves 15.56 -from messy to overwhelming.</para> 15.57 - 15.58 -<para>Fortunately, Mercurial includes a powerful extension, Mercurial Queues 15.59 -(or simply <quote>MQ</quote>), that massively simplifies the patch management 15.60 -problem. 15.61 -</para> 15.62 - 15.63 -</sect1> 15.64 -<sect1> 15.65 -<title>The prehistory of Mercurial Queues</title> 15.66 -<para>\label{sec:mq:history} 15.67 -</para> 15.68 - 15.69 -<para>During the late 1990s, several Linux kernel developers started to 15.70 -maintain <quote>patch series</quote> that modified the behaviour of the Linux 15.71 -kernel. Some of these series were focused on stability, some on 15.72 -feature coverage, and others were more speculative. 15.73 -</para> 15.74 - 15.75 -<para>The sizes of these patch series grew rapidly. In 2002, Andrew Morton 15.76 -published some shell scripts he had been using to automate the task of 15.77 -managing his patch queues. Andrew was successfully using these 15.78 -scripts to manage hundreds (sometimes thousands) of patches on top of 15.79 -the Linux kernel. 15.80 -</para> 15.81 - 15.82 -<sect2> 15.83 -<title>A patchwork quilt</title> 15.84 -<para>\label{sec:mq:quilt} 15.85 -</para> 15.86 - 15.87 -<para>In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the 15.88 -approach of Andrew's scripts and published a tool called <quote>patchwork 15.89 -quilt</quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote> 15.90 -(see <citation>gruenbacher:2005</citation> for a paper describing it). Because 15.91 -quilt substantially automated patch management, it rapidly gained a 15.92 -large following among open source software developers. 15.93 -</para> 15.94 - 15.95 -<para>Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory tree. 15.96 -To begin, you tell quilt to manage a directory tree, and tell it which 15.97 -files you want to manage; it stores away the names and contents of 15.98 -those files. To fix a bug, you create a new patch (using a single 15.99 -command), edit the files you need to fix, then <quote>refresh</quote> the patch. 15.100 -</para> 15.101 - 15.102 -<para>The refresh step causes quilt to scan the directory tree; it updates 15.103 -the patch with all of the changes you have made. You can create 15.104 -another patch on top of the first, which will track the changes 15.105 -required to modify the tree from <quote>tree with one patch applied</quote> to 15.106 -<quote>tree with two patches applied</quote>. 15.107 -</para> 15.108 - 15.109 -<para>You can <emphasis>change</emphasis> which patches are applied to the tree. If you 15.110 -<quote>pop</quote> a patch, the changes made by that patch will vanish from the 15.111 -directory tree. Quilt remembers which patches you have popped, 15.112 -though, so you can <quote>push</quote> a popped patch again, and the directory 15.113 -tree will be restored to contain the modifications in the patch. Most 15.114 -importantly, you can run the <quote>refresh</quote> command at any time, and the 15.115 -topmost applied patch will be updated. This means that you can, at 15.116 -any time, change both which patches are applied and what 15.117 -modifications those patches make. 15.118 -</para> 15.119 - 15.120 -<para>Quilt knows nothing about revision control tools, so it works equally 15.121 -well on top of an unpacked tarball or a Subversion working copy. 15.122 -</para> 15.123 - 15.124 -</sect2> 15.125 -<sect2> 15.126 -<title>From patchwork quilt to Mercurial Queues</title> 15.127 -<para>\label{sec:mq:quilt-mq} 15.128 -</para> 15.129 - 15.130 -<para>In mid-2005, Chris Mason took the features of quilt and wrote an 15.131 -extension that he called Mercurial Queues, which added quilt-like 15.132 -behaviour to Mercurial. 15.133 -</para> 15.134 - 15.135 -<para>The key difference between quilt and MQ is that quilt knows nothing 15.136 -about revision control systems, while MQ is <emphasis>integrated</emphasis> into 15.137 -Mercurial. Each patch that you push is represented as a Mercurial 15.138 -changeset. Pop a patch, and the changeset goes away. 15.139 -</para> 15.140 - 15.141 -<para>Because quilt does not care about revision control tools, it is still 15.142 -a tremendously useful piece of software to know about for situations 15.143 -where you cannot use Mercurial and MQ. 15.144 -</para> 15.145 - 15.146 -</sect2> 15.147 -</sect1> 15.148 -<sect1> 15.149 -<title>The huge advantage of MQ</title> 15.150 - 15.151 -<para>I cannot overstate the value that MQ offers through the unification of 15.152 -patches and revision control. 15.153 -</para> 15.154 - 15.155 -<para>A major reason that patches have persisted in the free software and 15.156 -open source world&emdash;in spite of the availability of increasingly 15.157 -capable revision control tools over the years&emdash;is the <emphasis>agility</emphasis> 15.158 -they offer. 15.159 -</para> 15.160 - 15.161 -<para>Traditional revision control tools make a permanent, irreversible 15.162 -record of everything that you do. While this has great value, it's 15.163 -also somewhat stifling. If you want to perform a wild-eyed 15.164 -experiment, you have to be careful in how you go about it, or you risk 15.165 -leaving unneeded&emdash;or worse, misleading or destabilising&emdash;traces of 15.166 -your missteps and errors in the permanent revision record. 15.167 -</para> 15.168 - 15.169 -<para>By contrast, MQ's marriage of distributed revision control with 15.170 -patches makes it much easier to isolate your work. Your patches live 15.171 -on top of normal revision history, and you can make them disappear or 15.172 -reappear at will. If you don't like a patch, you can drop it. If a 15.173 -patch isn't quite as you want it to be, simply fix it&emdash;as many times 15.174 -as you need to, until you have refined it into the form you desire. 15.175 -</para> 15.176 - 15.177 -<para>As an example, the integration of patches with revision control makes 15.178 -understanding patches and debugging their effects&emdash;and their 15.179 -interplay with the code they're based on&emdash;<emphasis>enormously</emphasis> easier. 15.180 -Since every applied patch has an associated changeset, you can use 15.181 -<command role="hg-cmd">hg log <emphasis>filename</emphasis></command> to see which changesets and patches 15.182 -affected a file. You can use the <literal role="hg-ext">bisect</literal> command to 15.183 -binary-search through all changesets and applied patches to see where 15.184 -a bug got introduced or fixed. You can use the <command role="hg-cmd">hg annotate</command> 15.185 -command to see which changeset or patch modified a particular line of 15.186 -a source file. And so on. 15.187 -</para> 15.188 - 15.189 -</sect1> 15.190 -<sect1> 15.191 -<title>Understanding patches</title> 15.192 -<para>\label{sec:mq:patch} 15.193 -</para> 15.194 - 15.195 -<para>Because MQ doesn't hide its patch-oriented nature, it is helpful to 15.196 -understand what patches are, and a little about the tools that work 15.197 -with them. 15.198 -</para> 15.199 - 15.200 -<para>The traditional Unix <command>diff</command> command compares two files, and 15.201 -prints a list of differences between them. The <command>patch</command> command 15.202 -understands these differences as <emphasis>modifications</emphasis> to make to a 15.203 -file. Take a look at figure <xref linkend="ex:mq:diff"/> for a simple example of 15.204 -these commands in action. 15.205 -</para> 15.206 - 15.207 -<informalfigure> 15.208 -<para> <!-- &interaction.mq.dodiff.diff; --> 15.209 - <caption><para>Simple uses of the <command>diff</para></caption> and \command{patch</command> commands} 15.210 - \label{ex:mq:diff} 15.211 -</para> 15.212 -</informalfigure> 15.213 - 15.214 -<para>The type of file that <command>diff</command> generates (and <command>patch</command> 15.215 -takes as input) is called a <quote>patch</quote> or a <quote>diff</quote>; there is no 15.216 -difference between a patch and a diff. (We'll use the term <quote>patch</quote>, 15.217 -since it's more commonly used.) 15.218 -</para> 15.219 - 15.220 -<para>A patch file can start with arbitrary text; the <command>patch</command> 15.221 -command ignores this text, but MQ uses it as the commit message when 15.222 -creating changesets. To find the beginning of the patch content, 15.223 -<command>patch</command> searches for the first line that starts with the 15.224 -string <quote><literal>diff -</literal></quote>. 15.225 -</para> 15.226 - 15.227 -<para>MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> can accept several 15.228 -other diff formats, but MQ doesn't). A unified diff contains two 15.229 -kinds of header. The <emphasis>file header</emphasis> describes the file being 15.230 -modified; it contains the name of the file to modify. When 15.231 -<command>patch</command> sees a new file header, it looks for a file with that 15.232 -name to start modifying. 15.233 -</para> 15.234 - 15.235 -<para>After the file header comes a series of <emphasis>hunks</emphasis>. Each hunk 15.236 -starts with a header; this identifies the range of line numbers within 15.237 -the file that the hunk should modify. Following the header, a hunk 15.238 -starts and ends with a few (usually three) lines of text from the 15.239 -unmodified file; these are called the <emphasis>context</emphasis> for the hunk. If 15.240 -there's only a small amount of context between successive hunks, 15.241 -<command>diff</command> doesn't print a new hunk header; it just runs the hunks 15.242 -together, with a few lines of context between modifications. 15.243 -</para> 15.244 - 15.245 -<para>Each line of context begins with a space character. Within the hunk, 15.246 -a line that begins with <quote><literal>-</literal></quote> means <quote>remove this line,</quote> 15.247 -while a line that begins with <quote><literal>+</literal></quote> means <quote>insert this 15.248 -line.</quote> For example, a line that is modified is represented by one 15.249 -deletion and one insertion. 15.250 -</para> 15.251 - 15.252 -<para>We will return to some of the more subtle aspects of patches later (in 15.253 -section <xref linkend="sec:mq:adv-patch"/>), but you should have enough information 15.254 -now to use MQ. 15.255 -</para> 15.256 - 15.257 -</sect1> 15.258 -<sect1> 15.259 -<title>Getting started with Mercurial Queues</title> 15.260 -<para>\label{sec:mq:start} 15.261 -</para> 15.262 - 15.263 -<para>Because MQ is implemented as an extension, you must explicitly enable 15.264 -before you can use it. (You don't need to download anything; MQ ships 15.265 -with the standard Mercurial distribution.) To enable MQ, edit your 15.266 -<filename role="home">~/.hgrc</filename> file, and add the lines in figure <xref linkend="ex:mq:config"/>. 15.267 -</para> 15.268 - 15.269 -<informalfigure> 15.270 -<programlisting> 15.271 -<para> [extensions] 15.272 - hgext.mq = 15.273 -</para> 15.274 -</programlisting> 15.275 -<para> \label{ex:mq:config} 15.276 - <caption><para>Contents to add to <filename role="home">~/.hgrc</para></caption> to enable the MQ extension</filename> 15.277 -</para> 15.278 -</informalfigure> 15.279 - 15.280 -<para>Once the extension is enabled, it will make a number of new commands 15.281 -available. To verify that the extension is working, you can use 15.282 -<command role="hg-cmd">hg help</command> to see if the <command role="hg-ext-mq">qinit</command> command is now available; see 15.283 -the example in figure <xref linkend="ex:mq:enabled"/>. 15.284 -</para> 15.285 - 15.286 -<informalfigure> 15.287 -<para> <!-- &interaction.mq.qinit-help.help; --> 15.288 - <caption><para>How to verify that MQ is enabled</para></caption> 15.289 - \label{ex:mq:enabled} 15.290 -</para> 15.291 -</informalfigure> 15.292 - 15.293 -<para>You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its commands 15.294 -only operate within that repository. To get started, simply prepare 15.295 -the repository using the <command role="hg-ext-mq">qinit</command> command (see 15.296 -figure <xref linkend="ex:mq:qinit"/>). This command creates an empty directory 15.297 -called <filename role="special" class="directory">.hg/patches</filename>, where MQ will keep its metadata. As 15.298 -with many Mercurial commands, the <command role="hg-ext-mq">qinit</command> command prints nothing 15.299 -if it succeeds. 15.300 -</para> 15.301 - 15.302 -<informalfigure> 15.303 -<para> <!-- &interaction.mq.tutorial.qinit; --> 15.304 - <caption><para>Preparing a repository for use with MQ</para></caption> 15.305 - \label{ex:mq:qinit} 15.306 -</para> 15.307 -</informalfigure> 15.308 - 15.309 -<informalfigure> 15.310 -<para> <!-- &interaction.mq.tutorial.qnew; --> 15.311 - <caption><para>Creating a new patch</para></caption> 15.312 - \label{ex:mq:qnew} 15.313 -</para> 15.314 -</informalfigure> 15.315 - 15.316 -<sect2> 15.317 -<title>Creating a new patch</title> 15.318 - 15.319 -<para>To begin work on a new patch, use the <command role="hg-ext-mq">qnew</command> command. This 15.320 -command takes one argument, the name of the patch to create. MQ will 15.321 -use this as the name of an actual file in the <filename role="special" class="directory">.hg/patches</filename> 15.322 -directory, as you can see in figure <xref linkend="ex:mq:qnew"/>. 15.323 -</para> 15.324 - 15.325 -<para>Also newly present in the <filename role="special" class="directory">.hg/patches</filename> directory are two 15.326 -other files, <filename role="special">series</filename> and <filename role="special">status</filename>. The 15.327 -<filename role="special">series</filename> file lists all of the patches that MQ knows about 15.328 -for this repository, with one patch per line. Mercurial uses the 15.329 -<filename role="special">status</filename> file for internal book-keeping; it tracks all of the 15.330 -patches that MQ has <emphasis>applied</emphasis> in this repository. 15.331 -</para> 15.332 - 15.333 -<note> 15.334 -<para> You may sometimes want to edit the <filename role="special">series</filename> file by hand; 15.335 - for example, to change the sequence in which some patches are 15.336 - applied. However, manually editing the <filename role="special">status</filename> file is 15.337 - almost always a bad idea, as it's easy to corrupt MQ's idea of what 15.338 - is happening. 15.339 -</para> 15.340 -</note> 15.341 - 15.342 -<para>Once you have created your new patch, you can edit files in the 15.343 -working directory as you usually would. All of the normal Mercurial 15.344 -commands, such as <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg annotate</command>, work exactly as 15.345 -they did before. 15.346 -</para> 15.347 - 15.348 -</sect2> 15.349 -<sect2> 15.350 -<title>Refreshing a patch</title> 15.351 - 15.352 -<para>When you reach a point where you want to save your work, use the 15.353 -<command role="hg-ext-mq">qrefresh</command> command (figure <xref linkend="ex:mq:qnew"/>) to update the patch 15.354 -you are working on. This command folds the changes you have made in 15.355 -the working directory into your patch, and updates its corresponding 15.356 -changeset to contain those changes. 15.357 -</para> 15.358 - 15.359 -<informalfigure> 15.360 -<para> <!-- &interaction.mq.tutorial.qrefresh; --> 15.361 - <caption><para>Refreshing a patch</para></caption> 15.362 - \label{ex:mq:qrefresh} 15.363 -</para> 15.364 -</informalfigure> 15.365 - 15.366 -<para>You can run <command role="hg-ext-mq">qrefresh</command> as often as you like, so it's a good way 15.367 -to <quote>checkpoint</quote> your work. Refresh your patch at an opportune 15.368 -time; try an experiment; and if the experiment doesn't work out, 15.369 -<command role="hg-cmd">hg revert</command> your modifications back to the last time you refreshed. 15.370 -</para> 15.371 - 15.372 -<informalfigure> 15.373 -<para> <!-- &interaction.mq.tutorial.qrefresh2; --> 15.374 - <caption><para>Refresh a patch many times to accumulate changes</para></caption> 15.375 - \label{ex:mq:qrefresh2} 15.376 -</para> 15.377 -</informalfigure> 15.378 - 15.379 -</sect2> 15.380 -<sect2> 15.381 -<title>Stacking and tracking patches</title> 15.382 - 15.383 -<para>Once you have finished working on a patch, or need to work on another, 15.384 -you can use the <command role="hg-ext-mq">qnew</command> command again to create a new patch. 15.385 -Mercurial will apply this patch on top of your existing patch. See 15.386 -figure <xref linkend="ex:mq:qnew2"/> for an example. Notice that the patch 15.387 -contains the changes in our prior patch as part of its context (you 15.388 -can see this more clearly in the output of <command role="hg-cmd">hg annotate</command>). 15.389 -</para> 15.390 - 15.391 -<informalfigure> 15.392 -<para> <!-- &interaction.mq.tutorial.qnew2; --> 15.393 - <caption><para>Stacking a second patch on top of the first</para></caption> 15.394 - \label{ex:mq:qnew2} 15.395 -</para> 15.396 -</informalfigure> 15.397 - 15.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 15.399 -been careful to only use regular Mercurial commands. However, MQ 15.400 -provides many commands that are easier to use when you are thinking 15.401 -about patches, as illustrated in figure <xref linkend="ex:mq:qseries"/>: 15.402 -</para> 15.403 - 15.404 -<itemizedlist> 15.405 -<listitem><para>The <command role="hg-ext-mq">qseries</command> command lists every patch that MQ knows 15.406 - about in this repository, from oldest to newest (most recently 15.407 - <emphasis>created</emphasis>). 15.408 -</para> 15.409 -</listitem> 15.410 -<listitem><para>The <command role="hg-ext-mq">qapplied</command> command lists every patch that MQ has 15.411 - <emphasis>applied</emphasis> in this repository, again from oldest to newest (most 15.412 - recently applied). 15.413 -</para> 15.414 -</listitem></itemizedlist> 15.415 - 15.416 -<informalfigure> 15.417 -<para> <!-- &interaction.mq.tutorial.qseries; --> 15.418 - \caption{Understanding the patch stack with <command role="hg-ext-mq">qseries</command> and 15.419 - <command role="hg-ext-mq">qapplied</command>} 15.420 - \label{ex:mq:qseries} 15.421 -</para> 15.422 -</informalfigure> 15.423 - 15.424 -</sect2> 15.425 -<sect2> 15.426 -<title>Manipulating the patch stack</title> 15.427 - 15.428 -<para>The previous discussion implied that there must be a difference 15.429 -between <quote>known</quote> and <quote>applied</quote> patches, and there is. MQ can 15.430 -manage a patch without it being applied in the repository. 15.431 -</para> 15.432 - 15.433 -<para>An <emphasis>applied</emphasis> patch has a corresponding changeset in the 15.434 -repository, and the effects of the patch and changeset are visible in 15.435 -the working directory. You can undo the application of a patch using 15.436 -the <command role="hg-ext-mq">qpop</command> command. MQ still <emphasis>knows about</emphasis>, or manages, a 15.437 -popped patch, but the patch no longer has a corresponding changeset in 15.438 -the repository, and the working directory does not contain the changes 15.439 -made by the patch. Figure <xref linkend="fig:mq:stack"/> illustrates the 15.440 -difference between applied and tracked patches. 15.441 -</para> 15.442 - 15.443 -<informalfigure> 15.444 - 15.445 -<para> <mediaobject><imageobject><imagedata fileref="mq-stack"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 15.446 - <caption><para>Applied and unapplied patches in the MQ patch stack</para></caption> 15.447 - \label{fig:mq:stack} 15.448 -</para> 15.449 -</informalfigure> 15.450 - 15.451 -<para>You can reapply an unapplied, or popped, patch using the <command role="hg-ext-mq">qpush</command> 15.452 -command. This creates a new changeset to correspond to the patch, and 15.453 -the patch's changes once again become present in the working 15.454 -directory. See figure <xref linkend="ex:mq:qpop"/> for examples of <command role="hg-ext-mq">qpop</command> 15.455 -and <command role="hg-ext-mq">qpush</command> in action. Notice that once we have popped a patch 15.456 -or two patches, the output of <command role="hg-ext-mq">qseries</command> remains the same, while 15.457 -that of <command role="hg-ext-mq">qapplied</command> has changed. 15.458 -</para> 15.459 - 15.460 -<informalfigure> 15.461 -<para> <!-- &interaction.mq.tutorial.qpop; --> 15.462 - <caption><para>Modifying the stack of applied patches</para></caption> 15.463 - \label{ex:mq:qpop} 15.464 -</para> 15.465 -</informalfigure> 15.466 - 15.467 -</sect2> 15.468 -<sect2> 15.469 -<title>Pushing and popping many patches</title> 15.470 - 15.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 15.472 -a time by default, you can push and pop many patches in one go. The 15.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 15.474 -unapplied patches, while the <option role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command role="hg-ext-mq">qpop</command> 15.475 -causes it to pop all applied patches. (For some more ways to push and 15.476 -pop many patches, see section <xref linkend="sec:mq:perf"/> below.) 15.477 -</para> 15.478 - 15.479 -<informalfigure> 15.480 -<para> <!-- &interaction.mq.tutorial.qpush-a; --> 15.481 - <caption><para>Pushing all unapplied patches</para></caption> 15.482 - \label{ex:mq:qpush-a} 15.483 -</para> 15.484 -</informalfigure> 15.485 - 15.486 -</sect2> 15.487 -<sect2> 15.488 -<title>Safety checks, and overriding them</title> 15.489 - 15.490 -<para>Several MQ commands check the working directory before they do 15.491 -anything, and fail if they find any modifications. They do this to 15.492 -ensure that you won't lose any changes that you have made, but not yet 15.493 -incorporated into a patch. Figure <xref linkend="ex:mq:add"/> illustrates this; 15.494 -the <command role="hg-ext-mq">qnew</command> command will not create a new patch if there are 15.495 -outstanding changes, caused in this case by the <command role="hg-cmd">hg add</command> of 15.496 -<filename>file3</filename>. 15.497 -</para> 15.498 - 15.499 -<informalfigure> 15.500 -<para> <!-- &interaction.mq.tutorial.add; --> 15.501 - <caption><para>Forcibly creating a patch</para></caption> 15.502 - \label{ex:mq:add} 15.503 -</para> 15.504 -</informalfigure> 15.505 - 15.506 -<para>Commands that check the working directory all take an <quote>I know what 15.507 -I'm doing</quote> option, which is always named <option>-f</option>. The exact 15.508 -meaning of <option>-f</option> depends on the command. For example, 15.509 -<command role="hg-cmd">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">-f</option></command> will incorporate any outstanding 15.510 -changes into the new patch it creates, but 15.511 -<command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-f</option></command> will revert modifications to any 15.512 -files affected by the patch that it is popping. Be sure to read the 15.513 -documentation for a command's <option>-f</option> option before you use it! 15.514 -</para> 15.515 - 15.516 -</sect2> 15.517 -<sect2> 15.518 -<title>Working on several patches at once</title> 15.519 - 15.520 -<para>The <command role="hg-ext-mq">qrefresh</command> command always refreshes the <emphasis>topmost</emphasis> 15.521 -applied patch. This means that you can suspend work on one patch (by 15.522 -refreshing it), pop or push to make a different patch the top, and 15.523 -work on <emphasis>that</emphasis> patch for a while. 15.524 -</para> 15.525 - 15.526 -<para>Here's an example that illustrates how you can use this ability. 15.527 -Let's say you're developing a new feature as two patches. The first 15.528 -is a change to the core of your software, and the second&emdash;layered on 15.529 -top of the first&emdash;changes the user interface to use the code you just 15.530 -added to the core. If you notice a bug in the core while you're 15.531 -working on the UI patch, it's easy to fix the core. Simply 15.532 -<command role="hg-ext-mq">qrefresh</command> the UI patch to save your in-progress changes, and 15.533 -<command role="hg-ext-mq">qpop</command> down to the core patch. Fix the core bug, 15.534 -<command role="hg-ext-mq">qrefresh</command> the core patch, and <command role="hg-ext-mq">qpush</command> back to the UI 15.535 -patch to continue where you left off. 15.536 -</para> 15.537 - 15.538 -</sect2> 15.539 -</sect1> 15.540 -<sect1> 15.541 -<title>More about patches</title> 15.542 -<para>\label{sec:mq:adv-patch} 15.543 -</para> 15.544 - 15.545 -<para>MQ uses the GNU <command>patch</command> command to apply patches, so it's 15.546 -helpful to know a few more detailed aspects of how <command>patch</command> 15.547 -works, and about patches themselves. 15.548 -</para> 15.549 - 15.550 -<sect2> 15.551 -<title>The strip count</title> 15.552 - 15.553 -<para>If you look at the file headers in a patch, you will notice that the 15.554 -pathnames usually have an extra component on the front that isn't 15.555 -present in the actual path name. This is a holdover from the way that 15.556 -people used to generate patches (people still do this, but it's 15.557 -somewhat rare with modern revision control tools). 15.558 -</para> 15.559 - 15.560 -<para>Alice would unpack a tarball, edit her files, then decide that she 15.561 -wanted to create a patch. So she'd rename her working directory, 15.562 -unpack the tarball again (hence the need for the rename), and use the 15.563 -<option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to <command>diff</command> to 15.564 -recursively generate a patch between the unmodified directory and the 15.565 -modified one. The result would be that the name of the unmodified 15.566 -directory would be at the front of the left-hand path in every file 15.567 -header, and the name of the modified directory would be at the front 15.568 -of the right-hand path. 15.569 -</para> 15.570 - 15.571 -<para>Since someone receiving a patch from the Alices of the net would be 15.572 -unlikely to have unmodified and modified directories with exactly the 15.573 -same names, the <command>patch</command> command has a <option role="cmd-opt-patch">-p</option> 15.574 -option that indicates the number of leading path name components to 15.575 -strip when trying to apply a patch. This number is called the 15.576 -<emphasis>strip count</emphasis>. 15.577 -</para> 15.578 - 15.579 -<para>An option of <quote><literal>-p1</literal></quote> means <quote>use a strip count of one</quote>. If 15.580 -<command>patch</command> sees a file name <filename>foo/bar/baz</filename> in a file 15.581 -header, it will strip <filename>foo</filename> and try to patch a file named 15.582 -<filename>bar/baz</filename>. (Strictly speaking, the strip count refers to the 15.583 -number of <emphasis>path separators</emphasis> (and the components that go with them 15.584 -) to strip. A strip count of one will turn <filename>foo/bar</filename> into 15.585 -<filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra leading 15.586 -slash) into <filename>foo/bar</filename>.) 15.587 -</para> 15.588 - 15.589 -<para>The <quote>standard</quote> strip count for patches is one; almost all patches 15.590 -contain one leading path name component that needs to be stripped. 15.591 -Mercurial's <command role="hg-cmd">hg diff</command> command generates path names in this form, 15.592 -and the <command role="hg-cmd">hg import</command> command and MQ expect patches to have a strip 15.593 -count of one. 15.594 -</para> 15.595 - 15.596 -<para>If you receive a patch from someone that you want to add to your patch 15.597 -queue, and the patch needs a strip count other than one, you cannot 15.598 -just <command role="hg-ext-mq">qimport</command> the patch, because <command role="hg-ext-mq">qimport</command> does not yet 15.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 15.600 -<command role="hg-ext-mq">qnew</command> a patch of your own, then use <command>patch -p<emphasis>N</emphasis></command> 15.601 -to apply their patch, followed by <command role="hg-cmd">hg addremove</command> to pick up any 15.602 -files added or removed by the patch, followed by <command role="hg-ext-mq">qrefresh</command>. 15.603 -This complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue 311</ulink> for details. 15.604 -</sect2> 15.605 -<sect2> 15.606 -<title>Strategies for applying a patch</title> 15.607 -</para> 15.608 - 15.609 -<para>When <command>patch</command> applies a hunk, it tries a handful of 15.610 -successively less accurate strategies to try to make the hunk apply. 15.611 -This falling-back technique often makes it possible to take a patch 15.612 -that was generated against an old version of a file, and apply it 15.613 -against a newer version of that file. 15.614 -</para> 15.615 - 15.616 -<para>First, <command>patch</command> tries an exact match, where the line numbers, 15.617 -the context, and the text to be modified must apply exactly. If it 15.618 -cannot make an exact match, it tries to find an exact match for the 15.619 -context, without honouring the line numbering information. If this 15.620 -succeeds, it prints a line of output saying that the hunk was applied, 15.621 -but at some <emphasis>offset</emphasis> from the original line number. 15.622 -</para> 15.623 - 15.624 -<para>If a context-only match fails, <command>patch</command> removes the first and 15.625 -last lines of the context, and tries a <emphasis>reduced</emphasis> context-only 15.626 -match. If the hunk with reduced context succeeds, it prints a message 15.627 -saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the number 15.628 -after the fuzz factor indicates how many lines of context 15.629 -<command>patch</command> had to trim before the patch applied). 15.630 -</para> 15.631 - 15.632 -<para>When neither of these techniques works, <command>patch</command> prints a 15.633 -message saying that the hunk in question was rejected. It saves 15.634 -rejected hunks (also simply called <quote>rejects</quote>) to a file with the 15.635 -same name, and an added <filename role="special">.rej</filename> extension. It also saves an 15.636 -unmodified copy of the file with a <filename role="special">.orig</filename> extension; the 15.637 -copy of the file without any extensions will contain any changes made 15.638 -by hunks that <emphasis>did</emphasis> apply cleanly. If you have a patch that 15.639 -modifies <filename>foo</filename> with six hunks, and one of them fails to 15.640 -apply, you will have: an unmodified <filename>foo.orig</filename>, a 15.641 -<filename>foo.rej</filename> containing one hunk, and <filename>foo</filename>, containing 15.642 -the changes made by the five successful hunks. 15.643 -</para> 15.644 - 15.645 -</sect2> 15.646 -<sect2> 15.647 -<title>Some quirks of patch representation</title> 15.648 - 15.649 -<para>There are a few useful things to know about how <command>patch</command> works 15.650 -with files. 15.651 -</para> 15.652 -<itemizedlist> 15.653 -<listitem><para>This should already be obvious, but <command>patch</command> cannot 15.654 - handle binary files. 15.655 -</para> 15.656 -</listitem> 15.657 -<listitem><para>Neither does it care about the executable bit; it creates new 15.658 - files as readable, but not executable. 15.659 -</para> 15.660 -</listitem> 15.661 -<listitem><para><command>patch</command> treats the removal of a file as a diff between 15.662 - the file to be removed and the empty file. So your idea of <quote>I 15.663 - deleted this file</quote> looks like <quote>every line of this file was 15.664 - deleted</quote> in a patch. 15.665 -</para> 15.666 -</listitem> 15.667 -<listitem><para>It treats the addition of a file as a diff between the empty 15.668 - file and the file to be added. So in a patch, your idea of <quote>I 15.669 - added this file</quote> looks like <quote>every line of this file was added</quote>. 15.670 -</para> 15.671 -</listitem> 15.672 -<listitem><para>It treats a renamed file as the removal of the old name, and the 15.673 - addition of the new name. This means that renamed files have a big 15.674 - footprint in patches. (Note also that Mercurial does not currently 15.675 - try to infer when files have been renamed or copied in a patch.) 15.676 -</para> 15.677 -</listitem> 15.678 -<listitem><para><command>patch</command> cannot represent empty files, so you cannot use 15.679 - a patch to represent the notion <quote>I added this empty file to the 15.680 - tree</quote>. 15.681 -</para> 15.682 -</listitem></itemizedlist> 15.683 -</sect2> 15.684 -<sect2> 15.685 -<title>Beware the fuzz</title> 15.686 - 15.687 -<para>While applying a hunk at an offset, or with a fuzz factor, will often 15.688 -be completely successful, these inexact techniques naturally leave 15.689 -open the possibility of corrupting the patched file. The most common 15.690 -cases typically involve applying a patch twice, or at an incorrect 15.691 -location in the file. If <command>patch</command> or <command role="hg-ext-mq">qpush</command> ever 15.692 -mentions an offset or fuzz factor, you should make sure that the 15.693 -modified files are correct afterwards. 15.694 -</para> 15.695 - 15.696 -<para>It's often a good idea to refresh a patch that has applied with an 15.697 -offset or fuzz factor; refreshing the patch generates new context 15.698 -information that will make it apply cleanly. I say <quote>often,</quote> not 15.699 -<quote>always,</quote> because sometimes refreshing a patch will make it fail to 15.700 -apply against a different revision of the underlying files. In some 15.701 -cases, such as when you're maintaining a patch that must sit on top of 15.702 -multiple versions of a source tree, it's acceptable to have a patch 15.703 -apply with some fuzz, provided you've verified the results of the 15.704 -patching process in such cases. 15.705 -</para> 15.706 - 15.707 -</sect2> 15.708 -<sect2> 15.709 -<title>Handling rejection</title> 15.710 - 15.711 -<para>If <command role="hg-ext-mq">qpush</command> fails to apply a patch, it will print an error 15.712 -message and exit. If it has left <filename role="special">.rej</filename> files behind, it is 15.713 -usually best to fix up the rejected hunks before you push more patches 15.714 -or do any further work. 15.715 -</para> 15.716 - 15.717 -<para>If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does because 15.718 -you've changed the underlying code that your patches are based on, 15.719 -Mercurial Queues can help; see section <xref linkend="sec:mq:merge"/> for details. 15.720 -</para> 15.721 - 15.722 -<para>Unfortunately, there aren't any great techniques for dealing with 15.723 -rejected hunks. Most often, you'll need to view the <filename role="special">.rej</filename> 15.724 -file and edit the target file, applying the rejected hunks by hand. 15.725 -</para> 15.726 - 15.727 -<para>If you're feeling adventurous, Neil Brown, a Linux kernel hacker, 15.728 -wrote a tool called <command>wiggle</command> <citation>web:wiggle</citation>, which is more 15.729 -vigorous than <command>patch</command> in its attempts to make a patch apply. 15.730 -</para> 15.731 - 15.732 -<para>Another Linux kernel hacker, Chris Mason (the author of Mercurial 15.733 -Queues), wrote a similar tool called 15.734 -<command>mpatch</command> <citation>web:mpatch</citation>, which takes a simple approach to 15.735 -automating the application of hunks rejected by <command>patch</command>. The 15.736 -<command>mpatch</command> command can help with four common reasons that a hunk 15.737 -may be rejected: 15.738 -</para> 15.739 - 15.740 -<itemizedlist> 15.741 -<listitem><para>The context in the middle of a hunk has changed. 15.742 -</para> 15.743 -</listitem> 15.744 -<listitem><para>A hunk is missing some context at the beginning or end. 15.745 -</para> 15.746 -</listitem> 15.747 -<listitem><para>A large hunk might apply better&emdash;either entirely or in 15.748 - part&emdash;if it was broken up into smaller hunks. 15.749 -</para> 15.750 -</listitem> 15.751 -<listitem><para>A hunk removes lines with slightly different content than those 15.752 - currently present in the file. 15.753 -</para> 15.754 -</listitem></itemizedlist> 15.755 - 15.756 -<para>If you use <command>wiggle</command> or <command>mpatch</command>, you should be doubly 15.757 -careful to check your results when you're done. In fact, 15.758 -<command>mpatch</command> enforces this method of double-checking the tool's 15.759 -output, by automatically dropping you into a merge program when it has 15.760 -done its job, so that you can verify its work and finish off any 15.761 -remaining merges. 15.762 -</para> 15.763 - 15.764 -</sect2> 15.765 -</sect1> 15.766 -<sect1> 15.767 -<title>Getting the best performance out of MQ</title> 15.768 -<para>\label{sec:mq:perf} 15.769 -</para> 15.770 - 15.771 -<para>MQ is very efficient at handling a large number of patches. I ran 15.772 -some performance experiments in mid-2006 for a talk that I gave at the 15.773 -2006 EuroPython conference <citation>web:europython</citation>. I used as my data 15.774 -set the Linux 2.6.17-mm1 patch series, which consists of 1,738 15.775 -patches. I applied these on top of a Linux kernel repository 15.776 -containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux 15.777 -2.6.17. 15.778 -</para> 15.779 - 15.780 -<para>On my old, slow laptop, I was able to 15.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, 15.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 15.783 -newer laptop, the time to push all patches dropped to two minutes.) I 15.784 -could <command role="hg-ext-mq">qrefresh</command> one of the biggest patches (which made 22,779 15.785 -lines of changes to 287 files) in 6.6 seconds. 15.786 -</para> 15.787 - 15.788 -<para>Clearly, MQ is well suited to working in large trees, but there are a 15.789 -few tricks you can use to get the best performance of it. 15.790 -</para> 15.791 - 15.792 -<para>First of all, try to <quote>batch</quote> operations together. Every time you 15.793 -run <command role="hg-ext-mq">qpush</command> or <command role="hg-ext-mq">qpop</command>, these commands scan the working 15.794 -directory once to make sure you haven't made some changes and then 15.795 -forgotten to run <command role="hg-ext-mq">qrefresh</command>. On a small tree, the time that 15.796 -this scan takes is unnoticeable. However, on a medium-sized tree 15.797 -(containing tens of thousands of files), it can take a second or more. 15.798 -</para> 15.799 - 15.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 15.801 -multiple patches at a time. You can identify the <quote>destination 15.802 -patch</quote> that you want to end up at. When you <command role="hg-ext-mq">qpush</command> with a 15.803 -destination specified, it will push patches until that patch is at the 15.804 -top of the applied stack. When you <command role="hg-ext-mq">qpop</command> to a destination, MQ 15.805 -will pop patches until the destination patch is at the top. 15.806 -</para> 15.807 - 15.808 -<para>You can identify a destination patch using either the name of the 15.809 -patch, or by number. If you use numeric addressing, patches are 15.810 -counted from zero; this means that the first patch is zero, the second 15.811 -is one, and so on. 15.812 -</para> 15.813 - 15.814 -</sect1> 15.815 -<sect1> 15.816 -<title>Updating your patches when the underlying code changes</title> 15.817 -<para>\label{sec:mq:merge} 15.818 -</para> 15.819 - 15.820 -<para>It's common to have a stack of patches on top of an underlying 15.821 -repository that you don't modify directly. If you're working on 15.822 -changes to third-party code, or on a feature that is taking longer to 15.823 -develop than the rate of change of the code beneath, you will often 15.824 -need to sync up with the underlying code, and fix up any hunks in your 15.825 -patches that no longer apply. This is called <emphasis>rebasing</emphasis> your 15.826 -patch series. 15.827 -</para> 15.828 - 15.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> 15.830 -your patches, then <command role="hg-cmd">hg pull</command> changes into the underlying 15.831 -repository, and finally <command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> your 15.832 -patches again. MQ will stop pushing any time it runs across a patch 15.833 -that fails to apply during conflicts, allowing you to fix your 15.834 -conflicts, <command role="hg-ext-mq">qrefresh</command> the affected patch, and continue pushing 15.835 -until you have fixed your entire stack. 15.836 -</para> 15.837 - 15.838 -<para>This approach is easy to use and works well if you don't expect 15.839 -changes to the underlying code to affect how well your patches apply. 15.840 -If your patch stack touches code that is modified frequently or 15.841 -invasively in the underlying repository, however, fixing up rejected 15.842 -hunks by hand quickly becomes tiresome. 15.843 -</para> 15.844 - 15.845 -<para>It's possible to partially automate the rebasing process. If your 15.846 -patches apply cleanly against some revision of the underlying repo, MQ 15.847 -can use this information to help you to resolve conflicts between your 15.848 -patches and a different revision. 15.849 -</para> 15.850 - 15.851 -<para>The process is a little involved. 15.852 -</para> 15.853 -<orderedlist> 15.854 -<listitem><para>To begin, <command role="hg-cmd">hg qpush -a</command> all of your patches on top of 15.855 - the revision where you know that they apply cleanly. 15.856 -</para> 15.857 -</listitem> 15.858 -<listitem><para>Save a backup copy of your patch directory using 15.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 15.860 - the name of the directory that it has saved the patches in. It will 15.861 - save the patches to a directory called 15.862 - <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>, where <literal><emphasis>N</emphasis></literal> is a small 15.863 - integer. It also commits a <quote>save changeset</quote> on top of your 15.864 - applied patches; this is for internal book-keeping, and records the 15.865 - states of the <filename role="special">series</filename> and <filename role="special">status</filename> files. 15.866 -</para> 15.867 -</listitem> 15.868 -<listitem><para>Use <command role="hg-cmd">hg pull</command> to bring new changes into the underlying 15.869 - repository. (Don't run <command role="hg-cmd">hg pull -u</command>; see below for why.) 15.870 -</para> 15.871 -</listitem> 15.872 -<listitem><para>Update to the new tip revision, using 15.873 - <command role="hg-cmd">hg update <option role="hg-opt-update">-C</option></command> to override the patches you 15.874 - have pushed. 15.875 -</para> 15.876 -</listitem> 15.877 -<listitem><para>Merge all patches using \hgcmdargs{qpush}{<option role="hg-ext-mq-cmd-qpush-opt">-m</option> 15.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> 15.879 - tells MQ to perform a three-way merge if the patch fails to apply. 15.880 -</para> 15.881 -</listitem></orderedlist> 15.882 - 15.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 15.884 -<filename role="special">series</filename> file is applied normally. If a patch applies with 15.885 -fuzz or rejects, MQ looks at the queue you <command role="hg-ext-mq">qsave</command>d, and 15.886 -performs a three-way merge with the corresponding changeset. This 15.887 -merge uses Mercurial's normal merge machinery, so it may pop up a GUI 15.888 -merge tool to help you to resolve problems. 15.889 -</para> 15.890 - 15.891 -<para>When you finish resolving the effects of a patch, MQ refreshes your 15.892 -patch based on the result of the merge. 15.893 -</para> 15.894 - 15.895 -<para>At the end of this process, your repository will have one extra head 15.896 -from the old patch queue, and a copy of the old patch queue will be in 15.897 -<filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis>. You can remove the extra head using 15.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> 15.899 -or <command role="hg-cmd">hg strip</command>. You can delete <filename role="special" class="directory">.hg/patches.<emphasis>N</filename></emphasis> once 15.900 -you are sure that you no longer need it as a backup. 15.901 -</para> 15.902 - 15.903 -</sect1> 15.904 -<sect1> 15.905 -<title>Identifying patches</title> 15.906 - 15.907 -<para>MQ commands that work with patches let you refer to a patch either by 15.908 -using its name or by a number. By name is obvious enough; pass the 15.909 -name <filename>foo.patch</filename> to <command role="hg-ext-mq">qpush</command>, for example, and it will 15.910 -push patches until <filename>foo.patch</filename> is applied. 15.911 -</para> 15.912 - 15.913 -<para>As a shortcut, you can refer to a patch using both a name and a 15.914 -numeric offset; <literal>foo.patch-2</literal> means <quote>two patches before 15.915 -<literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> means <quote>four patches 15.916 -after <literal>bar.patch</literal></quote>. 15.917 -</para> 15.918 - 15.919 -<para>Referring to a patch by index isn't much different. The first patch 15.920 -printed in the output of <command role="hg-ext-mq">qseries</command> is patch zero (yes, it's one 15.921 -of those start-at-zero counting systems); the second is patch one; and 15.922 -so on. 15.923 -</para> 15.924 - 15.925 -<para>MQ also makes it easy to work with patches when you are using normal 15.926 -Mercurial commands. Every command that accepts a changeset ID will 15.927 -also accept the name of an applied patch. MQ augments the tags 15.928 -normally in the repository with an eponymous one for each applied 15.929 -patch. In addition, the special tags \index{tags!special tag 15.930 - names!<literal>qbase</literal>}<literal>qbase</literal> and \index{tags!special tag 15.931 - names!<literal>qtip</literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and 15.932 -topmost applied patches, respectively. 15.933 -</para> 15.934 - 15.935 -<para>These additions to Mercurial's normal tagging capabilities make 15.936 -dealing with patches even more of a breeze. 15.937 -</para> 15.938 -<itemizedlist> 15.939 -<listitem><para>Want to patchbomb a mailing list with your latest series of 15.940 - changes? 15.941 -</para> 15.942 -</listitem><programlisting> 15.943 -<listitem><para> hg email qbase:qtip 15.944 -</para> 15.945 -</listitem></programlisting> 15.946 -<listitem><para> (Don't know what <quote>patchbombing</quote> is? See 15.947 - section <xref linkend="sec:hgext:patchbomb"/>.) 15.948 -</para> 15.949 -</listitem> 15.950 -<listitem><para>Need to see all of the patches since <literal>foo.patch</literal> that 15.951 - have touched files in a subdirectory of your tree? 15.952 -</para> 15.953 -</listitem><programlisting> 15.954 -<listitem><para> hg log -r foo.patch:qtip <emphasis>subdir</emphasis> 15.955 -</para> 15.956 -</listitem></programlisting> 15.957 -</itemizedlist> 15.958 - 15.959 -<para>Because MQ makes the names of patches available to the rest of 15.960 -Mercurial through its normal internal tag machinery, you don't need to 15.961 -type in the entire name of a patch when you want to identify it by 15.962 -name. 15.963 -</para> 15.964 - 15.965 -<informalfigure> 15.966 -<para> <!-- &interaction.mq.id.output; --> 15.967 - <caption><para>Using MQ's tag features to work with patches</para></caption> 15.968 - \label{ex:mq:id} 15.969 -</para> 15.970 -</informalfigure> 15.971 - 15.972 -<para>Another nice consequence of representing patch names as tags is that 15.973 -when you run the <command role="hg-cmd">hg log</command> command, it will display a patch's name 15.974 -as a tag, simply as part of its normal output. This makes it easy to 15.975 -visually distinguish applied patches from underlying <quote>normal</quote> 15.976 -revisions. Figure <xref linkend="ex:mq:id"/> shows a few normal Mercurial 15.977 -commands in use with applied patches. 15.978 -</para> 15.979 - 15.980 -</sect1> 15.981 -<sect1> 15.982 -<title>Useful things to know about</title> 15.983 - 15.984 -<para>There are a number of aspects of MQ usage that don't fit tidily into 15.985 -sections of their own, but that are good to know. Here they are, in 15.986 -one place. 15.987 -</para> 15.988 - 15.989 -<itemizedlist> 15.990 -<listitem><para>Normally, when you <command role="hg-ext-mq">qpop</command> a patch and <command role="hg-ext-mq">qpush</command> it 15.991 - again, the changeset that represents the patch after the pop/push 15.992 - will have a <emphasis>different identity</emphasis> than the changeset that 15.993 - represented the hash beforehand. See 15.994 - section <xref linkend="sec:mqref:cmd:qpush"/> for information as to why this is. 15.995 -</para> 15.996 -</listitem> 15.997 -<listitem><para>It's not a good idea to <command role="hg-cmd">hg merge</command> changes from another 15.998 - branch with a patch changeset, at least if you want to maintain the 15.999 - <quote>patchiness</quote> of that changeset and changesets below it on the 15.1000 - patch stack. If you try to do this, it will appear to succeed, but 15.1001 - MQ will become confused. 15.1002 -</para> 15.1003 -</listitem></itemizedlist> 15.1004 - 15.1005 -</sect1> 15.1006 -<sect1> 15.1007 -<title>Managing patches in a repository</title> 15.1008 -<para>\label{sec:mq:repo} 15.1009 -</para> 15.1010 - 15.1011 -<para>Because MQ's <filename role="special" class="directory">.hg/patches</filename> directory resides outside a 15.1012 -Mercurial repository's working directory, the <quote>underlying</quote> Mercurial 15.1013 -repository knows nothing about the management or presence of patches. 15.1014 -</para> 15.1015 - 15.1016 -<para>This presents the interesting possibility of managing the contents of 15.1017 -the patch directory as a Mercurial repository in its own right. This 15.1018 -can be a useful way to work. For example, you can work on a patch for 15.1019 -a while, <command role="hg-ext-mq">qrefresh</command> it, then <command role="hg-cmd">hg commit</command> the current state of 15.1020 -the patch. This lets you <quote>roll back</quote> to that version of the patch 15.1021 -later on. 15.1022 -</para> 15.1023 - 15.1024 -<para>You can then share different versions of the same patch stack among 15.1025 -multiple underlying repositories. I use this when I am developing a 15.1026 -Linux kernel feature. I have a pristine copy of my kernel sources for 15.1027 -each of several CPU architectures, and a cloned repository under each 15.1028 -that contains the patches I am working on. When I want to test a 15.1029 -change on a different architecture, I push my current patches to the 15.1030 -patch repository associated with that kernel tree, pop and push all of 15.1031 -my patches, and build and test that kernel. 15.1032 -</para> 15.1033 - 15.1034 -<para>Managing patches in a repository makes it possible for multiple 15.1035 -developers to work on the same patch series without colliding with 15.1036 -each other, all on top of an underlying source base that they may or 15.1037 -may not control. 15.1038 -</para> 15.1039 - 15.1040 -<sect2> 15.1041 -<title>MQ support for patch repositories</title> 15.1042 - 15.1043 -<para>MQ helps you to work with the <filename role="special" class="directory">.hg/patches</filename> directory as a 15.1044 -repository; when you prepare a repository for working with patches 15.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 15.1046 -create the <filename role="special" class="directory">.hg/patches</filename> directory as a Mercurial repository. 15.1047 -</para> 15.1048 - 15.1049 -<note> 15.1050 -<para> If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">-c</option> option, you can simply go 15.1051 - into the <filename role="special" class="directory">.hg/patches</filename> directory at any time and run 15.1052 - <command role="hg-cmd">hg init</command>. Don't forget to add an entry for the 15.1053 - <filename role="special">status</filename> file to the <filename role="special">.hgignore</filename> file, though 15.1054 -</para> 15.1055 - 15.1056 -<para> (<command role="hg-cmd">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> does this for you 15.1057 - automatically); you <emphasis>really</emphasis> don't want to manage the 15.1058 - <filename role="special">status</filename> file. 15.1059 -</para> 15.1060 -</note> 15.1061 - 15.1062 -<para>As a convenience, if MQ notices that the <filename class="directory">.hg/patches</filename> 15.1063 -directory is a repository, it will automatically <command role="hg-cmd">hg add</command> every 15.1064 -patch that you create and import. 15.1065 -</para> 15.1066 - 15.1067 -<para>MQ provides a shortcut command, <command role="hg-ext-mq">qcommit</command>, that runs 15.1068 -<command role="hg-cmd">hg commit</command> in the <filename role="special" class="directory">.hg/patches</filename> directory. This saves 15.1069 -some bothersome typing. 15.1070 -</para> 15.1071 - 15.1072 -<para>Finally, as a convenience to manage the patch directory, you can 15.1073 -define the alias <command>mq</command> on Unix systems. For example, on Linux 15.1074 -systems using the <command>bash</command> shell, you can include the following 15.1075 -snippet in your <filename role="home">~/.bashrc</filename>. 15.1076 -</para> 15.1077 - 15.1078 -<programlisting> 15.1079 -<para> alias mq=`hg -R $(hg root)/.hg/patches' 15.1080 -</para> 15.1081 -</programlisting> 15.1082 - 15.1083 -<para>You can then issue commands of the form <command>mq pull</command> from 15.1084 -the main repository. 15.1085 -</para> 15.1086 - 15.1087 -</sect2> 15.1088 -<sect2> 15.1089 -<title>A few things to watch out for</title> 15.1090 - 15.1091 -<para>MQ's support for working with a repository full of patches is limited 15.1092 -in a few small respects. 15.1093 -</para> 15.1094 - 15.1095 -<para>MQ cannot automatically detect changes that you make to the patch 15.1096 -directory. If you <command role="hg-cmd">hg pull</command>, manually edit, or <command role="hg-cmd">hg update</command> 15.1097 -changes to patches or the <filename role="special">series</filename> file, you will have to 15.1098 -<command role="hg-cmd">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">-a</option></command> and then 15.1099 -<command role="hg-cmd">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">-a</option></command> in the underlying repository to 15.1100 -see those changes show up there. If you forget to do this, you can 15.1101 -confuse MQ's idea of which patches are applied. 15.1102 -</para> 15.1103 - 15.1104 -</sect2> 15.1105 -</sect1> 15.1106 -<sect1> 15.1107 -<title>Third party tools for working with patches</title> 15.1108 -<para>\label{sec:mq:tools} 15.1109 -</para> 15.1110 - 15.1111 -<para>Once you've been working with patches for a while, you'll find 15.1112 -yourself hungry for tools that will help you to understand and 15.1113 -manipulate the patches you're dealing with. 15.1114 -</para> 15.1115 - 15.1116 -<para>The <command>diffstat</command> command <citation>web:diffstat</citation> generates a 15.1117 -histogram of the modifications made to each file in a patch. It 15.1118 -provides a good way to <quote>get a sense of</quote> a patch&emdash;which files it 15.1119 -affects, and how much change it introduces to each file and as a 15.1120 -whole. (I find that it's a good idea to use <command>diffstat</command>'s 15.1121 -<option role="cmd-opt-diffstat">-p</option> option as a matter of course, as otherwise it 15.1122 -will try to do clever things with prefixes of file names that 15.1123 -inevitably confuse at least me.) 15.1124 -</para> 15.1125 - 15.1126 -<informalfigure> 15.1127 -<para> <!-- &interaction.mq.tools.tools; --> 15.1128 - <caption><para>The <command>diffstat</para></caption>, \command{filterdiff</command>, and <command>lsdiff</command> commands} 15.1129 - \label{ex:mq:tools} 15.1130 -</para> 15.1131 -</informalfigure> 15.1132 - 15.1133 -<para>The <literal role="package">patchutils</literal> package <citation>web:patchutils</citation> is invaluable. 15.1134 -It provides a set of small utilities that follow the <quote>Unix 15.1135 -philosophy;</quote> each does one useful thing with a patch. The 15.1136 -<literal role="package">patchutils</literal> command I use most is <command>filterdiff</command>, which 15.1137 -extracts subsets from a patch file. For example, given a patch that 15.1138 -modifies hundreds of files across dozens of directories, a single 15.1139 -invocation of <command>filterdiff</command> can generate a smaller patch that 15.1140 -only touches files whose names match a particular glob pattern. See 15.1141 -section <xref linkend="mq-collab:tips:interdiff"/> for another example. 15.1142 -</para> 15.1143 - 15.1144 -</sect1> 15.1145 -<sect1> 15.1146 -<title>Good ways to work with patches</title> 15.1147 - 15.1148 -<para>Whether you are working on a patch series to submit to a free software 15.1149 -or open source project, or a series that you intend to treat as a 15.1150 -sequence of regular changesets when you're done, you can use some 15.1151 -simple techniques to keep your work well organised. 15.1152 -</para> 15.1153 - 15.1154 -<para>Give your patches descriptive names. A good name for a patch might be 15.1155 -<filename>rework-device-alloc.patch</filename>, because it will immediately give 15.1156 -you a hint what the purpose of the patch is. Long names shouldn't be 15.1157 -a problem; you won't be typing the names often, but you <emphasis>will</emphasis> be 15.1158 -running commands like <command role="hg-ext-mq">qapplied</command> and <command role="hg-ext-mq">qtop</command> over and over. 15.1159 -Good naming becomes especially important when you have a number of 15.1160 -patches to work with, or if you are juggling a number of different 15.1161 -tasks and your patches only get a fraction of your attention. 15.1162 -</para> 15.1163 - 15.1164 -<para>Be aware of what patch you're working on. Use the <command role="hg-ext-mq">qtop</command> 15.1165 -command and skim over the text of your patches frequently&emdash;for 15.1166 -example, using <command role="hg-cmd">hg tip <option role="hg-opt-tip">-p</option></command>)&emdash;to be sure of where 15.1167 -you stand. I have several times worked on and <command role="hg-ext-mq">qrefresh</command>ed a 15.1168 -patch other than the one I intended, and it's often tricky to migrate 15.1169 -changes into the right patch after making them in the wrong one. 15.1170 -</para> 15.1171 - 15.1172 -<para>For this reason, it is very much worth investing a little time to 15.1173 -learn how to use some of the third-party tools I described in 15.1174 -section <xref linkend="sec:mq:tools"/>, particularly <command>diffstat</command> and 15.1175 -<command>filterdiff</command>. The former will give you a quick idea of what 15.1176 -changes your patch is making, while the latter makes it easy to splice 15.1177 -hunks selectively out of one patch and into another. 15.1178 -</para> 15.1179 - 15.1180 -</sect1> 15.1181 -<sect1> 15.1182 -<title>MQ cookbook</title> 15.1183 - 15.1184 -<sect2> 15.1185 -<title>Manage <quote>trivial</quote> patches</title> 15.1186 - 15.1187 -<para>Because the overhead of dropping files into a new Mercurial repository 15.1188 -is so low, it makes a lot of sense to manage patches this way even if 15.1189 -you simply want to make a few changes to a source tarball that you 15.1190 -downloaded. 15.1191 -</para> 15.1192 - 15.1193 -<para>Begin by downloading and unpacking the source tarball, 15.1194 -and turning it into a Mercurial repository. 15.1195 -<!-- &interaction.mq.tarball.download; --> 15.1196 -</para> 15.1197 - 15.1198 -<para>Continue by creating a patch stack and making your changes. 15.1199 -<!-- &interaction.mq.tarball.qinit; --> 15.1200 -</para> 15.1201 - 15.1202 -<para>Let's say a few weeks or months pass, and your package author releases 15.1203 -a new version. First, bring their changes into the repository. 15.1204 -<!-- &interaction.mq.tarball.newsource; --> 15.1205 -The pipeline starting with <command role="hg-cmd">hg locate</command> above deletes all files in 15.1206 -the working directory, so that <command role="hg-cmd">hg commit</command>'s 15.1207 -<option role="hg-opt-commit">--addremove</option> option can actually tell which files have 15.1208 -really been removed in the newer version of the source. 15.1209 -</para> 15.1210 - 15.1211 -<para>Finally, you can apply your patches on top of the new tree. 15.1212 -<!-- &interaction.mq.tarball.repush; --> 15.1213 -</para> 15.1214 - 15.1215 -</sect2> 15.1216 -<sect2> 15.1217 -<title>Combining entire patches</title> 15.1218 -<para>\label{sec:mq:combine} 15.1219 -</para> 15.1220 - 15.1221 -<para>MQ provides a command, <command role="hg-ext-mq">qfold</command> that lets you combine entire 15.1222 -patches. This <quote>folds</quote> the patches you name, in the order you name 15.1223 -them, into the topmost applied patch, and concatenates their 15.1224 -descriptions onto the end of its description. The patches that you 15.1225 -fold must be unapplied before you fold them. 15.1226 -</para> 15.1227 - 15.1228 -<para>The order in which you fold patches matters. If your topmost applied 15.1229 -patch is <literal>foo</literal>, and you <command role="hg-ext-mq">qfold</command> <literal>bar</literal> and 15.1230 -<literal>quux</literal> into it, you will end up with a patch that has the same 15.1231 -effect as if you applied first <literal>foo</literal>, then <literal>bar</literal>, 15.1232 -followed by <literal>quux</literal>. 15.1233 -</para> 15.1234 - 15.1235 -</sect2> 15.1236 -<sect2> 15.1237 -<title>Merging part of one patch into another</title> 15.1238 - 15.1239 -<para>Merging <emphasis>part</emphasis> of one patch into another is more difficult than 15.1240 -combining entire patches. 15.1241 -</para> 15.1242 - 15.1243 -<para>If you want to move changes to entire files, you can use 15.1244 -<command>filterdiff</command>'s <option role="cmd-opt-filterdiff">-i</option> and 15.1245 -<option role="cmd-opt-filterdiff">-x</option> options to choose the modifications to snip 15.1246 -out of one patch, concatenating its output onto the end of the patch 15.1247 -you want to merge into. You usually won't need to modify the patch 15.1248 -you've merged the changes from. Instead, MQ will report some rejected 15.1249 -hunks when you <command role="hg-ext-mq">qpush</command> it (from the hunks you moved into the 15.1250 -other patch), and you can simply <command role="hg-ext-mq">qrefresh</command> the patch to drop 15.1251 -the duplicate hunks. 15.1252 -</para> 15.1253 - 15.1254 -<para>If you have a patch that has multiple hunks modifying a file, and you 15.1255 -only want to move a few of those hunks, the job becomes more messy, 15.1256 -but you can still partly automate it. Use <command>lsdiff -nvv</command> to 15.1257 -print some metadata about the patch. 15.1258 -<!-- &interaction.mq.tools.lsdiff; --> 15.1259 -</para> 15.1260 - 15.1261 -<para>This command prints three different kinds of number: 15.1262 -</para> 15.1263 -<itemizedlist> 15.1264 -<listitem><para>(in the first column) a <emphasis>file number</emphasis> to identify each file 15.1265 - modified in the patch; 15.1266 -</para> 15.1267 -</listitem> 15.1268 -<listitem><para>(on the next line, indented) the line number within a modified 15.1269 - file where a hunk starts; and 15.1270 -</para> 15.1271 -</listitem> 15.1272 -<listitem><para>(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk. 15.1273 -</para> 15.1274 -</listitem></itemizedlist> 15.1275 - 15.1276 -<para>You'll have to use some visual inspection, and reading of the patch, 15.1277 -to identify the file and hunk numbers you'll want, but you can then 15.1278 -pass them to to <command>filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option> 15.1279 -and <option role="cmd-opt-filterdiff">--hunks</option> options, to select exactly the file 15.1280 -and hunk you want to extract. 15.1281 -</para> 15.1282 - 15.1283 -<para>Once you have this hunk, you can concatenate it onto the end of your 15.1284 -destination patch and continue with the remainder of 15.1285 -section <xref linkend="sec:mq:combine"/>. 15.1286 -</para> 15.1287 - 15.1288 -</sect2> 15.1289 -</sect1> 15.1290 -<sect1> 15.1291 -<title>Differences between quilt and MQ</title> 15.1292 - 15.1293 -<para>If you are already familiar with quilt, MQ provides a similar command 15.1294 -set. There are a few differences in the way that it works. 15.1295 -</para> 15.1296 - 15.1297 -<para>You will already have noticed that most quilt commands have MQ 15.1298 -counterparts that simply begin with a <quote><literal>q</literal></quote>. The exceptions 15.1299 -are quilt's <literal>add</literal> and <literal>remove</literal> commands, the 15.1300 -counterparts for which are the normal Mercurial <command role="hg-cmd">hg add</command> and 15.1301 -<command role="hg-cmd">hg remove</command> commands. There is no MQ equivalent of the quilt 15.1302 -<literal>edit</literal> command. 15.1303 -</para> 15.1304 - 15.1305 -</sect1> 15.1306 +<chapter id="chap:mq"> 15.1307 + <?dbhtml filename="managing-change-with-mercurial-queues.html"?> 15.1308 + <title>Managing change with Mercurial Queues</title> 15.1309 + 15.1310 + <sect1 id="sec:mq:patch-mgmt"> 15.1311 + <title>The patch management problem</title> 15.1312 + 15.1313 + <para id="x_3ac">Here is a common scenario: you need to install a software 15.1314 + package from source, but you find a bug that you must fix in the 15.1315 + source before you can start using the package. You make your 15.1316 + changes, forget about the package for a while, and a few months 15.1317 + later you need to upgrade to a newer version of the package. If 15.1318 + the newer version of the package still has the bug, you must 15.1319 + extract your fix from the older source tree and apply it against 15.1320 + the newer version. This is a tedious task, and it's easy to 15.1321 + make mistakes.</para> 15.1322 + 15.1323 + <para id="x_3ad">This is a simple case of the <quote>patch management</quote> 15.1324 + problem. You have an <quote>upstream</quote> source tree that 15.1325 + you can't change; you need to make some local changes on top of 15.1326 + the upstream tree; and you'd like to be able to keep those 15.1327 + changes separate, so that you can apply them to newer versions 15.1328 + of the upstream source.</para> 15.1329 + 15.1330 + <para id="x_3ae">The patch management problem arises in many situations. 15.1331 + Probably the most visible is that a user of an open source 15.1332 + software project will contribute a bug fix or new feature to the 15.1333 + project's maintainers in the form of a patch.</para> 15.1334 + 15.1335 + <para id="x_3af">Distributors of operating systems that include open source 15.1336 + software often need to make changes to the packages they 15.1337 + distribute so that they will build properly in their 15.1338 + environments.</para> 15.1339 + 15.1340 + <para id="x_3b0">When you have few changes to maintain, it is easy to manage 15.1341 + a single patch using the standard <command>diff</command> and 15.1342 + <command>patch</command> programs (see <xref 15.1343 + linkend="sec:mq:patch"/> for a discussion of these 15.1344 + tools). Once the number of changes grows, it starts to make 15.1345 + sense to maintain patches as discrete <quote>chunks of 15.1346 + work,</quote> so that for example a single patch will contain 15.1347 + only one bug fix (the patch might modify several files, but it's 15.1348 + doing <quote>only one thing</quote>), and you may have a number 15.1349 + of such patches for different bugs you need fixed and local 15.1350 + changes you require. In this situation, if you submit a bug fix 15.1351 + patch to the upstream maintainers of a package and they include 15.1352 + your fix in a subsequent release, you can simply drop that 15.1353 + single patch when you're updating to the newer release.</para> 15.1354 + 15.1355 + <para id="x_3b1">Maintaining a single patch against an upstream tree is a 15.1356 + little tedious and error-prone, but not difficult. However, the 15.1357 + complexity of the problem grows rapidly as the number of patches 15.1358 + you have to maintain increases. With more than a tiny number of 15.1359 + patches in hand, understanding which ones you have applied and 15.1360 + maintaining them moves from messy to overwhelming.</para> 15.1361 + 15.1362 + <para id="x_3b2">Fortunately, Mercurial includes a powerful extension, 15.1363 + Mercurial Queues (or simply <quote>MQ</quote>), that massively 15.1364 + simplifies the patch management problem.</para> 15.1365 + 15.1366 + </sect1> 15.1367 + <sect1 id="sec:mq:history"> 15.1368 + <title>The prehistory of Mercurial Queues</title> 15.1369 + 15.1370 + <para id="x_3b3">During the late 1990s, several Linux kernel developers 15.1371 + started to maintain <quote>patch series</quote> that modified 15.1372 + the behavior of the Linux kernel. Some of these series were 15.1373 + focused on stability, some on feature coverage, and others were 15.1374 + more speculative.</para> 15.1375 + 15.1376 + <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002, 15.1377 + Andrew Morton published some shell scripts he had been using to 15.1378 + automate the task of managing his patch queues. Andrew was 15.1379 + successfully using these scripts to manage hundreds (sometimes 15.1380 + thousands) of patches on top of the Linux kernel.</para> 15.1381 + 15.1382 + <sect2 id="sec:mq:quilt"> 15.1383 + <title>A patchwork quilt</title> 15.1384 + 15.1385 + <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson 15.1386 + borrowed the approach of Andrew's scripts and published a tool 15.1387 + called <quote>patchwork quilt</quote> 15.1388 + <citation>web:quilt</citation>, or simply <quote>quilt</quote> 15.1389 + (see <citation>gruenbacher:2005</citation> for a paper 15.1390 + describing it). Because quilt substantially automated patch 15.1391 + management, it rapidly gained a large following among open 15.1392 + source software developers.</para> 15.1393 + 15.1394 + <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on 15.1395 + top of a directory tree. To begin, you tell quilt to manage a 15.1396 + directory tree, and tell it which files you want to manage; it 15.1397 + stores away the names and contents of those files. To fix a 15.1398 + bug, you create a new patch (using a single command), edit the 15.1399 + files you need to fix, then <quote>refresh</quote> the 15.1400 + patch.</para> 15.1401 + 15.1402 + <para id="x_3b7">The refresh step causes quilt to scan the directory tree; 15.1403 + it updates the patch with all of the changes you have made. 15.1404 + You can create another patch on top of the first, which will 15.1405 + track the changes required to modify the tree from <quote>tree 15.1406 + with one patch applied</quote> to <quote>tree with two 15.1407 + patches applied</quote>.</para> 15.1408 + 15.1409 + <para id="x_3b8">You can <emphasis>change</emphasis> which patches are 15.1410 + applied to the tree. If you <quote>pop</quote> a patch, the 15.1411 + changes made by that patch will vanish from the directory 15.1412 + tree. Quilt remembers which patches you have popped, though, 15.1413 + so you can <quote>push</quote> a popped patch again, and the 15.1414 + directory tree will be restored to contain the modifications 15.1415 + in the patch. Most importantly, you can run the 15.1416 + <quote>refresh</quote> command at any time, and the topmost 15.1417 + applied patch will be updated. This means that you can, at 15.1418 + any time, change both which patches are applied and what 15.1419 + modifications those patches make.</para> 15.1420 + 15.1421 + <para id="x_3b9">Quilt knows nothing about revision control tools, so it 15.1422 + works equally well on top of an unpacked tarball or a 15.1423 + Subversion working copy.</para> 15.1424 + </sect2> 15.1425 + 15.1426 + <sect2 id="sec:mq:quilt-mq"> 15.1427 + <title>From patchwork quilt to Mercurial Queues</title> 15.1428 + 15.1429 + <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and 15.1430 + wrote an extension that he called Mercurial Queues, which 15.1431 + added quilt-like behavior to Mercurial.</para> 15.1432 + 15.1433 + <para id="x_3bb">The key difference between quilt and MQ is that quilt 15.1434 + knows nothing about revision control systems, while MQ is 15.1435 + <emphasis>integrated</emphasis> into Mercurial. Each patch 15.1436 + that you push is represented as a Mercurial changeset. Pop a 15.1437 + patch, and the changeset goes away.</para> 15.1438 + 15.1439 + <para id="x_3bc">Because quilt does not care about revision control tools, 15.1440 + it is still a tremendously useful piece of software to know 15.1441 + about for situations where you cannot use Mercurial and 15.1442 + MQ.</para> 15.1443 + 15.1444 + </sect2> 15.1445 + </sect1> 15.1446 + <sect1> 15.1447 + <title>The huge advantage of MQ</title> 15.1448 + 15.1449 + <para id="x_3bd">I cannot overstate the value that MQ offers through the 15.1450 + unification of patches and revision control.</para> 15.1451 + 15.1452 + <para id="x_3be">A major reason that patches have persisted in the free 15.1453 + software and open source world&emdash;in spite of the 15.1454 + availability of increasingly capable revision control tools over 15.1455 + the years&emdash;is the <emphasis>agility</emphasis> they 15.1456 + offer.</para> 15.1457 + 15.1458 + <para id="x_3bf">Traditional revision control tools make a permanent, 15.1459 + irreversible record of everything that you do. While this has 15.1460 + great value, it's also somewhat stifling. If you want to 15.1461 + perform a wild-eyed experiment, you have to be careful in how 15.1462 + you go about it, or you risk leaving unneeded&emdash;or worse, 15.1463 + misleading or destabilising&emdash;traces of your missteps and 15.1464 + errors in the permanent revision record.</para> 15.1465 + 15.1466 + <para id="x_3c0">By contrast, MQ's marriage of distributed revision control 15.1467 + with patches makes it much easier to isolate your work. Your 15.1468 + patches live on top of normal revision history, and you can make 15.1469 + them disappear or reappear at will. If you don't like a patch, 15.1470 + you can drop it. If a patch isn't quite as you want it to be, 15.1471 + simply fix it&emdash;as many times as you need to, until you 15.1472 + have refined it into the form you desire.</para> 15.1473 + 15.1474 + <para id="x_3c1">As an example, the integration of patches with revision 15.1475 + control makes understanding patches and debugging their 15.1476 + effects&emdash;and their interplay with the code they're based 15.1477 + on&emdash;<emphasis>enormously</emphasis> easier. Since every 15.1478 + applied patch has an associated changeset, you can give <command 15.1479 + role="hg-cmd">hg log</command> a file name to see which 15.1480 + changesets and patches affected the file. You can use the 15.1481 + <command role="hg-cmd">hg bisect</command> command to 15.1482 + binary-search through all changesets and applied patches to see 15.1483 + where a bug got introduced or fixed. You can use the <command 15.1484 + role="hg-cmd">hg annotate</command> command to see which 15.1485 + changeset or patch modified a particular line of a source file. 15.1486 + And so on.</para> 15.1487 + </sect1> 15.1488 + 15.1489 + <sect1 id="sec:mq:patch"> 15.1490 + <title>Understanding patches</title> 15.1491 + 15.1492 + <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is 15.1493 + helpful to understand what patches are, and a little about the 15.1494 + tools that work with them.</para> 15.1495 + 15.1496 + <para id="x_3c3">The traditional Unix <command>diff</command> command 15.1497 + compares two files, and prints a list of differences between 15.1498 + them. The <command>patch</command> command understands these 15.1499 + differences as <emphasis>modifications</emphasis> to make to a 15.1500 + file. Take a look below for a simple example of these commands 15.1501 + in action.</para> 15.1502 + 15.1503 + &interaction.mq.dodiff.diff; 15.1504 + 15.1505 + <para id="x_3c4">The type of file that <command>diff</command> generates (and 15.1506 + <command>patch</command> takes as input) is called a 15.1507 + <quote>patch</quote> or a <quote>diff</quote>; there is no 15.1508 + difference between a patch and a diff. (We'll use the term 15.1509 + <quote>patch</quote>, since it's more commonly used.)</para> 15.1510 + 15.1511 + <para id="x_3c5">A patch file can start with arbitrary text; the 15.1512 + <command>patch</command> command ignores this text, but MQ uses 15.1513 + it as the commit message when creating changesets. To find the 15.1514 + beginning of the patch content, <command>patch</command> 15.1515 + searches for the first line that starts with the string 15.1516 + <quote><literal>diff -</literal></quote>.</para> 15.1517 + 15.1518 + <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs 15.1519 + (<command>patch</command> can accept several other diff formats, 15.1520 + but MQ doesn't). A unified diff contains two kinds of header. 15.1521 + The <emphasis>file header</emphasis> describes the file being 15.1522 + modified; it contains the name of the file to modify. When 15.1523 + <command>patch</command> sees a new file header, it looks for a 15.1524 + file with that name to start modifying.</para> 15.1525 + 15.1526 + <para id="x_3c7">After the file header comes a series of 15.1527 + <emphasis>hunks</emphasis>. Each hunk starts with a header; 15.1528 + this identifies the range of line numbers within the file that 15.1529 + the hunk should modify. Following the header, a hunk starts and 15.1530 + ends with a few (usually three) lines of text from the 15.1531 + unmodified file; these are called the 15.1532 + <emphasis>context</emphasis> for the hunk. If there's only a 15.1533 + small amount of context between successive hunks, 15.1534 + <command>diff</command> doesn't print a new hunk header; it just 15.1535 + runs the hunks together, with a few lines of context between 15.1536 + modifications.</para> 15.1537 + 15.1538 + <para id="x_3c8">Each line of context begins with a space character. Within 15.1539 + the hunk, a line that begins with 15.1540 + <quote><literal>-</literal></quote> means <quote>remove this 15.1541 + line,</quote> while a line that begins with 15.1542 + <quote><literal>+</literal></quote> means <quote>insert this 15.1543 + line.</quote> For example, a line that is modified is 15.1544 + represented by one deletion and one insertion.</para> 15.1545 + 15.1546 + <para id="x_3c9">We will return to some of the more subtle aspects of patches 15.1547 + later (in <xref linkend="sec:mq:adv-patch"/>), but you 15.1548 + should have 15.1549 + enough information now to use MQ.</para> 15.1550 + </sect1> 15.1551 + 15.1552 + <sect1 id="sec:mq:start"> 15.1553 + <title>Getting started with Mercurial Queues</title> 15.1554 + 15.1555 + <para id="x_3ca">Because MQ is implemented as an extension, you must 15.1556 + explicitly enable before you can use it. (You don't need to 15.1557 + download anything; MQ ships with the standard Mercurial 15.1558 + distribution.) To enable MQ, edit your <filename 15.1559 + role="home">~/.hgrc</filename> file, and add the lines 15.1560 + below.</para> 15.1561 + 15.1562 + <programlisting>[extensions] 15.1563 +hgext.mq =</programlisting> 15.1564 + 15.1565 + <para id="x_3cb">Once the extension is enabled, it will make a number of new 15.1566 + commands available. To verify that the extension is working, 15.1567 + you can use <command role="hg-cmd">hg help</command> to see if 15.1568 + the <command role="hg-ext-mq">qinit</command> command is now 15.1569 + available.</para> 15.1570 + 15.1571 + &interaction.mq.qinit-help.help; 15.1572 + 15.1573 + <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 15.1574 + repository, and its commands only operate within that 15.1575 + repository. To get started, simply prepare the repository using 15.1576 + the <command role="hg-ext-mq">qinit</command> command.</para> 15.1577 + 15.1578 + &interaction.mq.tutorial.qinit; 15.1579 + 15.1580 + <para id="x_3cd">This command creates an empty directory called <filename 15.1581 + role="special" class="directory">.hg/patches</filename>, where 15.1582 + MQ will keep its metadata. As with many Mercurial commands, the 15.1583 + <command role="hg-ext-mq">qinit</command> command prints nothing 15.1584 + if it succeeds.</para> 15.1585 + 15.1586 + <sect2> 15.1587 + <title>Creating a new patch</title> 15.1588 + 15.1589 + <para id="x_3ce">To begin work on a new patch, use the <command 15.1590 + role="hg-ext-mq">qnew</command> command. This command takes 15.1591 + one argument, the name of the patch to create.</para> 15.1592 + 15.1593 + <para id="x_3cf">MQ will use this as the name of an actual file in the 15.1594 + <filename role="special" 15.1595 + class="directory">.hg/patches</filename> directory, as you 15.1596 + can see below.</para> 15.1597 + 15.1598 + &interaction.mq.tutorial.qnew; 15.1599 + 15.1600 + <para id="x_3d0">Also newly present in the <filename role="special" 15.1601 + class="directory">.hg/patches</filename> directory are two 15.1602 + other files, <filename role="special">series</filename> and 15.1603 + <filename role="special">status</filename>. The <filename 15.1604 + role="special">series</filename> file lists all of the 15.1605 + patches that MQ knows about for this repository, with one 15.1606 + patch per line. Mercurial uses the <filename 15.1607 + role="special">status</filename> file for internal 15.1608 + book-keeping; it tracks all of the patches that MQ has 15.1609 + <emphasis>applied</emphasis> in this repository.</para> 15.1610 + 15.1611 + <note> 15.1612 + <para id="x_3d1"> You may sometimes want to edit the <filename 15.1613 + role="special">series</filename> file by hand; for 15.1614 + example, to change the sequence in which some patches are 15.1615 + applied. However, manually editing the <filename 15.1616 + role="special">status</filename> file is almost always a 15.1617 + bad idea, as it's easy to corrupt MQ's idea of what is 15.1618 + happening.</para> 15.1619 + </note> 15.1620 + 15.1621 + <para id="x_3d2">Once you have created your new patch, you can edit files 15.1622 + in the working directory as you usually would. All of the 15.1623 + normal Mercurial commands, such as <command role="hg-cmd">hg 15.1624 + diff</command> and <command role="hg-cmd">hg 15.1625 + annotate</command>, work exactly as they did before.</para> 15.1626 + </sect2> 15.1627 + 15.1628 + <sect2> 15.1629 + <title>Refreshing a patch</title> 15.1630 + 15.1631 + <para id="x_3d3">When you reach a point where you want to save your work, 15.1632 + use the <command role="hg-ext-mq">qrefresh</command> command 15.1633 + to update the patch you are working on.</para> 15.1634 + 15.1635 + &interaction.mq.tutorial.qrefresh; 15.1636 + 15.1637 + <para id="x_3d4">This command folds the changes you have made in the 15.1638 + working directory into your patch, and updates its 15.1639 + corresponding changeset to contain those changes.</para> 15.1640 + 15.1641 + <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command> 15.1642 + as often as you like, so it's a good way to 15.1643 + <quote>checkpoint</quote> your work. Refresh your patch at an 15.1644 + opportune time; try an experiment; and if the experiment 15.1645 + doesn't work out, <command role="hg-cmd">hg revert</command> 15.1646 + your modifications back to the last time you refreshed.</para> 15.1647 + 15.1648 + &interaction.mq.tutorial.qrefresh2; 15.1649 + </sect2> 15.1650 + 15.1651 + <sect2> 15.1652 + <title>Stacking and tracking patches</title> 15.1653 + 15.1654 + <para id="x_3d6">Once you have finished working on a patch, or need to work 15.1655 + on another, you can use the <command 15.1656 + role="hg-ext-mq">qnew</command> command again to create a 15.1657 + new patch. Mercurial will apply this patch on top of your 15.1658 + existing patch.</para> 15.1659 + 15.1660 + &interaction.mq.tutorial.qnew2; 15.1661 + 15.1662 + <para id="x_3d7">Notice that the patch contains the changes in our prior 15.1663 + patch as part of its context (you can see this more clearly in 15.1664 + the output of <command role="hg-cmd">hg 15.1665 + annotate</command>).</para> 15.1666 + 15.1667 + <para id="x_3d8">So far, with the exception of <command 15.1668 + role="hg-ext-mq">qnew</command> and <command 15.1669 + role="hg-ext-mq">qrefresh</command>, we've been careful to 15.1670 + only use regular Mercurial commands. However, MQ provides 15.1671 + many commands that are easier to use when you are thinking 15.1672 + about patches, as illustrated below.</para> 15.1673 + 15.1674 + &interaction.mq.tutorial.qseries; 15.1675 + 15.1676 + <itemizedlist> 15.1677 + <listitem><para id="x_3d9">The <command 15.1678 + role="hg-ext-mq">qseries</command> command lists every 15.1679 + patch that MQ knows about in this repository, from oldest 15.1680 + to newest (most recently 15.1681 + <emphasis>created</emphasis>).</para> 15.1682 + </listitem> 15.1683 + <listitem><para id="x_3da">The <command 15.1684 + role="hg-ext-mq">qapplied</command> command lists every 15.1685 + patch that MQ has <emphasis>applied</emphasis> in this 15.1686 + repository, again from oldest to newest (most recently 15.1687 + applied).</para> 15.1688 + </listitem></itemizedlist> 15.1689 + </sect2> 15.1690 + 15.1691 + <sect2> 15.1692 + <title>Manipulating the patch stack</title> 15.1693 + 15.1694 + <para id="x_3db">The previous discussion implied that there must be a 15.1695 + difference between <quote>known</quote> and 15.1696 + <quote>applied</quote> patches, and there is. MQ can manage a 15.1697 + patch without it being applied in the repository.</para> 15.1698 + 15.1699 + <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding 15.1700 + changeset in the repository, and the effects of the patch and 15.1701 + changeset are visible in the working directory. You can undo 15.1702 + the application of a patch using the <command 15.1703 + role="hg-ext-mq">qpop</command> command. MQ still 15.1704 + <emphasis>knows about</emphasis>, or manages, a popped patch, 15.1705 + but the patch no longer has a corresponding changeset in the 15.1706 + repository, and the working directory does not contain the 15.1707 + changes made by the patch. <xref 15.1708 + linkend="fig:mq:stack"/> illustrates 15.1709 + the difference between applied and tracked patches.</para> 15.1710 + 15.1711 + <figure id="fig:mq:stack"> 15.1712 + <title>Applied and unapplied patches in the MQ patch 15.1713 + stack</title> 15.1714 + <mediaobject> 15.1715 + <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject> 15.1716 + <textobject><phrase>XXX add text</phrase></textobject> 15.1717 + </mediaobject> 15.1718 + </figure> 15.1719 + 15.1720 + <para id="x_3de">You can reapply an unapplied, or popped, patch using the 15.1721 + <command role="hg-ext-mq">qpush</command> command. This 15.1722 + creates a new changeset to correspond to the patch, and the 15.1723 + patch's changes once again become present in the working 15.1724 + directory. See below for examples of <command 15.1725 + role="hg-ext-mq">qpop</command> and <command 15.1726 + role="hg-ext-mq">qpush</command> in action.</para> 15.1727 + 15.1728 + &interaction.mq.tutorial.qpop; 15.1729 + 15.1730 + <para id="x_3df">Notice that once we have popped a patch or two patches, 15.1731 + the output of <command role="hg-ext-mq">qseries</command> 15.1732 + remains the same, while that of <command 15.1733 + role="hg-ext-mq">qapplied</command> has changed.</para> 15.1734 + 15.1735 + </sect2> 15.1736 + 15.1737 + <sect2> 15.1738 + <title>Pushing and popping many patches</title> 15.1739 + 15.1740 + <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and 15.1741 + <command role="hg-ext-mq">qpop</command> each operate on a 15.1742 + single patch at a time by default, you can push and pop many 15.1743 + patches in one go. The <option 15.1744 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to 15.1745 + <command role="hg-ext-mq">qpush</command> causes it to push 15.1746 + all unapplied patches, while the <option 15.1747 + role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command 15.1748 + role="hg-ext-mq">qpop</command> causes it to pop all applied 15.1749 + patches. (For some more ways to push and pop many patches, 15.1750 + see <xref linkend="sec:mq:perf"/> below.)</para> 15.1751 + 15.1752 + &interaction.mq.tutorial.qpush-a; 15.1753 + </sect2> 15.1754 + 15.1755 + <sect2> 15.1756 + <title>Safety checks, and overriding them</title> 15.1757 + 15.1758 + <para id="x_3e1">Several MQ commands check the working directory before 15.1759 + they do anything, and fail if they find any modifications. 15.1760 + They do this to ensure that you won't lose any changes that 15.1761 + you have made, but not yet incorporated into a patch. The 15.1762 + example below illustrates this; the <command 15.1763 + role="hg-ext-mq">qnew</command> command will not create a 15.1764 + new patch if there are outstanding changes, caused in this 15.1765 + case by the <command role="hg-cmd">hg add</command> of 15.1766 + <filename>file3</filename>.</para> 15.1767 + 15.1768 + &interaction.mq.tutorial.add; 15.1769 + 15.1770 + <para id="x_3e2">Commands that check the working directory all take an 15.1771 + <quote>I know what I'm doing</quote> option, which is always 15.1772 + named <option>-f</option>. The exact meaning of 15.1773 + <option>-f</option> depends on the command. For example, 15.1774 + <command role="hg-cmd">hg qnew <option 15.1775 + role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command> 15.1776 + will incorporate any outstanding changes into the new patch it 15.1777 + creates, but <command role="hg-cmd">hg qpop <option 15.1778 + role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command> 15.1779 + will revert modifications to any files affected by the patch 15.1780 + that it is popping. Be sure to read the documentation for a 15.1781 + command's <option>-f</option> option before you use it!</para> 15.1782 + </sect2> 15.1783 + 15.1784 + <sect2> 15.1785 + <title>Working on several patches at once</title> 15.1786 + 15.1787 + <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command 15.1788 + always refreshes the <emphasis>topmost</emphasis> applied 15.1789 + patch. This means that you can suspend work on one patch (by 15.1790 + refreshing it), pop or push to make a different patch the top, 15.1791 + and work on <emphasis>that</emphasis> patch for a 15.1792 + while.</para> 15.1793 + 15.1794 + <para id="x_3e4">Here's an example that illustrates how you can use this 15.1795 + ability. Let's say you're developing a new feature as two 15.1796 + patches. The first is a change to the core of your software, 15.1797 + and the second&emdash;layered on top of the 15.1798 + first&emdash;changes the user interface to use the code you 15.1799 + just added to the core. If you notice a bug in the core while 15.1800 + you're working on the UI patch, it's easy to fix the core. 15.1801 + Simply <command role="hg-ext-mq">qrefresh</command> the UI 15.1802 + patch to save your in-progress changes, and <command 15.1803 + role="hg-ext-mq">qpop</command> down to the core patch. Fix 15.1804 + the core bug, <command role="hg-ext-mq">qrefresh</command> the 15.1805 + core patch, and <command role="hg-ext-mq">qpush</command> back 15.1806 + to the UI patch to continue where you left off.</para> 15.1807 + </sect2> 15.1808 + </sect1> 15.1809 + 15.1810 + <sect1 id="sec:mq:adv-patch"> 15.1811 + <title>More about patches</title> 15.1812 + 15.1813 + <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply 15.1814 + patches, so it's helpful to know a few more detailed aspects of 15.1815 + how <command>patch</command> works, and about patches 15.1816 + themselves.</para> 15.1817 + 15.1818 + <sect2> 15.1819 + <title>The strip count</title> 15.1820 + 15.1821 + <para id="x_3e6">If you look at the file headers in a patch, you will 15.1822 + notice that the pathnames usually have an extra component on 15.1823 + the front that isn't present in the actual path name. This is 15.1824 + a holdover from the way that people used to generate patches 15.1825 + (people still do this, but it's somewhat rare with modern 15.1826 + revision control tools).</para> 15.1827 + 15.1828 + <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide 15.1829 + that she wanted to create a patch. So she'd rename her 15.1830 + working directory, unpack the tarball again (hence the need 15.1831 + for the rename), and use the <option 15.1832 + role="cmd-opt-diff">-r</option> and <option 15.1833 + role="cmd-opt-diff">-N</option> options to 15.1834 + <command>diff</command> to recursively generate a patch 15.1835 + between the unmodified directory and the modified one. The 15.1836 + result would be that the name of the unmodified directory 15.1837 + would be at the front of the left-hand path in every file 15.1838 + header, and the name of the modified directory would be at the 15.1839 + front of the right-hand path.</para> 15.1840 + 15.1841 + <para id="x_3e8">Since someone receiving a patch from the Alices of the net 15.1842 + would be unlikely to have unmodified and modified directories 15.1843 + with exactly the same names, the <command>patch</command> 15.1844 + command has a <option role="cmd-opt-patch">-p</option> option 15.1845 + that indicates the number of leading path name components to 15.1846 + strip when trying to apply a patch. This number is called the 15.1847 + <emphasis>strip count</emphasis>.</para> 15.1848 + 15.1849 + <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means 15.1850 + <quote>use a strip count of one</quote>. If 15.1851 + <command>patch</command> sees a file name 15.1852 + <filename>foo/bar/baz</filename> in a file header, it will 15.1853 + strip <filename>foo</filename> and try to patch a file named 15.1854 + <filename>bar/baz</filename>. (Strictly speaking, the strip 15.1855 + count refers to the number of <emphasis>path 15.1856 + separators</emphasis> (and the components that go with them 15.1857 + ) to strip. A strip count of one will turn 15.1858 + <filename>foo/bar</filename> into <filename>bar</filename>, 15.1859 + but <filename>/foo/bar</filename> (notice the extra leading 15.1860 + slash) into <filename>foo/bar</filename>.)</para> 15.1861 + 15.1862 + <para id="x_3ea">The <quote>standard</quote> strip count for patches is 15.1863 + one; almost all patches contain one leading path name 15.1864 + component that needs to be stripped. Mercurial's <command 15.1865 + role="hg-cmd">hg diff</command> command generates path names 15.1866 + in this form, and the <command role="hg-cmd">hg 15.1867 + import</command> command and MQ expect patches to have a 15.1868 + strip count of one.</para> 15.1869 + 15.1870 + <para id="x_3eb">If you receive a patch from someone that you want to add 15.1871 + to your patch queue, and the patch needs a strip count other 15.1872 + than one, you cannot just <command 15.1873 + role="hg-ext-mq">qimport</command> the patch, because 15.1874 + <command role="hg-ext-mq">qimport</command> does not yet have 15.1875 + a <literal>-p</literal> option (see <ulink role="hg-bug" 15.1876 + url="http://www.selenic.com/mercurial/bts/issue311">issue 15.1877 + 311</ulink>). Your best bet is to <command 15.1878 + role="hg-ext-mq">qnew</command> a patch of your own, then 15.1879 + use <command>patch -pN</command> to apply their patch, 15.1880 + followed by <command role="hg-cmd">hg addremove</command> to 15.1881 + pick up any files added or removed by the patch, followed by 15.1882 + <command role="hg-ext-mq">hg qrefresh</command>. This 15.1883 + complexity may become unnecessary; see <ulink role="hg-bug" 15.1884 + url="http://www.selenic.com/mercurial/bts/issue311">issue 15.1885 + 311</ulink> for details. 15.1886 + </para> 15.1887 + </sect2> 15.1888 + 15.1889 + <sect2> 15.1890 + <title>Strategies for applying a patch</title> 15.1891 + 15.1892 + <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a 15.1893 + handful of successively less accurate strategies to try to 15.1894 + make the hunk apply. This falling-back technique often makes 15.1895 + it possible to take a patch that was generated against an old 15.1896 + version of a file, and apply it against a newer version of 15.1897 + that file.</para> 15.1898 + 15.1899 + <para id="x_3ed">First, <command>patch</command> tries an exact match, 15.1900 + where the line numbers, the context, and the text to be 15.1901 + modified must apply exactly. If it cannot make an exact 15.1902 + match, it tries to find an exact match for the context, 15.1903 + without honouring the line numbering information. If this 15.1904 + succeeds, it prints a line of output saying that the hunk was 15.1905 + applied, but at some <emphasis>offset</emphasis> from the 15.1906 + original line number.</para> 15.1907 + 15.1908 + <para id="x_3ee">If a context-only match fails, <command>patch</command> 15.1909 + removes the first and last lines of the context, and tries a 15.1910 + <emphasis>reduced</emphasis> context-only match. If the hunk 15.1911 + with reduced context succeeds, it prints a message saying that 15.1912 + it applied the hunk with a <emphasis>fuzz factor</emphasis> 15.1913 + (the number after the fuzz factor indicates how many lines of 15.1914 + context <command>patch</command> had to trim before the patch 15.1915 + applied).</para> 15.1916 + 15.1917 + <para id="x_3ef">When neither of these techniques works, 15.1918 + <command>patch</command> prints a message saying that the hunk 15.1919 + in question was rejected. It saves rejected hunks (also 15.1920 + simply called <quote>rejects</quote>) to a file with the same 15.1921 + name, and an added <filename role="special">.rej</filename> 15.1922 + extension. It also saves an unmodified copy of the file with 15.1923 + a <filename role="special">.orig</filename> extension; the 15.1924 + copy of the file without any extensions will contain any 15.1925 + changes made by hunks that <emphasis>did</emphasis> apply 15.1926 + cleanly. If you have a patch that modifies 15.1927 + <filename>foo</filename> with six hunks, and one of them fails 15.1928 + to apply, you will have: an unmodified 15.1929 + <filename>foo.orig</filename>, a <filename>foo.rej</filename> 15.1930 + containing one hunk, and <filename>foo</filename>, containing 15.1931 + the changes made by the five successful hunks.</para> 15.1932 + </sect2> 15.1933 + 15.1934 + <sect2> 15.1935 + <title>Some quirks of patch representation</title> 15.1936 + 15.1937 + <para id="x_3f0">There are a few useful things to know about how 15.1938 + <command>patch</command> works with files.</para> 15.1939 + <itemizedlist> 15.1940 + <listitem><para id="x_3f1">This should already be obvious, but 15.1941 + <command>patch</command> cannot handle binary 15.1942 + files.</para> 15.1943 + </listitem> 15.1944 + <listitem><para id="x_3f2">Neither does it care about the executable bit; 15.1945 + it creates new files as readable, but not 15.1946 + executable.</para> 15.1947 + </listitem> 15.1948 + <listitem><para id="x_3f3"><command>patch</command> treats the removal of 15.1949 + a file as a diff between the file to be removed and the 15.1950 + empty file. So your idea of <quote>I deleted this 15.1951 + file</quote> looks like <quote>every line of this file 15.1952 + was deleted</quote> in a patch.</para> 15.1953 + </listitem> 15.1954 + <listitem><para id="x_3f4">It treats the addition of a file as a diff 15.1955 + between the empty file and the file to be added. So in a 15.1956 + patch, your idea of <quote>I added this file</quote> looks 15.1957 + like <quote>every line of this file was 15.1958 + added</quote>.</para> 15.1959 + </listitem> 15.1960 + <listitem><para id="x_3f5">It treats a renamed file as the removal of the 15.1961 + old name, and the addition of the new name. This means 15.1962 + that renamed files have a big footprint in patches. (Note 15.1963 + also that Mercurial does not currently try to infer when 15.1964 + files have been renamed or copied in a patch.)</para> 15.1965 + </listitem> 15.1966 + <listitem><para id="x_3f6"><command>patch</command> cannot represent 15.1967 + empty files, so you cannot use a patch to represent the 15.1968 + notion <quote>I added this empty file to the 15.1969 + tree</quote>.</para> 15.1970 + </listitem></itemizedlist> 15.1971 + </sect2> 15.1972 + 15.1973 + <sect2> 15.1974 + <title>Beware the fuzz</title> 15.1975 + 15.1976 + <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor, 15.1977 + will often be completely successful, these inexact techniques 15.1978 + naturally leave open the possibility of corrupting the patched 15.1979 + file. The most common cases typically involve applying a 15.1980 + patch twice, or at an incorrect location in the file. If 15.1981 + <command>patch</command> or <command 15.1982 + role="hg-ext-mq">qpush</command> ever mentions an offset or 15.1983 + fuzz factor, you should make sure that the modified files are 15.1984 + correct afterwards.</para> 15.1985 + 15.1986 + <para id="x_3f8">It's often a good idea to refresh a patch that has applied 15.1987 + with an offset or fuzz factor; refreshing the patch generates 15.1988 + new context information that will make it apply cleanly. I 15.1989 + say <quote>often,</quote> not <quote>always,</quote> because 15.1990 + sometimes refreshing a patch will make it fail to apply 15.1991 + against a different revision of the underlying files. In some 15.1992 + cases, such as when you're maintaining a patch that must sit 15.1993 + on top of multiple versions of a source tree, it's acceptable 15.1994 + to have a patch apply with some fuzz, provided you've verified 15.1995 + the results of the patching process in such cases.</para> 15.1996 + </sect2> 15.1997 + 15.1998 + <sect2> 15.1999 + <title>Handling rejection</title> 15.2000 + 15.2001 + <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to 15.2002 + apply a patch, it will print an error message and exit. If it 15.2003 + has left <filename role="special">.rej</filename> files 15.2004 + behind, it is usually best to fix up the rejected hunks before 15.2005 + you push more patches or do any further work.</para> 15.2006 + 15.2007 + <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly, 15.2008 + and no longer does because you've changed the underlying code 15.2009 + that your patches are based on, Mercurial Queues can help; see 15.2010 + <xref linkend="sec:mq:merge"/> for details.</para> 15.2011 + 15.2012 + <para id="x_3fb">Unfortunately, there aren't any great techniques for 15.2013 + dealing with rejected hunks. Most often, you'll need to view 15.2014 + the <filename role="special">.rej</filename> file and edit the 15.2015 + target file, applying the rejected hunks by hand.</para> 15.2016 + 15.2017 + <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author 15.2018 + of Mercurial Queues), wrote a tool called 15.2019 + <command>mpatch</command> (<ulink 15.2020 + url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 15.2021 + which takes a simple approach to automating the application of 15.2022 + hunks rejected by <command>patch</command>. The 15.2023 + <command>mpatch</command> command can help with four common 15.2024 + reasons that a hunk may be rejected:</para> 15.2025 + 15.2026 + <itemizedlist> 15.2027 + <listitem><para id="x_3fe">The context in the middle of a hunk has 15.2028 + changed.</para> 15.2029 + </listitem> 15.2030 + <listitem><para id="x_3ff">A hunk is missing some context at the 15.2031 + beginning or end.</para> 15.2032 + </listitem> 15.2033 + <listitem><para id="x_400">A large hunk might apply better&emdash;either 15.2034 + entirely or in part&emdash;if it was broken up into 15.2035 + smaller hunks.</para> 15.2036 + </listitem> 15.2037 + <listitem><para id="x_401">A hunk removes lines with slightly different 15.2038 + content than those currently present in the file.</para> 15.2039 + </listitem></itemizedlist> 15.2040 + 15.2041 + <para id="x_402">If you use <command>mpatch</command>, you 15.2042 + should be doubly careful to check your results when you're 15.2043 + done. In fact, <command>mpatch</command> enforces this method 15.2044 + of double-checking the tool's output, by automatically 15.2045 + dropping you into a merge program when it has done its job, so 15.2046 + that you can verify its work and finish off any remaining 15.2047 + merges.</para> 15.2048 + </sect2> 15.2049 + </sect1> 15.2050 + 15.2051 + <sect1> 15.2052 + <title>More on patch management</title> 15.2053 + 15.2054 + <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting 15.2055 + to perform other kinds of patch management operations.</para> 15.2056 + 15.2057 + <sect2> 15.2058 + <title>Deleting unwanted patches</title> 15.2059 + 15.2060 + <para id="x_6dc">If you want to get rid of a patch, use the <command 15.2061 + role="hg-ext-mq">hg qdelete</command> command to delete the 15.2062 + patch file and remove its entry from the patch series. If you 15.2063 + try to delete a patch that is still applied, <command 15.2064 + role="hg-ext-mq">hg qdelete</command> will refuse.</para> 15.2065 + 15.2066 + &interaction.ch11-qdelete.go; 15.2067 + </sect2> 15.2068 + 15.2069 + <sect2> 15.2070 + <title>Converting to and from permanent revisions</title> 15.2071 + 15.2072 + <para id="x_6dd">Once you're done working on a patch and want to 15.2073 + turn it into a permanent changeset, use the <command 15.2074 + role="hg-ext-mq">hg qfinish</command> command. Pass a revision 15.2075 + to the command to identify the patch that you want to turn into 15.2076 + a regular changeset; this patch must already be applied.</para> 15.2077 + 15.2078 + &interaction.ch11-qdelete.convert; 15.2079 + 15.2080 + <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command 15.2081 + accepts an <option>--all</option> or <option>-a</option> 15.2082 + option, which turns all applied patches into regular 15.2083 + changesets.</para> 15.2084 + 15.2085 + <para id="x_6de">It is also possible to turn an existing changeset into a 15.2086 + patch, by passing the <option>-r</option> option to <command 15.2087 + role="hg-ext-mq">hg qimport</command>.</para> 15.2088 + 15.2089 + &interaction.ch11-qdelete.import; 15.2090 + 15.2091 + <para id="x_6df">Note that it only makes sense to convert a changeset into 15.2092 + a patch if you have not propagated that changeset into any 15.2093 + other repositories. The imported changeset's ID will change 15.2094 + every time you refresh the patch, which will make Mercurial 15.2095 + treat it as unrelated to the original changeset if you have 15.2096 + pushed it somewhere else.</para> 15.2097 + </sect2> 15.2098 + </sect1> 15.2099 + 15.2100 + <sect1 id="sec:mq:perf"> 15.2101 + <title>Getting the best performance out of MQ</title> 15.2102 + 15.2103 + <para id="x_403">MQ is very efficient at handling a large number 15.2104 + of patches. I ran some performance experiments in mid-2006 for a 15.2105 + talk that I gave at the 2006 EuroPython conference (on modern 15.2106 + hardware, you should expect better performance than you'll see 15.2107 + below). I used as my data set the Linux 2.6.17-mm1 patch 15.2108 + series, which consists of 1,738 patches. I applied these on top 15.2109 + of a Linux kernel repository containing all 27,472 revisions 15.2110 + between Linux 2.6.12-rc2 and Linux 2.6.17.</para> 15.2111 + 15.2112 + <para id="x_404">On my old, slow laptop, I was able to <command 15.2113 + role="hg-cmd">hg qpush <option 15.2114 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all 15.2115 + 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 15.2116 + <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> 15.2117 + them all in 30 seconds. (On a newer laptop, the time to push 15.2118 + all patches dropped to two minutes.) I could <command 15.2119 + role="hg-ext-mq">qrefresh</command> one of the biggest patches 15.2120 + (which made 22,779 lines of changes to 287 files) in 6.6 15.2121 + seconds.</para> 15.2122 + 15.2123 + <para id="x_405">Clearly, MQ is well suited to working in large trees, but 15.2124 + there are a few tricks you can use to get the best performance 15.2125 + of it.</para> 15.2126 + 15.2127 + <para id="x_406">First of all, try to <quote>batch</quote> operations 15.2128 + together. Every time you run <command 15.2129 + role="hg-ext-mq">qpush</command> or <command 15.2130 + role="hg-ext-mq">qpop</command>, these commands scan the 15.2131 + working directory once to make sure you haven't made some 15.2132 + changes and then forgotten to run <command 15.2133 + role="hg-ext-mq">qrefresh</command>. On a small tree, the 15.2134 + time that this scan takes is unnoticeable. However, on a 15.2135 + medium-sized tree (containing tens of thousands of files), it 15.2136 + can take a second or more.</para> 15.2137 + 15.2138 + <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command 15.2139 + role="hg-ext-mq">qpop</command> commands allow you to push and 15.2140 + pop multiple patches at a time. You can identify the 15.2141 + <quote>destination patch</quote> that you want to end up at. 15.2142 + When you <command role="hg-ext-mq">qpush</command> with a 15.2143 + destination specified, it will push patches until that patch is 15.2144 + at the top of the applied stack. When you <command 15.2145 + role="hg-ext-mq">qpop</command> to a destination, MQ will pop 15.2146 + patches until the destination patch is at the top.</para> 15.2147 + 15.2148 + <para id="x_408">You can identify a destination patch using either the name 15.2149 + of the patch, or by number. If you use numeric addressing, 15.2150 + patches are counted from zero; this means that the first patch 15.2151 + is zero, the second is one, and so on.</para> 15.2152 + </sect1> 15.2153 + 15.2154 + <sect1 id="sec:mq:merge"> 15.2155 + <title>Updating your patches when the underlying code 15.2156 + changes</title> 15.2157 + 15.2158 + <para id="x_409">It's common to have a stack of patches on top of an 15.2159 + underlying repository that you don't modify directly. If you're 15.2160 + working on changes to third-party code, or on a feature that is 15.2161 + taking longer to develop than the rate of change of the code 15.2162 + beneath, you will often need to sync up with the underlying 15.2163 + code, and fix up any hunks in your patches that no longer apply. 15.2164 + This is called <emphasis>rebasing</emphasis> your patch 15.2165 + series.</para> 15.2166 + 15.2167 + <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg 15.2168 + qpop <option role="hg-ext-mq-cmd-qpop-opt">hg 15.2169 + -a</option></command> your patches, then <command 15.2170 + role="hg-cmd">hg pull</command> changes into the underlying 15.2171 + repository, and finally <command role="hg-cmd">hg qpush <option 15.2172 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your 15.2173 + patches again. MQ will stop pushing any time it runs across a 15.2174 + patch that fails to apply during conflicts, allowing you to fix 15.2175 + your conflicts, <command role="hg-ext-mq">qrefresh</command> the 15.2176 + affected patch, and continue pushing until you have fixed your 15.2177 + entire stack.</para> 15.2178 + 15.2179 + <para id="x_40b">This approach is easy to use and works well if you don't 15.2180 + expect changes to the underlying code to affect how well your 15.2181 + patches apply. If your patch stack touches code that is modified 15.2182 + frequently or invasively in the underlying repository, however, 15.2183 + fixing up rejected hunks by hand quickly becomes 15.2184 + tiresome.</para> 15.2185 + 15.2186 + <para id="x_40c">It's possible to partially automate the rebasing process. 15.2187 + If your patches apply cleanly against some revision of the 15.2188 + underlying repo, MQ can use this information to help you to 15.2189 + resolve conflicts between your patches and a different 15.2190 + revision.</para> 15.2191 + 15.2192 + <para id="x_40d">The process is a little involved.</para> 15.2193 + <orderedlist> 15.2194 + <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush 15.2195 + -a</command> all of your patches on top of the revision 15.2196 + where you know that they apply cleanly.</para> 15.2197 + </listitem> 15.2198 + <listitem><para id="x_40f">Save a backup copy of your patch directory using 15.2199 + <command role="hg-cmd">hg qsave <option 15.2200 + role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option 15.2201 + role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>. 15.2202 + This prints the name of the directory that it has saved the 15.2203 + patches in. It will save the patches to a directory called 15.2204 + <filename role="special" 15.2205 + class="directory">.hg/patches.N</filename>, where 15.2206 + <literal>N</literal> is a small integer. It also commits a 15.2207 + <quote>save changeset</quote> on top of your applied 15.2208 + patches; this is for internal book-keeping, and records the 15.2209 + states of the <filename role="special">series</filename> and 15.2210 + <filename role="special">status</filename> files.</para> 15.2211 + </listitem> 15.2212 + <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to 15.2213 + bring new changes into the underlying repository. (Don't 15.2214 + run <command role="hg-cmd">hg pull -u</command>; see below 15.2215 + for why.)</para> 15.2216 + </listitem> 15.2217 + <listitem><para id="x_411">Update to the new tip revision, using <command 15.2218 + role="hg-cmd">hg update <option 15.2219 + role="hg-opt-update">-C</option></command> to override 15.2220 + the patches you have pushed.</para> 15.2221 + </listitem> 15.2222 + <listitem><para id="x_412">Merge all patches using <command>hg qpush -m 15.2223 + -a</command>. The <option 15.2224 + role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 15.2225 + <command role="hg-ext-mq">qpush</command> tells MQ to 15.2226 + perform a three-way merge if the patch fails to 15.2227 + apply.</para> 15.2228 + </listitem></orderedlist> 15.2229 + 15.2230 + <para id="x_413">During the <command role="hg-cmd">hg qpush <option 15.2231 + role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>, 15.2232 + each patch in the <filename role="special">series</filename> 15.2233 + file is applied normally. If a patch applies with fuzz or 15.2234 + rejects, MQ looks at the queue you <command 15.2235 + role="hg-ext-mq">qsave</command>d, and performs a three-way 15.2236 + merge with the corresponding changeset. This merge uses 15.2237 + Mercurial's normal merge machinery, so it may pop up a GUI merge 15.2238 + tool to help you to resolve problems.</para> 15.2239 + 15.2240 + <para id="x_414">When you finish resolving the effects of a patch, MQ 15.2241 + refreshes your patch based on the result of the merge.</para> 15.2242 + 15.2243 + <para id="x_415">At the end of this process, your repository will have one 15.2244 + extra head from the old patch queue, and a copy of the old patch 15.2245 + queue will be in <filename role="special" 15.2246 + class="directory">.hg/patches.N</filename>. You can remove the 15.2247 + extra head using <command role="hg-cmd">hg qpop -a -n 15.2248 + patches.N</command> or <command role="hg-cmd">hg 15.2249 + strip</command>. You can delete <filename role="special" 15.2250 + class="directory">.hg/patches.N</filename> once you are sure 15.2251 + that you no longer need it as a backup.</para> 15.2252 + </sect1> 15.2253 + 15.2254 + <sect1> 15.2255 + <title>Identifying patches</title> 15.2256 + 15.2257 + <para id="x_416">MQ commands that work with patches let you refer to a patch 15.2258 + either by using its name or by a number. By name is obvious 15.2259 + enough; pass the name <filename>foo.patch</filename> to <command 15.2260 + role="hg-ext-mq">qpush</command>, for example, and it will 15.2261 + push patches until <filename>foo.patch</filename> is 15.2262 + applied.</para> 15.2263 + 15.2264 + <para id="x_417">As a shortcut, you can refer to a patch using both a name 15.2265 + and a numeric offset; <literal>foo.patch-2</literal> means 15.2266 + <quote>two patches before <literal>foo.patch</literal></quote>, 15.2267 + while <literal>bar.patch+4</literal> means <quote>four patches 15.2268 + after <literal>bar.patch</literal></quote>.</para> 15.2269 + 15.2270 + <para id="x_418">Referring to a patch by index isn't much different. The 15.2271 + first patch printed in the output of <command 15.2272 + role="hg-ext-mq">qseries</command> is patch zero (yes, it's 15.2273 + one of those start-at-zero counting systems); the second is 15.2274 + patch one; and so on.</para> 15.2275 + 15.2276 + <para id="x_419">MQ also makes it easy to work with patches when you are 15.2277 + using normal Mercurial commands. Every command that accepts a 15.2278 + changeset ID will also accept the name of an applied patch. MQ 15.2279 + augments the tags normally in the repository with an eponymous 15.2280 + one for each applied patch. In addition, the special tags 15.2281 + <literal role="tag">qbase</literal> and 15.2282 + <literal role="tag">qtip</literal> identify 15.2283 + the <quote>bottom-most</quote> and topmost applied patches, 15.2284 + respectively.</para> 15.2285 + 15.2286 + <para id="x_41a">These additions to Mercurial's normal tagging capabilities 15.2287 + make dealing with patches even more of a breeze.</para> 15.2288 + <itemizedlist> 15.2289 + <listitem><para id="x_41b">Want to patchbomb a mailing list with your 15.2290 + latest series of changes?</para> 15.2291 + <programlisting>hg email qbase:qtip</programlisting> 15.2292 + <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See 15.2293 + <xref linkend="sec:hgext:patchbomb"/>.)</para> 15.2294 + </listitem> 15.2295 + <listitem><para id="x_41d">Need to see all of the patches since 15.2296 + <literal>foo.patch</literal> that have touched files in a 15.2297 + subdirectory of your tree?</para> 15.2298 + <programlisting>hg log -r foo.patch:qtip subdir</programlisting> 15.2299 + </listitem> 15.2300 + </itemizedlist> 15.2301 + 15.2302 + <para id="x_41e">Because MQ makes the names of patches available to the rest 15.2303 + of Mercurial through its normal internal tag machinery, you 15.2304 + don't need to type in the entire name of a patch when you want 15.2305 + to identify it by name.</para> 15.2306 + 15.2307 + <para id="x_41f">Another nice consequence of representing patch names as tags 15.2308 + is that when you run the <command role="hg-cmd">hg log</command> 15.2309 + command, it will display a patch's name as a tag, simply as part 15.2310 + of its normal output. This makes it easy to visually 15.2311 + distinguish applied patches from underlying 15.2312 + <quote>normal</quote> revisions. The following example shows a 15.2313 + few normal Mercurial commands in use with applied 15.2314 + patches.</para> 15.2315 + 15.2316 + &interaction.mq.id.output; 15.2317 + </sect1> 15.2318 + 15.2319 + <sect1> 15.2320 + <title>Useful things to know about</title> 15.2321 + 15.2322 + <para id="x_420">There are a number of aspects of MQ usage that don't fit 15.2323 + tidily into sections of their own, but that are good to know. 15.2324 + Here they are, in one place.</para> 15.2325 + 15.2326 + <itemizedlist> 15.2327 + <listitem><para id="x_421">Normally, when you <command 15.2328 + role="hg-ext-mq">qpop</command> a patch and <command 15.2329 + role="hg-ext-mq">qpush</command> it again, the changeset 15.2330 + that represents the patch after the pop/push will have a 15.2331 + <emphasis>different identity</emphasis> than the changeset 15.2332 + that represented the hash beforehand. See <xref 15.2333 + linkend="sec:mqref:cmd:qpush"/> for 15.2334 + information as to why this is.</para> 15.2335 + </listitem> 15.2336 + <listitem><para id="x_422">It's not a good idea to <command 15.2337 + role="hg-cmd">hg merge</command> changes from another 15.2338 + branch with a patch changeset, at least if you want to 15.2339 + maintain the <quote>patchiness</quote> of that changeset and 15.2340 + changesets below it on the patch stack. If you try to do 15.2341 + this, it will appear to succeed, but MQ will become 15.2342 + confused.</para> 15.2343 + </listitem></itemizedlist> 15.2344 + </sect1> 15.2345 + 15.2346 + <sect1 id="sec:mq:repo"> 15.2347 + <title>Managing patches in a repository</title> 15.2348 + 15.2349 + <para id="x_423">Because MQ's <filename role="special" 15.2350 + class="directory">.hg/patches</filename> directory resides 15.2351 + outside a Mercurial repository's working directory, the 15.2352 + <quote>underlying</quote> Mercurial repository knows nothing 15.2353 + about the management or presence of patches.</para> 15.2354 + 15.2355 + <para id="x_424">This presents the interesting possibility of managing the 15.2356 + contents of the patch directory as a Mercurial repository in its 15.2357 + own right. This can be a useful way to work. For example, you 15.2358 + can work on a patch for a while, <command 15.2359 + role="hg-ext-mq">qrefresh</command> it, then <command 15.2360 + role="hg-cmd">hg commit</command> the current state of the 15.2361 + patch. This lets you <quote>roll back</quote> to that version 15.2362 + of the patch later on.</para> 15.2363 + 15.2364 + <para id="x_425">You can then share different versions of the same patch 15.2365 + stack among multiple underlying repositories. I use this when I 15.2366 + am developing a Linux kernel feature. I have a pristine copy of 15.2367 + my kernel sources for each of several CPU architectures, and a 15.2368 + cloned repository under each that contains the patches I am 15.2369 + working on. When I want to test a change on a different 15.2370 + architecture, I push my current patches to the patch repository 15.2371 + associated with that kernel tree, pop and push all of my 15.2372 + patches, and build and test that kernel.</para> 15.2373 + 15.2374 + <para id="x_426">Managing patches in a repository makes it possible for 15.2375 + multiple developers to work on the same patch series without 15.2376 + colliding with each other, all on top of an underlying source 15.2377 + base that they may or may not control.</para> 15.2378 + 15.2379 + <sect2> 15.2380 + <title>MQ support for patch repositories</title> 15.2381 + 15.2382 + <para id="x_427">MQ helps you to work with the <filename role="special" 15.2383 + class="directory">.hg/patches</filename> directory as a 15.2384 + repository; when you prepare a repository for working with 15.2385 + patches using <command role="hg-ext-mq">qinit</command>, you 15.2386 + can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg 15.2387 + -c</option> option to create the <filename role="special" 15.2388 + class="directory">.hg/patches</filename> directory as a 15.2389 + Mercurial repository.</para> 15.2390 + 15.2391 + <note> 15.2392 + <para id="x_428"> If you forget to use the <option 15.2393 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you 15.2394 + can simply go into the <filename role="special" 15.2395 + class="directory">.hg/patches</filename> directory at any 15.2396 + time and run <command role="hg-cmd">hg init</command>. 15.2397 + Don't forget to add an entry for the <filename 15.2398 + role="special">status</filename> file to the <filename 15.2399 + role="special">.hgignore</filename> file, though</para> 15.2400 + 15.2401 + <para id="x_429"> (<command role="hg-cmd">hg qinit <option 15.2402 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command> 15.2403 + does this for you automatically); you 15.2404 + <emphasis>really</emphasis> don't want to manage the 15.2405 + <filename role="special">status</filename> file.</para> 15.2406 + </note> 15.2407 + 15.2408 + <para id="x_42a">As a convenience, if MQ notices that the <filename 15.2409 + class="directory">.hg/patches</filename> directory is a 15.2410 + repository, it will automatically <command role="hg-cmd">hg 15.2411 + add</command> every patch that you create and import.</para> 15.2412 + 15.2413 + <para id="x_42b">MQ provides a shortcut command, <command 15.2414 + role="hg-ext-mq">qcommit</command>, that runs <command 15.2415 + role="hg-cmd">hg commit</command> in the <filename 15.2416 + role="special" class="directory">.hg/patches</filename> 15.2417 + directory. This saves some bothersome typing.</para> 15.2418 + 15.2419 + <para id="x_42c">Finally, as a convenience to manage the patch directory, 15.2420 + you can define the alias <command>mq</command> on Unix 15.2421 + systems. For example, on Linux systems using the 15.2422 + <command>bash</command> shell, you can include the following 15.2423 + snippet in your <filename 15.2424 + role="home">~/.bashrc</filename>.</para> 15.2425 + 15.2426 + <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting> 15.2427 + 15.2428 + <para id="x_42d">You can then issue commands of the form <command>mq 15.2429 + pull</command> from the main repository.</para> 15.2430 + </sect2> 15.2431 + 15.2432 + <sect2> 15.2433 + <title>A few things to watch out for</title> 15.2434 + 15.2435 + <para id="x_42e">MQ's support for working with a repository full of patches 15.2436 + is limited in a few small respects.</para> 15.2437 + 15.2438 + <para id="x_42f">MQ cannot automatically detect changes that you make to 15.2439 + the patch directory. If you <command role="hg-cmd">hg 15.2440 + pull</command>, manually edit, or <command role="hg-cmd">hg 15.2441 + update</command> changes to patches or the <filename 15.2442 + role="special">series</filename> file, you will have to 15.2443 + <command role="hg-cmd">hg qpop <option 15.2444 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and 15.2445 + then <command role="hg-cmd">hg qpush <option 15.2446 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in 15.2447 + the underlying repository to see those changes show up there. 15.2448 + If you forget to do this, you can confuse MQ's idea of which 15.2449 + patches are applied.</para> 15.2450 + 15.2451 + </sect2> 15.2452 + </sect1> 15.2453 + <sect1 id="sec:mq:tools"> 15.2454 + <title>Third party tools for working with patches</title> 15.2455 + 15.2456 + <para id="x_430">Once you've been working with patches for a while, you'll 15.2457 + find yourself hungry for tools that will help you to understand 15.2458 + and manipulate the patches you're dealing with.</para> 15.2459 + 15.2460 + <para id="x_431">The <command>diffstat</command> command 15.2461 + <citation>web:diffstat</citation> generates a histogram of the 15.2462 + modifications made to each file in a patch. It provides a good 15.2463 + way to <quote>get a sense of</quote> a patch&emdash;which files 15.2464 + it affects, and how much change it introduces to each file and 15.2465 + as a whole. (I find that it's a good idea to use 15.2466 + <command>diffstat</command>'s <option 15.2467 + role="cmd-opt-diffstat">-p</option> option as a matter of 15.2468 + course, as otherwise it will try to do clever things with 15.2469 + prefixes of file names that inevitably confuse at least 15.2470 + me.)</para> 15.2471 + 15.2472 +&interaction.mq.tools.tools; 15.2473 + 15.2474 + <para id="x_432">The <literal role="package">patchutils</literal> package 15.2475 + <citation>web:patchutils</citation> is invaluable. It provides a 15.2476 + set of small utilities that follow the <quote>Unix 15.2477 + philosophy;</quote> each does one useful thing with a patch. 15.2478 + The <literal role="package">patchutils</literal> command I use 15.2479 + most is <command>filterdiff</command>, which extracts subsets 15.2480 + from a patch file. For example, given a patch that modifies 15.2481 + hundreds of files across dozens of directories, a single 15.2482 + invocation of <command>filterdiff</command> can generate a 15.2483 + smaller patch that only touches files whose names match a 15.2484 + particular glob pattern. See <xref 15.2485 + linkend="mq-collab:tips:interdiff"/> for another 15.2486 + example.</para> 15.2487 + 15.2488 + </sect1> 15.2489 + <sect1> 15.2490 + <title>Good ways to work with patches</title> 15.2491 + 15.2492 + <para id="x_433">Whether you are working on a patch series to submit to a 15.2493 + free software or open source project, or a series that you 15.2494 + intend to treat as a sequence of regular changesets when you're 15.2495 + done, you can use some simple techniques to keep your work well 15.2496 + organized.</para> 15.2497 + 15.2498 + <para id="x_434">Give your patches descriptive names. A good name for a 15.2499 + patch might be <filename>rework-device-alloc.patch</filename>, 15.2500 + because it will immediately give you a hint what the purpose of 15.2501 + the patch is. Long names shouldn't be a problem; you won't be 15.2502 + typing the names often, but you <emphasis>will</emphasis> be 15.2503 + running commands like <command 15.2504 + role="hg-ext-mq">qapplied</command> and <command 15.2505 + role="hg-ext-mq">qtop</command> over and over. Good naming 15.2506 + becomes especially important when you have a number of patches 15.2507 + to work with, or if you are juggling a number of different tasks 15.2508 + and your patches only get a fraction of your attention.</para> 15.2509 + 15.2510 + <para id="x_435">Be aware of what patch you're working on. Use the <command 15.2511 + role="hg-ext-mq">qtop</command> command and skim over the text 15.2512 + of your patches frequently&emdash;for example, using <command 15.2513 + role="hg-cmd">hg tip <option 15.2514 + role="hg-opt-tip">-p</option></command>)&emdash;to be sure 15.2515 + of where you stand. I have several times worked on and <command 15.2516 + role="hg-ext-mq">qrefresh</command>ed a patch other than the 15.2517 + one I intended, and it's often tricky to migrate changes into 15.2518 + the right patch after making them in the wrong one.</para> 15.2519 + 15.2520 + <para id="x_436">For this reason, it is very much worth investing a little 15.2521 + time to learn how to use some of the third-party tools I 15.2522 + described in <xref linkend="sec:mq:tools"/>, 15.2523 + particularly 15.2524 + <command>diffstat</command> and <command>filterdiff</command>. 15.2525 + The former will give you a quick idea of what changes your patch 15.2526 + is making, while the latter makes it easy to splice hunks 15.2527 + selectively out of one patch and into another.</para> 15.2528 + 15.2529 + </sect1> 15.2530 + <sect1> 15.2531 + <title>MQ cookbook</title> 15.2532 + 15.2533 + <sect2> 15.2534 + <title>Manage <quote>trivial</quote> patches</title> 15.2535 + 15.2536 + <para id="x_437">Because the overhead of dropping files into a new 15.2537 + Mercurial repository is so low, it makes a lot of sense to 15.2538 + manage patches this way even if you simply want to make a few 15.2539 + changes to a source tarball that you downloaded.</para> 15.2540 + 15.2541 + <para id="x_438">Begin by downloading and unpacking the source tarball, and 15.2542 + turning it into a Mercurial repository.</para> 15.2543 + 15.2544 + &interaction.mq.tarball.download; 15.2545 + 15.2546 + <para id="x_439">Continue by creating a patch stack and making your 15.2547 + changes.</para> 15.2548 + 15.2549 + &interaction.mq.tarball.qinit; 15.2550 + 15.2551 + <para id="x_43a">Let's say a few weeks or months pass, and your package 15.2552 + author releases a new version. First, bring their changes 15.2553 + into the repository.</para> 15.2554 + 15.2555 + &interaction.mq.tarball.newsource; 15.2556 + 15.2557 + <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg 15.2558 + locate</command> above deletes all files in the working 15.2559 + directory, so that <command role="hg-cmd">hg 15.2560 + commit</command>'s <option 15.2561 + role="hg-opt-commit">--addremove</option> option can 15.2562 + actually tell which files have really been removed in the 15.2563 + newer version of the source.</para> 15.2564 + 15.2565 + <para id="x_43c">Finally, you can apply your patches on top of the new 15.2566 + tree.</para> 15.2567 + 15.2568 + &interaction.mq.tarball.repush; 15.2569 + </sect2> 15.2570 + 15.2571 + <sect2 id="sec:mq:combine"> 15.2572 + <title>Combining entire patches</title> 15.2573 + 15.2574 + <para id="x_43d">MQ provides a command, <command 15.2575 + role="hg-ext-mq">qfold</command> that lets you combine 15.2576 + entire patches. This <quote>folds</quote> the patches you 15.2577 + name, in the order you name them, into the topmost applied 15.2578 + patch, and concatenates their descriptions onto the end of its 15.2579 + description. The patches that you fold must be unapplied 15.2580 + before you fold them.</para> 15.2581 + 15.2582 + <para id="x_43e">The order in which you fold patches matters. If your 15.2583 + topmost applied patch is <literal>foo</literal>, and you 15.2584 + <command role="hg-ext-mq">qfold</command> 15.2585 + <literal>bar</literal> and <literal>quux</literal> into it, 15.2586 + you will end up with a patch that has the same effect as if 15.2587 + you applied first <literal>foo</literal>, then 15.2588 + <literal>bar</literal>, followed by 15.2589 + <literal>quux</literal>.</para> 15.2590 + </sect2> 15.2591 + 15.2592 + <sect2> 15.2593 + <title>Merging part of one patch into another</title> 15.2594 + 15.2595 + <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into 15.2596 + another is more difficult than combining entire 15.2597 + patches.</para> 15.2598 + 15.2599 + <para id="x_440">If you want to move changes to entire files, you can use 15.2600 + <command>filterdiff</command>'s <option 15.2601 + role="cmd-opt-filterdiff">-i</option> and <option 15.2602 + role="cmd-opt-filterdiff">-x</option> options to choose the 15.2603 + modifications to snip out of one patch, concatenating its 15.2604 + output onto the end of the patch you want to merge into. You 15.2605 + usually won't need to modify the patch you've merged the 15.2606 + changes from. Instead, MQ will report some rejected hunks 15.2607 + when you <command role="hg-ext-mq">qpush</command> it (from 15.2608 + the hunks you moved into the other patch), and you can simply 15.2609 + <command role="hg-ext-mq">qrefresh</command> the patch to drop 15.2610 + the duplicate hunks.</para> 15.2611 + 15.2612 + <para id="x_441">If you have a patch that has multiple hunks modifying a 15.2613 + file, and you only want to move a few of those hunks, the job 15.2614 + becomes more messy, but you can still partly automate it. Use 15.2615 + <command>lsdiff -nvv</command> to print some metadata about 15.2616 + the patch.</para> 15.2617 + 15.2618 + &interaction.mq.tools.lsdiff; 15.2619 + 15.2620 + <para id="x_442">This command prints three different kinds of 15.2621 + number:</para> 15.2622 + <itemizedlist> 15.2623 + <listitem><para id="x_443">(in the first column) a <emphasis>file 15.2624 + number</emphasis> to identify each file modified in the 15.2625 + patch;</para> 15.2626 + </listitem> 15.2627 + <listitem><para id="x_444">(on the next line, indented) the line number 15.2628 + within a modified file where a hunk starts; and</para> 15.2629 + </listitem> 15.2630 + <listitem><para id="x_445">(on the same line) a <emphasis>hunk 15.2631 + number</emphasis> to identify that hunk.</para> 15.2632 + </listitem></itemizedlist> 15.2633 + 15.2634 + <para id="x_446">You'll have to use some visual inspection, and reading of 15.2635 + the patch, to identify the file and hunk numbers you'll want, 15.2636 + but you can then pass them to to 15.2637 + <command>filterdiff</command>'s <option 15.2638 + role="cmd-opt-filterdiff">--files</option> and <option 15.2639 + role="cmd-opt-filterdiff">--hunks</option> options, to 15.2640 + select exactly the file and hunk you want to extract.</para> 15.2641 + 15.2642 + <para id="x_447">Once you have this hunk, you can concatenate it onto the 15.2643 + end of your destination patch and continue with the remainder 15.2644 + of <xref linkend="sec:mq:combine"/>.</para> 15.2645 + 15.2646 + </sect2> 15.2647 + </sect1> 15.2648 + <sect1> 15.2649 + <title>Differences between quilt and MQ</title> 15.2650 + 15.2651 + <para id="x_448">If you are already familiar with quilt, MQ provides a 15.2652 + similar command set. There are a few differences in the way 15.2653 + that it works.</para> 15.2654 + 15.2655 + <para id="x_449">You will already have noticed that most quilt commands have 15.2656 + MQ counterparts that simply begin with a 15.2657 + <quote><literal>q</literal></quote>. The exceptions are quilt's 15.2658 + <literal>add</literal> and <literal>remove</literal> commands, 15.2659 + the counterparts for which are the normal Mercurial <command 15.2660 + role="hg-cmd">hg add</command> and <command role="hg-cmd">hg 15.2661 + remove</command> commands. There is no MQ equivalent of the 15.2662 + quilt <literal>edit</literal> command.</para> 15.2663 + 15.2664 + </sect1> 15.2665 </chapter> 15.2666 15.2667 <!-- 15.2668 local variables: 15.2669 sgml-parent-document: ("00book.xml" "book" "chapter") 15.2670 end: 15.2671 ---> 15.2672 \ No newline at end of file 15.2673 +-->
16.1 --- a/fr/ch13-mq-collab.xml Sat Sep 12 17:58:26 2009 +0200 16.2 +++ b/fr/ch13-mq-collab.xml Sat Sep 12 17:58:56 2009 +0200 16.3 @@ -1,499 +1,525 @@ 16.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 16.5 16.6 -<chapter> 16.7 -<title>Advanced uses of Mercurial Queues</title> 16.8 -<para>\label{chap:mq-collab}</para> 16.9 - 16.10 -<para>While it's easy to pick up straightforward uses of Mercurial Queues, 16.11 -use of a little discipline and some of MQ's less frequently used 16.12 -capabilities makes it possible to work in complicated development 16.13 -environments.</para> 16.14 - 16.15 -<para>In this chapter, I will use as an example a technique I have used to 16.16 -manage the development of an Infiniband device driver for the Linux 16.17 -kernel. The driver in question is large (at least as drivers go), 16.18 -with 25,000 lines of code spread across 35 source files. It is 16.19 -maintained by a small team of developers.</para> 16.20 - 16.21 -<para>While much of the material in this chapter is specific to Linux, the 16.22 -same principles apply to any code base for which you're not the 16.23 -primary owner, and upon which you need to do a lot of development.</para> 16.24 - 16.25 -<sect1> 16.26 -<title>The problem of many targets</title> 16.27 - 16.28 -<para>The Linux kernel changes rapidly, and has never been internally 16.29 -stable; developers frequently make drastic changes between releases. 16.30 -This means that a version of the driver that works well with a 16.31 -particular released version of the kernel will not even <emphasis>compile</emphasis> 16.32 -correctly against, typically, any other version.</para> 16.33 - 16.34 -<para>To maintain a driver, we have to keep a number of distinct versions of 16.35 -Linux in mind.</para> 16.36 -<itemizedlist> 16.37 -<listitem><para>One target is the main Linux kernel development tree. 16.38 - Maintenance of the code is in this case partly shared by other 16.39 - developers in the kernel community, who make <quote>drive-by</quote> 16.40 - modifications to the driver as they develop and refine kernel 16.41 - subsystems.</para> 16.42 -</listitem> 16.43 -<listitem><para>We also maintain a number of <quote>backports</quote> to older versions of 16.44 - the Linux kernel, to support the needs of customers who are running 16.45 - older Linux distributions that do not incorporate our drivers. (To 16.46 - <emphasis>backport</emphasis> a piece of code is to modify it to work in an older 16.47 - version of its target environment than the version it was developed 16.48 - for.)</para> 16.49 -</listitem> 16.50 -<listitem><para>Finally, we make software releases on a schedule that is 16.51 - necessarily not aligned with those used by Linux distributors and 16.52 - kernel developers, so that we can deliver new features to customers 16.53 - without forcing them to upgrade their entire kernels or 16.54 - distributions. 16.55 -</para> 16.56 -</listitem></itemizedlist> 16.57 - 16.58 -<sect2> 16.59 -<title>Tempting approaches that don't work well</title> 16.60 - 16.61 -<para>There are two <quote>standard</quote> ways to maintain a piece of software that 16.62 -has to target many different environments. 16.63 -</para> 16.64 - 16.65 -<para>The first is to maintain a number of branches, each intended for a 16.66 -single target. The trouble with this approach is that you must 16.67 -maintain iron discipline in the flow of changes between repositories. 16.68 -A new feature or bug fix must start life in a <quote>pristine</quote> repository, 16.69 -then percolate out to every backport repository. Backport changes are 16.70 -more limited in the branches they should propagate to; a backport 16.71 -change that is applied to a branch where it doesn't belong will 16.72 -probably stop the driver from compiling. 16.73 -</para> 16.74 - 16.75 -<para>The second is to maintain a single source tree filled with conditional 16.76 -statements that turn chunks of code on or off depending on the 16.77 -intended target. Because these <quote>ifdefs</quote> are not allowed in the 16.78 -Linux kernel tree, a manual or automatic process must be followed to 16.79 -strip them out and yield a clean tree. A code base maintained in this 16.80 -fashion rapidly becomes a rat's nest of conditional blocks that are 16.81 -difficult to understand and maintain. 16.82 -</para> 16.83 - 16.84 -<para>Neither of these approaches is well suited to a situation where you 16.85 -don't <quote>own</quote> the canonical copy of a source tree. In the case of a 16.86 -Linux driver that is distributed with the standard kernel, Linus's 16.87 -tree contains the copy of the code that will be treated by the world 16.88 -as canonical. The upstream version of <quote>my</quote> driver can be modified 16.89 -by people I don't know, without me even finding out about it until 16.90 -after the changes show up in Linus's tree. 16.91 -</para> 16.92 - 16.93 -<para>These approaches have the added weakness of making it difficult to 16.94 -generate well-formed patches to submit upstream. 16.95 -</para> 16.96 - 16.97 -<para>In principle, Mercurial Queues seems like a good candidate to manage a 16.98 -development scenario such as the above. While this is indeed the 16.99 -case, MQ contains a few added features that make the job more 16.100 -pleasant. 16.101 -</para> 16.102 - 16.103 -<para>\section{Conditionally applying patches with 16.104 - guards} 16.105 -</para> 16.106 - 16.107 -<para>Perhaps the best way to maintain sanity with so many targets is to be 16.108 -able to choose specific patches to apply for a given situation. MQ 16.109 -provides a feature called <quote>guards</quote> (which originates with quilt's 16.110 -<literal>guards</literal> command) that does just this. To start off, let's 16.111 -create a simple repository for experimenting in. 16.112 -<!-- &interaction.mq.guards.init; --> 16.113 -This gives us a tiny repository that contains two patches that don't 16.114 -have any dependencies on each other, because they touch different files. 16.115 -</para> 16.116 - 16.117 -<para>The idea behind conditional application is that you can <quote>tag</quote> a 16.118 -patch with a <emphasis>guard</emphasis>, which is simply a text string of your 16.119 -choosing, then tell MQ to select specific guards to use when applying 16.120 -patches. MQ will then either apply, or skip over, a guarded patch, 16.121 -depending on the guards that you have selected. 16.122 -</para> 16.123 - 16.124 -<para>A patch can have an arbitrary number of guards; 16.125 -each one is <emphasis>positive</emphasis> (<quote>apply this patch if this guard is 16.126 -selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if this guard is 16.127 -selected</quote>). A patch with no guards is always applied. 16.128 -</para> 16.129 - 16.130 -</sect2> 16.131 -</sect1> 16.132 -<sect1> 16.133 -<title>Controlling the guards on a patch</title> 16.134 - 16.135 -<para>The <command role="hg-ext-mq">qguard</command> command lets you determine which guards should 16.136 -apply to a patch, or display the guards that are already in effect. 16.137 -Without any arguments, it displays the guards on the current topmost 16.138 -patch. 16.139 -<!-- &interaction.mq.guards.qguard; --> 16.140 -To set a positive guard on a patch, prefix the name of the guard with 16.141 -a <quote><literal>+</literal></quote>. 16.142 -<!-- &interaction.mq.guards.qguard.pos; --> 16.143 -To set a negative guard on a patch, prefix the name of the guard with 16.144 -a <quote><literal>-</literal></quote>. 16.145 -<!-- &interaction.mq.guards.qguard.neg; --> 16.146 -</para> 16.147 - 16.148 -<note> 16.149 -<para> The <command role="hg-ext-mq">qguard</command> command <emphasis>sets</emphasis> the guards on a patch; it 16.150 - doesn't <emphasis>modify</emphasis> them. What this means is that if you run 16.151 - <command role="hg-cmd">hg qguard +a +b</command> on a patch, then <command role="hg-cmd">hg qguard +c</command> on 16.152 - the same patch, the <emphasis>only</emphasis> guard that will be set on it 16.153 - afterwards is <literal>+c</literal>. 16.154 -</para> 16.155 -</note> 16.156 - 16.157 -<para>Mercurial stores guards in the <filename role="special">series</filename> file; the form in 16.158 -which they are stored is easy both to understand and to edit by hand. 16.159 -(In other words, you don't have to use the <command role="hg-ext-mq">qguard</command> command if 16.160 -you don't want to; it's okay to simply edit the <filename role="special">series</filename> 16.161 -file.) 16.162 -<!-- &interaction.mq.guards.series; --> 16.163 -</para> 16.164 - 16.165 -</sect1> 16.166 -<sect1> 16.167 -<title>Selecting the guards to use</title> 16.168 - 16.169 -<para>The <command role="hg-ext-mq">qselect</command> command determines which guards are active at a 16.170 -given time. The effect of this is to determine which patches MQ will 16.171 -apply the next time you run <command role="hg-ext-mq">qpush</command>. It has no other effect; in 16.172 -particular, it doesn't do anything to patches that are already 16.173 -applied. 16.174 -</para> 16.175 - 16.176 -<para>With no arguments, the <command role="hg-ext-mq">qselect</command> command lists the guards 16.177 -currently in effect, one per line of output. Each argument is treated 16.178 -as the name of a guard to apply. 16.179 -<!-- &interaction.mq.guards.qselect.foo; --> 16.180 -In case you're interested, the currently selected guards are stored in 16.181 -the <filename role="special">guards</filename> file. 16.182 -<!-- &interaction.mq.guards.qselect.cat; --> 16.183 -We can see the effect the selected guards have when we run 16.184 -<command role="hg-ext-mq">qpush</command>. 16.185 -<!-- &interaction.mq.guards.qselect.qpush; --> 16.186 -</para> 16.187 - 16.188 -<para>A guard cannot start with a <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote> 16.189 -character. The name of a guard must not contain white space, but most 16.190 -other characters are acceptable. If you try to use a guard with an 16.191 -invalid name, MQ will complain: 16.192 -<!-- &interaction.mq.guards.qselect.error; --> 16.193 -Changing the selected guards changes the patches that are applied. 16.194 -<!-- &interaction.mq.guards.qselect.quux; --> 16.195 -You can see in the example below that negative guards take precedence 16.196 -over positive guards. 16.197 -<!-- &interaction.mq.guards.qselect.foobar; --> 16.198 -</para> 16.199 - 16.200 -</sect1> 16.201 -<sect1> 16.202 -<title>MQ's rules for applying patches</title> 16.203 - 16.204 -<para>The rules that MQ uses when deciding whether to apply a patch 16.205 -are as follows. 16.206 -</para> 16.207 -<itemizedlist> 16.208 -<listitem><para>A patch that has no guards is always applied. 16.209 -</para> 16.210 -</listitem> 16.211 -<listitem><para>If the patch has any negative guard that matches any currently 16.212 - selected guard, the patch is skipped. 16.213 -</para> 16.214 -</listitem> 16.215 -<listitem><para>If the patch has any positive guard that matches any currently 16.216 - selected guard, the patch is applied. 16.217 -</para> 16.218 -</listitem> 16.219 -<listitem><para>If the patch has positive or negative guards, but none matches 16.220 - any currently selected guard, the patch is skipped. 16.221 -</para> 16.222 -</listitem></itemizedlist> 16.223 - 16.224 -</sect1> 16.225 -<sect1> 16.226 -<title>Trimming the work environment</title> 16.227 - 16.228 -<para>In working on the device driver I mentioned earlier, I don't apply the 16.229 -patches to a normal Linux kernel tree. Instead, I use a repository 16.230 -that contains only a snapshot of the source files and headers that are 16.231 -relevant to Infiniband development. This repository is 1% the size 16.232 -of a kernel repository, so it's easier to work with. 16.233 -</para> 16.234 - 16.235 -<para>I then choose a <quote>base</quote> version on top of which the patches are 16.236 -applied. This is a snapshot of the Linux kernel tree as of a revision 16.237 -of my choosing. When I take the snapshot, I record the changeset ID 16.238 -from the kernel repository in the commit message. Since the snapshot 16.239 -preserves the <quote>shape</quote> and content of the relevant parts of the 16.240 -kernel tree, I can apply my patches on top of either my tiny 16.241 -repository or a normal kernel tree. 16.242 -</para> 16.243 - 16.244 -<para>Normally, the base tree atop which the patches apply should be a 16.245 -snapshot of a very recent upstream tree. This best facilitates the 16.246 -development of patches that can easily be submitted upstream with few 16.247 -or no modifications. 16.248 -</para> 16.249 - 16.250 -</sect1> 16.251 -<sect1> 16.252 -<title>Dividing up the <filename role="special">series</filename> file</title> 16.253 - 16.254 -<para>I categorise the patches in the <filename role="special">series</filename> file into a number 16.255 -of logical groups. Each section of like patches begins with a block 16.256 -of comments that describes the purpose of the patches that follow. 16.257 -</para> 16.258 - 16.259 -<para>The sequence of patch groups that I maintain follows. The ordering of 16.260 -these groups is important; I'll describe why after I introduce the 16.261 -groups. 16.262 -</para> 16.263 -<itemizedlist> 16.264 -<listitem><para>The <quote>accepted</quote> group. Patches that the development team has 16.265 - submitted to the maintainer of the Infiniband subsystem, and which 16.266 - he has accepted, but which are not present in the snapshot that the 16.267 - tiny repository is based on. These are <quote>read only</quote> patches, 16.268 - present only to transform the tree into a similar state as it is in 16.269 - the upstream maintainer's repository. 16.270 -</para> 16.271 -</listitem> 16.272 -<listitem><para>The <quote>rework</quote> group. Patches that I have submitted, but that 16.273 - the upstream maintainer has requested modifications to before he 16.274 - will accept them. 16.275 -</para> 16.276 -</listitem> 16.277 -<listitem><para>The <quote>pending</quote> group. Patches that I have not yet submitted to 16.278 - the upstream maintainer, but which we have finished working on. 16.279 - These will be <quote>read only</quote> for a while. If the upstream maintainer 16.280 - accepts them upon submission, I'll move them to the end of the 16.281 - <quote>accepted</quote> group. If he requests that I modify any, I'll move 16.282 - them to the beginning of the <quote>rework</quote> group. 16.283 -</para> 16.284 -</listitem> 16.285 -<listitem><para>The <quote>in progress</quote> group. Patches that are actively being 16.286 - developed, and should not be submitted anywhere yet. 16.287 -</para> 16.288 -</listitem> 16.289 -<listitem><para>The <quote>backport</quote> group. Patches that adapt the source tree to 16.290 - older versions of the kernel tree. 16.291 -</para> 16.292 -</listitem> 16.293 -<listitem><para>The <quote>do not ship</quote> group. Patches that for some reason should 16.294 - never be submitted upstream. For example, one such patch might 16.295 - change embedded driver identification strings to make it easier to 16.296 - distinguish, in the field, between an out-of-tree version of the 16.297 - driver and a version shipped by a distribution vendor. 16.298 -</para> 16.299 -</listitem></itemizedlist> 16.300 - 16.301 -<para>Now to return to the reasons for ordering groups of patches in this 16.302 -way. We would like the lowest patches in the stack to be as stable as 16.303 -possible, so that we will not need to rework higher patches due to 16.304 -changes in context. Putting patches that will never be changed first 16.305 -in the <filename role="special">series</filename> file serves this purpose. 16.306 -</para> 16.307 - 16.308 -<para>We would also like the patches that we know we'll need to modify to be 16.309 -applied on top of a source tree that resembles the upstream tree as 16.310 -closely as possible. This is why we keep accepted patches around for 16.311 -a while. 16.312 -</para> 16.313 - 16.314 -<para>The <quote>backport</quote> and <quote>do not ship</quote> patches float at the end of the 16.315 -<filename role="special">series</filename> file. The backport patches must be applied on top 16.316 -of all other patches, and the <quote>do not ship</quote> patches might as well 16.317 -stay out of harm's way. 16.318 -</para> 16.319 - 16.320 -</sect1> 16.321 -<sect1> 16.322 -<title>Maintaining the patch series</title> 16.323 - 16.324 -<para>In my work, I use a number of guards to control which patches are to 16.325 -be applied. 16.326 -</para> 16.327 - 16.328 -<itemizedlist> 16.329 -<listitem><para><quote>Accepted</quote> patches are guarded with <literal>accepted</literal>. I 16.330 - enable this guard most of the time. When I'm applying the patches 16.331 - on top of a tree where the patches are already present, I can turn 16.332 - this patch off, and the patches that follow it will apply cleanly. 16.333 -</para> 16.334 -</listitem> 16.335 -<listitem><para>Patches that are <quote>finished</quote>, but not yet submitted, have no 16.336 - guards. If I'm applying the patch stack to a copy of the upstream 16.337 - tree, I don't need to enable any guards in order to get a reasonably 16.338 - safe source tree. 16.339 -</para> 16.340 -</listitem> 16.341 -<listitem><para>Those patches that need reworking before being resubmitted are 16.342 - guarded with <literal>rework</literal>. 16.343 -</para> 16.344 -</listitem> 16.345 -<listitem><para>For those patches that are still under development, I use 16.346 - <literal>devel</literal>. 16.347 -</para> 16.348 -</listitem> 16.349 -<listitem><para>A backport patch may have several guards, one for each version 16.350 - of the kernel to which it applies. For example, a patch that 16.351 - backports a piece of code to 2.6.9 will have a <literal>2.6.9</literal> guard. 16.352 -</para> 16.353 -</listitem></itemizedlist> 16.354 -<para>This variety of guards gives me considerable flexibility in 16.355 -determining what kind of source tree I want to end up with. For most 16.356 -situations, the selection of appropriate guards is automated during 16.357 -the build process, but I can manually tune the guards to use for less 16.358 -common circumstances. 16.359 -</para> 16.360 - 16.361 -<sect2> 16.362 -<title>The art of writing backport patches</title> 16.363 - 16.364 -<para>Using MQ, writing a backport patch is a simple process. All such a 16.365 -patch has to do is modify a piece of code that uses a kernel feature 16.366 -not present in the older version of the kernel, so that the driver 16.367 -continues to work correctly under that older version. 16.368 -</para> 16.369 - 16.370 -<para>A useful goal when writing a good backport patch is to make your code 16.371 -look as if it was written for the older version of the kernel you're 16.372 -targeting. The less obtrusive the patch, the easier it will be to 16.373 -understand and maintain. If you're writing a collection of backport 16.374 -patches to avoid the <quote>rat's nest</quote> effect of lots of 16.375 -<literal>#ifdef</literal>s (hunks of source code that are only used 16.376 -conditionally) in your code, don't introduce version-dependent 16.377 -<literal>#ifdef</literal>s into the patches. Instead, write several patches, 16.378 -each of which makes unconditional changes, and control their 16.379 -application using guards. 16.380 -</para> 16.381 - 16.382 -<para>There are two reasons to divide backport patches into a distinct 16.383 -group, away from the <quote>regular</quote> patches whose effects they modify. 16.384 -The first is that intermingling the two makes it more difficult to use 16.385 -a tool like the <literal role="hg-ext">patchbomb</literal> extension to automate the process of 16.386 -submitting the patches to an upstream maintainer. The second is that 16.387 -a backport patch could perturb the context in which a subsequent 16.388 -regular patch is applied, making it impossible to apply the regular 16.389 -patch cleanly <emphasis>without</emphasis> the earlier backport patch already being 16.390 -applied. 16.391 -</para> 16.392 - 16.393 -</sect2> 16.394 -</sect1> 16.395 -<sect1> 16.396 -<title>Useful tips for developing with MQ</title> 16.397 - 16.398 -<sect2> 16.399 -<title>Organising patches in directories</title> 16.400 - 16.401 -<para>If you're working on a substantial project with MQ, it's not difficult 16.402 -to accumulate a large number of patches. For example, I have one 16.403 -patch repository that contains over 250 patches. 16.404 -</para> 16.405 - 16.406 -<para>If you can group these patches into separate logical categories, you 16.407 -can if you like store them in different directories; MQ has no 16.408 -problems with patch names that contain path separators. 16.409 -</para> 16.410 - 16.411 -</sect2> 16.412 -<sect2> 16.413 -<title>Viewing the history of a patch</title> 16.414 -<para>\label{mq-collab:tips:interdiff} 16.415 -</para> 16.416 - 16.417 -<para>If you're developing a set of patches over a long time, it's a good 16.418 -idea to maintain them in a repository, as discussed in 16.419 -section <xref linkend="sec:mq:repo"/>. If you do so, you'll quickly discover that 16.420 -using the <command role="hg-cmd">hg diff</command> command to look at the history of changes to a 16.421 -patch is unworkable. This is in part because you're looking at the 16.422 -second derivative of the real code (a diff of a diff), but also 16.423 -because MQ adds noise to the process by modifying time stamps and 16.424 -directory names when it updates a patch. 16.425 -</para> 16.426 - 16.427 -<para>However, you can use the <literal role="hg-ext">extdiff</literal> extension, which is bundled 16.428 -with Mercurial, to turn a diff of two versions of a patch into 16.429 -something readable. To do this, you will need a third-party package 16.430 -called <literal role="package">patchutils</literal> <citation>web:patchutils</citation>. This provides a 16.431 -command named <command>interdiff</command>, which shows the differences between 16.432 -two diffs as a diff. Used on two versions of the same diff, it 16.433 -generates a diff that represents the diff from the first to the second 16.434 -version. 16.435 -</para> 16.436 - 16.437 -<para>You can enable the <literal role="hg-ext">extdiff</literal> extension in the usual way, by 16.438 -adding a line to the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>. 16.439 -</para> 16.440 -<programlisting> 16.441 -<para> [extensions] 16.442 - extdiff = 16.443 -</para> 16.444 -</programlisting> 16.445 -<para>The <command>interdiff</command> command expects to be passed the names of two 16.446 -files, but the <literal role="hg-ext">extdiff</literal> extension passes the program it runs a 16.447 -pair of directories, each of which can contain an arbitrary number of 16.448 -files. We thus need a small program that will run <command>interdiff</command> 16.449 -on each pair of files in these two directories. This program is 16.450 -available as <filename role="special">hg-interdiff</filename> in the <filename class="directory">examples</filename> 16.451 -directory of the source code repository that accompanies this book. 16.452 -<!-- &example.hg-interdiff; --> 16.453 -</para> 16.454 - 16.455 -<para>With the <filename role="special">hg-interdiff</filename> program in your shell's search path, 16.456 -you can run it as follows, from inside an MQ patch directory: 16.457 -</para> 16.458 -<programlisting> 16.459 -<para> hg extdiff -p hg-interdiff -r A:B my-change.patch 16.460 -</para> 16.461 -</programlisting> 16.462 -<para>Since you'll probably want to use this long-winded command a lot, you 16.463 -can get <literal role="hg-ext">hgext</literal> to make it available as a normal Mercurial 16.464 -command, again by editing your <filename role="special"> /.hgrc</filename>. 16.465 -</para> 16.466 -<programlisting> 16.467 -<para> [extdiff] 16.468 - cmd.interdiff = hg-interdiff 16.469 -</para> 16.470 -</programlisting> 16.471 -<para>This directs <literal role="hg-ext">hgext</literal> to make an <literal>interdiff</literal> command 16.472 -available, so you can now shorten the previous invocation of 16.473 -<command role="hg-ext-extdiff">extdiff</command> to something a little more wieldy. 16.474 -</para> 16.475 -<programlisting> 16.476 -<para> hg interdiff -r A:B my-change.patch 16.477 -</para> 16.478 -</programlisting> 16.479 - 16.480 -<note> 16.481 -<para> The <command>interdiff</command> command works well only if the underlying 16.482 - files against which versions of a patch are generated remain the 16.483 - same. If you create a patch, modify the underlying files, and then 16.484 - regenerate the patch, <command>interdiff</command> may not produce useful 16.485 - output. 16.486 -</para> 16.487 -</note> 16.488 - 16.489 -<para>The <literal role="hg-ext">extdiff</literal> extension is useful for more than merely improving 16.490 -the presentation of MQ patches. To read more about it, go to 16.491 -section <xref linkend="sec:hgext:extdiff"/>. 16.492 -</para> 16.493 - 16.494 -</sect2> 16.495 -</sect1> 16.496 +<chapter id="chap:mq-collab"> 16.497 + <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> 16.498 + <title>Advanced uses of Mercurial Queues</title> 16.499 + 16.500 + <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial 16.501 + Queues, use of a little discipline and some of MQ's less 16.502 + frequently used capabilities makes it possible to work in 16.503 + complicated development environments.</para> 16.504 + 16.505 + <para id="x_15e">In this chapter, I will use as an example a technique I have 16.506 + used to manage the development of an Infiniband device driver for 16.507 + the Linux kernel. The driver in question is large (at least as 16.508 + drivers go), with 25,000 lines of code spread across 35 source 16.509 + files. It is maintained by a small team of developers.</para> 16.510 + 16.511 + <para id="x_15f">While much of the material in this chapter is specific to 16.512 + Linux, the same principles apply to any code base for which you're 16.513 + not the primary owner, and upon which you need to do a lot of 16.514 + development.</para> 16.515 + 16.516 + <sect1> 16.517 + <title>The problem of many targets</title> 16.518 + 16.519 + <para id="x_160">The Linux kernel changes rapidly, and has never been 16.520 + internally stable; developers frequently make drastic changes 16.521 + between releases. This means that a version of the driver that 16.522 + works well with a particular released version of the kernel will 16.523 + not even <emphasis>compile</emphasis> correctly against, 16.524 + typically, any other version.</para> 16.525 + 16.526 + <para id="x_161">To maintain a driver, we have to keep a number of distinct 16.527 + versions of Linux in mind.</para> 16.528 + <itemizedlist> 16.529 + <listitem><para id="x_162">One target is the main Linux kernel development 16.530 + tree. Maintenance of the code is in this case partly shared 16.531 + by other developers in the kernel community, who make 16.532 + <quote>drive-by</quote> modifications to the driver as they 16.533 + develop and refine kernel subsystems.</para> 16.534 + </listitem> 16.535 + <listitem><para id="x_163">We also maintain a number of 16.536 + <quote>backports</quote> to older versions of the Linux 16.537 + kernel, to support the needs of customers who are running 16.538 + older Linux distributions that do not incorporate our 16.539 + drivers. (To <emphasis>backport</emphasis> a piece of code 16.540 + is to modify it to work in an older version of its target 16.541 + environment than the version it was developed for.)</para> 16.542 + </listitem> 16.543 + <listitem><para id="x_164">Finally, we make software releases on a schedule 16.544 + that is necessarily not aligned with those used by Linux 16.545 + distributors and kernel developers, so that we can deliver 16.546 + new features to customers without forcing them to upgrade 16.547 + their entire kernels or distributions.</para> 16.548 + </listitem></itemizedlist> 16.549 + 16.550 + <sect2> 16.551 + <title>Tempting approaches that don't work well</title> 16.552 + 16.553 + <para id="x_165">There are two <quote>standard</quote> ways to maintain a 16.554 + piece of software that has to target many different 16.555 + environments.</para> 16.556 + 16.557 + <para id="x_166">The first is to maintain a number of branches, each 16.558 + intended for a single target. The trouble with this approach 16.559 + is that you must maintain iron discipline in the flow of 16.560 + changes between repositories. A new feature or bug fix must 16.561 + start life in a <quote>pristine</quote> repository, then 16.562 + percolate out to every backport repository. Backport changes 16.563 + are more limited in the branches they should propagate to; a 16.564 + backport change that is applied to a branch where it doesn't 16.565 + belong will probably stop the driver from compiling.</para> 16.566 + 16.567 + <para id="x_167">The second is to maintain a single source tree filled with 16.568 + conditional statements that turn chunks of code on or off 16.569 + depending on the intended target. Because these 16.570 + <quote>ifdefs</quote> are not allowed in the Linux kernel 16.571 + tree, a manual or automatic process must be followed to strip 16.572 + them out and yield a clean tree. A code base maintained in 16.573 + this fashion rapidly becomes a rat's nest of conditional 16.574 + blocks that are difficult to understand and maintain.</para> 16.575 + 16.576 + <para id="x_168">Neither of these approaches is well suited to a situation 16.577 + where you don't <quote>own</quote> the canonical copy of a 16.578 + source tree. In the case of a Linux driver that is 16.579 + distributed with the standard kernel, Linus's tree contains 16.580 + the copy of the code that will be treated by the world as 16.581 + canonical. The upstream version of <quote>my</quote> driver 16.582 + can be modified by people I don't know, without me even 16.583 + finding out about it until after the changes show up in 16.584 + Linus's tree.</para> 16.585 + 16.586 + <para id="x_169">These approaches have the added weakness of making it 16.587 + difficult to generate well-formed patches to submit 16.588 + upstream.</para> 16.589 + 16.590 + <para id="x_16a">In principle, Mercurial Queues seems like a good candidate 16.591 + to manage a development scenario such as the above. While 16.592 + this is indeed the case, MQ contains a few added features that 16.593 + make the job more pleasant.</para> 16.594 + 16.595 + </sect2> 16.596 + </sect1> 16.597 + <sect1> 16.598 + <title>Conditionally applying patches with guards</title> 16.599 + 16.600 + <para id="x_16b">Perhaps the best way to maintain sanity with so many targets 16.601 + is to be able to choose specific patches to apply for a given 16.602 + situation. MQ provides a feature called <quote>guards</quote> 16.603 + (which originates with quilt's <literal>guards</literal> 16.604 + command) that does just this. To start off, let's create a 16.605 + simple repository for experimenting in.</para> 16.606 + 16.607 + &interaction.mq.guards.init; 16.608 + 16.609 + <para id="x_16c">This gives us a tiny repository that contains two patches 16.610 + that don't have any dependencies on each other, because they 16.611 + touch different files.</para> 16.612 + 16.613 + <para id="x_16d">The idea behind conditional application is that you can 16.614 + <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 16.615 + which is simply a text string of your choosing, then tell MQ to 16.616 + select specific guards to use when applying patches. MQ will 16.617 + then either apply, or skip over, a guarded patch, depending on 16.618 + the guards that you have selected.</para> 16.619 + 16.620 + <para id="x_16e">A patch can have an arbitrary number of guards; each one is 16.621 + <emphasis>positive</emphasis> (<quote>apply this patch if this 16.622 + guard is selected</quote>) or <emphasis>negative</emphasis> 16.623 + (<quote>skip this patch if this guard is selected</quote>). A 16.624 + patch with no guards is always applied.</para> 16.625 + 16.626 + </sect1> 16.627 + <sect1> 16.628 + <title>Controlling the guards on a patch</title> 16.629 + 16.630 + <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets 16.631 + you determine which guards should apply to a patch, or display 16.632 + the guards that are already in effect. Without any arguments, it 16.633 + displays the guards on the current topmost patch.</para> 16.634 + 16.635 + &interaction.mq.guards.qguard; 16.636 + 16.637 + <para id="x_170">To set a positive guard on a patch, prefix the name of the 16.638 + guard with a <quote><literal>+</literal></quote>.</para> 16.639 + 16.640 + &interaction.mq.guards.qguard.pos; 16.641 + 16.642 + <para id="x_171">To set a negative guard 16.643 + on a patch, prefix the name of the guard with a 16.644 + <quote><literal>-</literal></quote>.</para> 16.645 + 16.646 + &interaction.mq.guards.qguard.neg; 16.647 + 16.648 + <para id="x_74a">Notice that we prefixed the arguments to the <command>hg 16.649 + qguard</command> command with a <literal>--</literal> here, so 16.650 + that Mercurial would not interpret the text 16.651 + <literal>-quux</literal> as an option.</para> 16.652 + 16.653 + <note> 16.654 + <title>Setting vs. modifying</title> 16.655 + 16.656 + <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command 16.657 + <emphasis>sets</emphasis> the guards on a patch; it doesn't 16.658 + <emphasis>modify</emphasis> them. What this means is that if 16.659 + you run <command role="hg-cmd">hg qguard +a +b</command> on a 16.660 + patch, then <command role="hg-cmd">hg qguard +c</command> on 16.661 + the same patch, the <emphasis>only</emphasis> guard that will 16.662 + be set on it afterwards is <literal>+c</literal>.</para> 16.663 + </note> 16.664 + 16.665 + <para id="x_173">Mercurial stores guards in the <filename 16.666 + role="special">series</filename> file; the form in which they 16.667 + are stored is easy both to understand and to edit by hand. (In 16.668 + other words, you don't have to use the <command 16.669 + role="hg-ext-mq">qguard</command> command if you don't want 16.670 + to; it's okay to simply edit the <filename 16.671 + role="special">series</filename> file.)</para> 16.672 + 16.673 + &interaction.mq.guards.series; 16.674 + 16.675 + </sect1> 16.676 + <sect1> 16.677 + <title>Selecting the guards to use</title> 16.678 + 16.679 + <para id="x_174">The <command role="hg-ext-mq">qselect</command> command 16.680 + determines which guards are active at a given time. The effect 16.681 + of this is to determine which patches MQ will apply the next 16.682 + time you run <command role="hg-ext-mq">qpush</command>. It has 16.683 + no other effect; in particular, it doesn't do anything to 16.684 + patches that are already applied.</para> 16.685 + 16.686 + <para id="x_175">With no arguments, the <command 16.687 + role="hg-ext-mq">qselect</command> command lists the guards 16.688 + currently in effect, one per line of output. Each argument is 16.689 + treated as the name of a guard to apply.</para> 16.690 + 16.691 + &interaction.mq.guards.qselect.foo; 16.692 + 16.693 + <para id="x_176">In case you're interested, the currently selected guards are 16.694 + stored in the <filename role="special">guards</filename> file.</para> 16.695 + 16.696 + &interaction.mq.guards.qselect.cat; 16.697 + 16.698 + <para id="x_177">We can see the effect the selected guards have when we run 16.699 + <command role="hg-ext-mq">qpush</command>.</para> 16.700 + 16.701 + &interaction.mq.guards.qselect.qpush; 16.702 + 16.703 + <para id="x_178">A guard cannot start with a 16.704 + <quote><literal>+</literal></quote> or 16.705 + <quote><literal>-</literal></quote> character. The name of a 16.706 + guard must not contain white space, but most other characters 16.707 + are acceptable. If you try to use a guard with an invalid name, 16.708 + MQ will complain:</para> 16.709 + 16.710 + &interaction.mq.guards.qselect.error; 16.711 + 16.712 + <para id="x_179">Changing the selected guards changes the patches that are 16.713 + applied.</para> 16.714 + 16.715 + &interaction.mq.guards.qselect.quux; 16.716 + 16.717 + <para id="x_17a">You can see in the example below that negative guards take 16.718 + precedence over positive guards.</para> 16.719 + 16.720 + &interaction.mq.guards.qselect.foobar; 16.721 + 16.722 + </sect1> 16.723 + <sect1> 16.724 + <title>MQ's rules for applying patches</title> 16.725 + 16.726 + <para id="x_17b">The rules that MQ uses when deciding whether to apply a 16.727 + patch are as follows.</para> 16.728 + <itemizedlist> 16.729 + <listitem><para id="x_17c">A patch that has no guards is always 16.730 + applied.</para> 16.731 + </listitem> 16.732 + <listitem><para id="x_17d">If the patch has any negative guard that matches 16.733 + any currently selected guard, the patch is skipped.</para> 16.734 + </listitem> 16.735 + <listitem><para id="x_17e">If the patch has any positive guard that matches 16.736 + any currently selected guard, the patch is applied.</para> 16.737 + </listitem> 16.738 + <listitem><para id="x_17f">If the patch has positive or negative guards, 16.739 + but none matches any currently selected guard, the patch is 16.740 + skipped.</para> 16.741 + </listitem></itemizedlist> 16.742 + 16.743 + </sect1> 16.744 + <sect1> 16.745 + <title>Trimming the work environment</title> 16.746 + 16.747 + <para id="x_180">In working on the device driver I mentioned earlier, I don't 16.748 + apply the patches to a normal Linux kernel tree. Instead, I use 16.749 + a repository that contains only a snapshot of the source files 16.750 + and headers that are relevant to Infiniband development. This 16.751 + repository is 1% the size of a kernel repository, so it's easier 16.752 + to work with.</para> 16.753 + 16.754 + <para id="x_181">I then choose a <quote>base</quote> version on top of which 16.755 + the patches are applied. This is a snapshot of the Linux kernel 16.756 + tree as of a revision of my choosing. When I take the snapshot, 16.757 + I record the changeset ID from the kernel repository in the 16.758 + commit message. Since the snapshot preserves the 16.759 + <quote>shape</quote> and content of the relevant parts of the 16.760 + kernel tree, I can apply my patches on top of either my tiny 16.761 + repository or a normal kernel tree.</para> 16.762 + 16.763 + <para id="x_182">Normally, the base tree atop which the patches apply should 16.764 + be a snapshot of a very recent upstream tree. This best 16.765 + facilitates the development of patches that can easily be 16.766 + submitted upstream with few or no modifications.</para> 16.767 + 16.768 + </sect1> 16.769 + <sect1> 16.770 + <title>Dividing up the <filename role="special">series</filename> 16.771 + file</title> 16.772 + 16.773 + <para id="x_183">I categorise the patches in the <filename 16.774 + role="special">series</filename> file into a number of logical 16.775 + groups. Each section of like patches begins with a block of 16.776 + comments that describes the purpose of the patches that 16.777 + follow.</para> 16.778 + 16.779 + <para id="x_184">The sequence of patch groups that I maintain follows. The 16.780 + ordering of these groups is important; I'll describe why after I 16.781 + introduce the groups.</para> 16.782 + <itemizedlist> 16.783 + <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that 16.784 + the development team has submitted to the maintainer of the 16.785 + Infiniband subsystem, and which he has accepted, but which 16.786 + are not present in the snapshot that the tiny repository is 16.787 + based on. These are <quote>read only</quote> patches, 16.788 + present only to transform the tree into a similar state as 16.789 + it is in the upstream maintainer's repository.</para> 16.790 + </listitem> 16.791 + <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I 16.792 + have submitted, but that the upstream maintainer has 16.793 + requested modifications to before he will accept 16.794 + them.</para> 16.795 + </listitem> 16.796 + <listitem><para id="x_187">The <quote>pending</quote> group. Patches that 16.797 + I have not yet submitted to the upstream maintainer, but 16.798 + which we have finished working on. These will be <quote>read 16.799 + only</quote> for a while. If the upstream maintainer 16.800 + accepts them upon submission, I'll move them to the end of 16.801 + the <quote>accepted</quote> group. If he requests that I 16.802 + modify any, I'll move them to the beginning of the 16.803 + <quote>rework</quote> group.</para> 16.804 + </listitem> 16.805 + <listitem><para id="x_188">The <quote>in progress</quote> group. Patches 16.806 + that are actively being developed, and should not be 16.807 + submitted anywhere yet.</para> 16.808 + </listitem> 16.809 + <listitem><para id="x_189">The <quote>backport</quote> group. Patches that 16.810 + adapt the source tree to older versions of the kernel 16.811 + tree.</para> 16.812 + </listitem> 16.813 + <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches 16.814 + that for some reason should never be submitted upstream. 16.815 + For example, one such patch might change embedded driver 16.816 + identification strings to make it easier to distinguish, in 16.817 + the field, between an out-of-tree version of the driver and 16.818 + a version shipped by a distribution vendor.</para> 16.819 + </listitem></itemizedlist> 16.820 + 16.821 + <para id="x_18b">Now to return to the reasons for ordering groups of patches 16.822 + in this way. We would like the lowest patches in the stack to 16.823 + be as stable as possible, so that we will not need to rework 16.824 + higher patches due to changes in context. Putting patches that 16.825 + will never be changed first in the <filename 16.826 + role="special">series</filename> file serves this 16.827 + purpose.</para> 16.828 + 16.829 + <para id="x_18c">We would also like the patches that we know we'll need to 16.830 + modify to be applied on top of a source tree that resembles the 16.831 + upstream tree as closely as possible. This is why we keep 16.832 + accepted patches around for a while.</para> 16.833 + 16.834 + <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> 16.835 + patches float at the end of the <filename 16.836 + role="special">series</filename> file. The backport patches 16.837 + must be applied on top of all other patches, and the <quote>do 16.838 + not ship</quote> patches might as well stay out of harm's 16.839 + way.</para> 16.840 + 16.841 + </sect1> 16.842 + <sect1> 16.843 + <title>Maintaining the patch series</title> 16.844 + 16.845 + <para id="x_18e">In my work, I use a number of guards to control which 16.846 + patches are to be applied.</para> 16.847 + 16.848 + <itemizedlist> 16.849 + <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with 16.850 + <literal>accepted</literal>. I enable this guard most of 16.851 + the time. When I'm applying the patches on top of a tree 16.852 + where the patches are already present, I can turn this patch 16.853 + off, and the patches that follow it will apply 16.854 + cleanly.</para> 16.855 + </listitem> 16.856 + <listitem><para id="x_190">Patches that are <quote>finished</quote>, but 16.857 + not yet submitted, have no guards. If I'm applying the 16.858 + patch stack to a copy of the upstream tree, I don't need to 16.859 + enable any guards in order to get a reasonably safe source 16.860 + tree.</para> 16.861 + </listitem> 16.862 + <listitem><para id="x_191">Those patches that need reworking before being 16.863 + resubmitted are guarded with 16.864 + <literal>rework</literal>.</para> 16.865 + </listitem> 16.866 + <listitem><para id="x_192">For those patches that are still under 16.867 + development, I use <literal>devel</literal>.</para> 16.868 + </listitem> 16.869 + <listitem><para id="x_193">A backport patch may have several guards, one 16.870 + for each version of the kernel to which it applies. For 16.871 + example, a patch that backports a piece of code to 2.6.9 16.872 + will have a <literal>2.6.9</literal> guard.</para> 16.873 + </listitem></itemizedlist> 16.874 + <para id="x_194">This variety of guards gives me considerable flexibility in 16.875 + determining what kind of source tree I want to end up with. For 16.876 + most situations, the selection of appropriate guards is 16.877 + automated during the build process, but I can manually tune the 16.878 + guards to use for less common circumstances.</para> 16.879 + 16.880 + <sect2> 16.881 + <title>The art of writing backport patches</title> 16.882 + 16.883 + <para id="x_195">Using MQ, writing a backport patch is a simple process. 16.884 + All such a patch has to do is modify a piece of code that uses 16.885 + a kernel feature not present in the older version of the 16.886 + kernel, so that the driver continues to work correctly under 16.887 + that older version.</para> 16.888 + 16.889 + <para id="x_196">A useful goal when writing a good backport patch is to 16.890 + make your code look as if it was written for the older version 16.891 + of the kernel you're targeting. The less obtrusive the patch, 16.892 + the easier it will be to understand and maintain. If you're 16.893 + writing a collection of backport patches to avoid the 16.894 + <quote>rat's nest</quote> effect of lots of 16.895 + <literal>#ifdef</literal>s (hunks of source code that are only 16.896 + used conditionally) in your code, don't introduce 16.897 + version-dependent <literal>#ifdef</literal>s into the patches. 16.898 + Instead, write several patches, each of which makes 16.899 + unconditional changes, and control their application using 16.900 + guards.</para> 16.901 + 16.902 + <para id="x_197">There are two reasons to divide backport patches into a 16.903 + distinct group, away from the <quote>regular</quote> patches 16.904 + whose effects they modify. The first is that intermingling the 16.905 + two makes it more difficult to use a tool like the <literal 16.906 + role="hg-ext">patchbomb</literal> extension to automate the 16.907 + process of submitting the patches to an upstream maintainer. 16.908 + The second is that a backport patch could perturb the context 16.909 + in which a subsequent regular patch is applied, making it 16.910 + impossible to apply the regular patch cleanly 16.911 + <emphasis>without</emphasis> the earlier backport patch 16.912 + already being applied.</para> 16.913 + 16.914 + </sect2> 16.915 + </sect1> 16.916 + <sect1> 16.917 + <title>Useful tips for developing with MQ</title> 16.918 + 16.919 + <sect2> 16.920 + <title>Organising patches in directories</title> 16.921 + 16.922 + <para id="x_198">If you're working on a substantial project with MQ, it's 16.923 + not difficult to accumulate a large number of patches. For 16.924 + example, I have one patch repository that contains over 250 16.925 + patches.</para> 16.926 + 16.927 + <para id="x_199">If you can group these patches into separate logical 16.928 + categories, you can if you like store them in different 16.929 + directories; MQ has no problems with patch names that contain 16.930 + path separators.</para> 16.931 + 16.932 + </sect2> 16.933 + <sect2 id="mq-collab:tips:interdiff"> 16.934 + <title>Viewing the history of a patch</title> 16.935 + 16.936 + <para id="x_19a">If you're developing a set of patches over a long time, 16.937 + it's a good idea to maintain them in a repository, as 16.938 + discussed in <xref linkend="sec:mq:repo"/>. If you do 16.939 + so, you'll quickly 16.940 + discover that using the <command role="hg-cmd">hg 16.941 + diff</command> command to look at the history of changes to 16.942 + a patch is unworkable. This is in part because you're looking 16.943 + at the second derivative of the real code (a diff of a diff), 16.944 + but also because MQ adds noise to the process by modifying 16.945 + time stamps and directory names when it updates a 16.946 + patch.</para> 16.947 + 16.948 + <para id="x_19b">However, you can use the <literal 16.949 + role="hg-ext">extdiff</literal> extension, which is bundled 16.950 + with Mercurial, to turn a diff of two versions of a patch into 16.951 + something readable. To do this, you will need a third-party 16.952 + package called <literal role="package">patchutils</literal> 16.953 + <citation>web:patchutils</citation>. This provides a command 16.954 + named <command>interdiff</command>, which shows the 16.955 + differences between two diffs as a diff. Used on two versions 16.956 + of the same diff, it generates a diff that represents the diff 16.957 + from the first to the second version.</para> 16.958 + 16.959 + <para id="x_19c">You can enable the <literal 16.960 + role="hg-ext">extdiff</literal> extension in the usual way, 16.961 + by adding a line to the <literal 16.962 + role="rc-extensions">extensions</literal> section of your 16.963 + <filename role="special">~/.hgrc</filename>.</para> 16.964 + <programlisting>[extensions] 16.965 +extdiff =</programlisting> 16.966 + <para id="x_19d">The <command>interdiff</command> command expects to be 16.967 + passed the names of two files, but the <literal 16.968 + role="hg-ext">extdiff</literal> extension passes the program 16.969 + it runs a pair of directories, each of which can contain an 16.970 + arbitrary number of files. We thus need a small program that 16.971 + will run <command>interdiff</command> on each pair of files in 16.972 + these two directories. This program is available as <filename 16.973 + role="special">hg-interdiff</filename> in the <filename 16.974 + class="directory">examples</filename> directory of the 16.975 + source code repository that accompanies this book. <!-- 16.976 + &example.hg-interdiff; --></para> 16.977 + 16.978 + <para id="x_19e">With the <filename role="special">hg-interdiff</filename> 16.979 + program in your shell's search path, you can run it as 16.980 + follows, from inside an MQ patch directory:</para> 16.981 + <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> 16.982 + <para id="x_19f">Since you'll probably want to use this long-winded command 16.983 + a lot, you can get <literal role="hg-ext">hgext</literal> to 16.984 + make it available as a normal Mercurial command, again by 16.985 + editing your <filename 16.986 + role="special">~/.hgrc</filename>.</para> 16.987 + <programlisting>[extdiff] 16.988 +cmd.interdiff = hg-interdiff</programlisting> 16.989 + <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to 16.990 + make an <literal>interdiff</literal> command available, so you 16.991 + can now shorten the previous invocation of <command 16.992 + role="hg-ext-extdiff">extdiff</command> to something a 16.993 + little more wieldy.</para> 16.994 + <programlisting>hg interdiff -r A:B my-change.patch</programlisting> 16.995 + 16.996 + <note> 16.997 + <para id="x_1a1"> The <command>interdiff</command> command works well 16.998 + only if the underlying files against which versions of a 16.999 + patch are generated remain the same. If you create a patch, 16.1000 + modify the underlying files, and then regenerate the patch, 16.1001 + <command>interdiff</command> may not produce useful 16.1002 + output.</para> 16.1003 + </note> 16.1004 + 16.1005 + <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is 16.1006 + useful for more than merely improving the presentation of MQ 16.1007 + patches. To read more about it, go to <xref 16.1008 + linkend="sec:hgext:extdiff"/>.</para> 16.1009 + 16.1010 + </sect2> 16.1011 + </sect1> 16.1012 </chapter> 16.1013 16.1014 <!-- 16.1015 local variables: 16.1016 sgml-parent-document: ("00book.xml" "book" "chapter") 16.1017 end: 16.1018 ---> 16.1019 \ No newline at end of file 16.1020 +-->
17.1 --- a/fr/ch14-hgext.xml Sat Sep 12 17:58:26 2009 +0200 17.2 +++ b/fr/ch14-hgext.xml Sat Sep 12 17:58:56 2009 +0200 17.3 @@ -1,539 +1,554 @@ 17.4 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 17.5 17.6 -<chapter> 17.7 -<title>Adding functionality with extensions</title> 17.8 -<para>\label{chap:hgext}</para> 17.9 - 17.10 -<para>While the core of Mercurial is quite complete from a functionality 17.11 -standpoint, it's deliberately shorn of fancy features. This approach 17.12 -of preserving simplicity keeps the software easy to deal with for both 17.13 -maintainers and users.</para> 17.14 - 17.15 -<para>However, Mercurial doesn't box you in with an inflexible command set: 17.16 -you can add features to it as <emphasis>extensions</emphasis> (sometimes known as 17.17 -<emphasis>plugins</emphasis>). We've already discussed a few of these extensions in 17.18 -earlier chapters.</para> 17.19 -<itemizedlist> 17.20 -<listitem><para>Section <xref linkend="sec:tour-merge:fetch"/> covers the <literal role="hg-ext">fetch</literal> 17.21 - extension; this combines pulling new changes and merging them with 17.22 - local changes into a single command, <command role="hg-ext-fetch">fetch</command>.</para> 17.23 -</listitem> 17.24 -<listitem><para>In chapter <xref linkend="chap:hook"/>, we covered several extensions that 17.25 - are useful for hook-related functionality: <literal role="hg-ext">acl</literal> adds access 17.26 - control lists; <literal role="hg-ext">bugzilla</literal> adds integration with the Bugzilla 17.27 - bug tracking system; and <literal role="hg-ext">notify</literal> sends notification emails on 17.28 - new changes.</para> 17.29 -</listitem> 17.30 -<listitem><para>The Mercurial Queues patch management extension is so invaluable 17.31 - that it merits two chapters and an appendix all to itself. 17.32 - Chapter <xref linkend="chap:mq"/> covers the basics; 17.33 - chapter <xref linkend="chap:mq-collab"/> discusses advanced topics; and 17.34 - appendix <xref linkend="chap:mqref"/> goes into detail on each command.</para> 17.35 -</listitem></itemizedlist> 17.36 - 17.37 -<para>In this chapter, we'll cover some of the other extensions that are 17.38 -available for Mercurial, and briefly touch on some of the machinery 17.39 -you'll need to know about if you want to write an extension of your 17.40 -own.</para> 17.41 -<itemizedlist> 17.42 -<listitem><para>In section <xref linkend="sec:hgext:inotify"/>, we'll discuss the 17.43 - possibility of <emphasis>huge</emphasis> performance improvements using the 17.44 - <literal role="hg-ext">inotify</literal> extension.</para> 17.45 -</listitem></itemizedlist> 17.46 - 17.47 -<sect1> 17.48 -<title>Improve performance with the <literal role="hg-ext">inotify</literal> extension</title> 17.49 -<para>\label{sec:hgext:inotify} 17.50 -</para> 17.51 - 17.52 -<para>Are you interested in having some of the most common Mercurial 17.53 -operations run as much as a hundred times faster? Read on! 17.54 -</para> 17.55 - 17.56 -<para>Mercurial has great performance under normal circumstances. For 17.57 -example, when you run the <command role="hg-cmd">hg status</command> command, Mercurial has to 17.58 -scan almost every directory and file in your repository so that it can 17.59 -display file status. Many other Mercurial commands need to do the 17.60 -same work behind the scenes; for example, the <command role="hg-cmd">hg diff</command> command 17.61 -uses the status machinery to avoid doing an expensive comparison 17.62 -operation on files that obviously haven't changed. 17.63 -</para> 17.64 - 17.65 -<para>Because obtaining file status is crucial to good performance, the 17.66 -authors of Mercurial have optimised this code to within an inch of its 17.67 -life. However, there's no avoiding the fact that when you run 17.68 -<command role="hg-cmd">hg status</command>, Mercurial is going to have to perform at least one 17.69 -expensive system call for each managed file to determine whether it's 17.70 -changed since the last time Mercurial checked. For a sufficiently 17.71 -large repository, this can take a long time. 17.72 -</para> 17.73 - 17.74 -<para>To put a number on the magnitude of this effect, I created a 17.75 -repository containing 150,000 managed files. I timed <command role="hg-cmd">hg status</command> 17.76 -as taking ten seconds to run, even when <emphasis>none</emphasis> of those files had 17.77 -been modified. 17.78 -</para> 17.79 - 17.80 -<para>Many modern operating systems contain a file notification facility. 17.81 -If a program signs up to an appropriate service, the operating system 17.82 -will notify it every time a file of interest is created, modified, or 17.83 -deleted. On Linux systems, the kernel component that does this is 17.84 -called <literal>inotify</literal>. 17.85 -</para> 17.86 - 17.87 -<para>Mercurial's <literal role="hg-ext">inotify</literal> extension talks to the kernel's 17.88 -<literal>inotify</literal> component to optimise <command role="hg-cmd">hg status</command> commands. The 17.89 -extension has two components. A daemon sits in the background and 17.90 -receives notifications from the <literal>inotify</literal> subsystem. It also 17.91 -listens for connections from a regular Mercurial command. The 17.92 -extension modifies Mercurial's behaviour so that instead of scanning 17.93 -the filesystem, it queries the daemon. Since the daemon has perfect 17.94 -information about the state of the repository, it can respond with a 17.95 -result instantaneously, avoiding the need to scan every directory and 17.96 -file in the repository. 17.97 -</para> 17.98 - 17.99 -<para>Recall the ten seconds that I measured plain Mercurial as taking to 17.100 -run <command role="hg-cmd">hg status</command> on a 150,000 file repository. With the 17.101 -<literal role="hg-ext">inotify</literal> extension enabled, the time dropped to 0.1 seconds, a 17.102 -factor of <emphasis>one hundred</emphasis> faster. 17.103 -</para> 17.104 - 17.105 -<para>Before we continue, please pay attention to some caveats. 17.106 -</para> 17.107 -<itemizedlist> 17.108 -<listitem><para>The <literal role="hg-ext">inotify</literal> extension is Linux-specific. Because it 17.109 - interfaces directly to the Linux kernel's <literal>inotify</literal> 17.110 - subsystem, it does not work on other operating systems. 17.111 -</para> 17.112 -</listitem> 17.113 -<listitem><para>It should work on any Linux distribution that was released after 17.114 - early 2005. Older distributions are likely to have a kernel that 17.115 - lacks <literal>inotify</literal>, or a version of <literal>glibc</literal> that does not 17.116 - have the necessary interfacing support. 17.117 -</para> 17.118 -</listitem> 17.119 -<listitem><para>Not all filesystems are suitable for use with the 17.120 - <literal role="hg-ext">inotify</literal> extension. Network filesystems such as NFS are a 17.121 - non-starter, for example, particularly if you're running Mercurial 17.122 - on several systems, all mounting the same network filesystem. The 17.123 - kernel's <literal>inotify</literal> system has no way of knowing about changes 17.124 - made on another system. Most local filesystems (e.g. ext3, XFS, 17.125 - ReiserFS) should work fine. 17.126 -</para> 17.127 -</listitem></itemizedlist> 17.128 - 17.129 -<para>The <literal role="hg-ext">inotify</literal> extension is not yet shipped with Mercurial as of 17.130 -May 2007, so it's a little more involved to set up than other 17.131 -extensions. But the performance improvement is worth it! 17.132 -</para> 17.133 - 17.134 -<para>The extension currently comes in two parts: a set of patches to the 17.135 -Mercurial source code, and a library of Python bindings to the 17.136 -<literal>inotify</literal> subsystem. 17.137 -</para> 17.138 -<note> 17.139 -<para> There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding libraries. One 17.140 - of them is called <literal>pyinotify</literal>, and is packaged by some Linux 17.141 - distributions as <literal>python-inotify</literal>. This is <emphasis>not</emphasis> the 17.142 - one you'll need, as it is too buggy and inefficient to be practical. 17.143 -</para> 17.144 -</note> 17.145 -<para>To get going, it's best to already have a functioning copy of 17.146 -Mercurial installed. 17.147 -</para> 17.148 -<note> 17.149 -<para> If you follow the instructions below, you'll be <emphasis>replacing</emphasis> and 17.150 - overwriting any existing installation of Mercurial that you might 17.151 - already have, using the latest <quote>bleeding edge</quote> Mercurial code. 17.152 - Don't say you weren't warned! 17.153 -</para> 17.154 -</note> 17.155 -<orderedlist> 17.156 -<listitem><para>Clone the Python <literal>inotify</literal> binding repository. Build and 17.157 - install it. 17.158 -</para> 17.159 -</listitem><programlisting> 17.160 -<listitem><para> hg clone http://hg.kublai.com/python/inotify 17.161 - cd inotify 17.162 - python setup.py build --force 17.163 - sudo python setup.py install --skip-build 17.164 -</para> 17.165 -</listitem></programlisting> 17.166 -</para> 17.167 -</listitem> 17.168 -<listitem><para>Clone the <filename class="directory">crew</filename> Mercurial repository. Clone the 17.169 - <literal role="hg-ext">inotify</literal> patch repository so that Mercurial Queues will be 17.170 - able to apply patches to your cope of the <filename class="directory">crew</filename> repository. 17.171 -</para> 17.172 -</listitem><programlisting> 17.173 -<listitem><para> hg clone http://hg.intevation.org/mercurial/crew 17.174 - hg clone crew inotify 17.175 - hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches 17.176 -</para> 17.177 -</listitem></programlisting> 17.178 -</para> 17.179 -</listitem> 17.180 -<listitem><para>Make sure that you have the Mercurial Queues extension, 17.181 - <literal role="hg-ext">mq</literal>, enabled. If you've never used MQ, read 17.182 - section <xref linkend="sec:mq:start"/> to get started quickly. 17.183 -</para> 17.184 -</listitem> 17.185 -<listitem><para>Go into the <filename class="directory">inotify</filename> repo, and apply all of the 17.186 - <literal role="hg-ext">inotify</literal> patches using the <option role="hg-ext-mq-cmd-qpush-opt">-a</option> option to 17.187 - the <command role="hg-ext-mq">qpush</command> command. 17.188 -</para> 17.189 -</listitem><programlisting> 17.190 -<listitem><para> cd inotify 17.191 - hg qpush -a 17.192 -</para> 17.193 -</listitem></programlisting> 17.194 -<listitem><para> If you get an error message from <command role="hg-ext-mq">qpush</command>, you should not 17.195 - continue. Instead, ask for help. 17.196 -</para> 17.197 -</listitem> 17.198 -<listitem><para>Build and install the patched version of Mercurial. 17.199 -</para> 17.200 -</listitem><programlisting> 17.201 -<listitem><para> python setup.py build --force 17.202 - sudo python setup.py install --skip-build 17.203 -</para> 17.204 -</listitem></programlisting> 17.205 -</orderedlist> 17.206 -<para>Once you've build a suitably patched version of Mercurial, all you 17.207 -need to do to enable the <literal role="hg-ext">inotify</literal> extension is add an entry to 17.208 -your <filename role="special"> /.hgrc</filename>. 17.209 -</para> 17.210 -<programlisting> 17.211 -<para> [extensions] 17.212 - inotify = 17.213 -</para> 17.214 -</programlisting> 17.215 -<para>When the <literal role="hg-ext">inotify</literal> extension is enabled, Mercurial will 17.216 -automatically and transparently start the status daemon the first time 17.217 -you run a command that needs status in a repository. It runs one 17.218 -status daemon per repository. 17.219 -</para> 17.220 - 17.221 -<para>The status daemon is started silently, and runs in the background. If 17.222 -you look at a list of running processes after you've enabled the 17.223 -<literal role="hg-ext">inotify</literal> extension and run a few commands in different 17.224 -repositories, you'll thus see a few <literal>hg</literal> processes sitting 17.225 -around, waiting for updates from the kernel and queries from 17.226 -Mercurial. 17.227 -</para> 17.228 - 17.229 -<para>The first time you run a Mercurial command in a repository when you 17.230 -have the <literal role="hg-ext">inotify</literal> extension enabled, it will run with about the 17.231 -same performance as a normal Mercurial command. This is because the 17.232 -status daemon needs to perform a normal status scan so that it has a 17.233 -baseline against which to apply later updates from the kernel. 17.234 -However, <emphasis>every</emphasis> subsequent command that does any kind of status 17.235 -check should be noticeably faster on repositories of even fairly 17.236 -modest size. Better yet, the bigger your repository is, the greater a 17.237 -performance advantage you'll see. The <literal role="hg-ext">inotify</literal> daemon makes 17.238 -status operations almost instantaneous on repositories of all sizes! 17.239 -</para> 17.240 - 17.241 -<para>If you like, you can manually start a status daemon using the 17.242 -<command role="hg-ext-inotify">inserve</command> command. This gives you slightly finer 17.243 -control over how the daemon ought to run. This command will of course 17.244 -only be available when the <literal role="hg-ext">inotify</literal> extension is enabled. 17.245 -</para> 17.246 - 17.247 -<para>When you're using the <literal role="hg-ext">inotify</literal> extension, you should notice 17.248 -<emphasis>no difference at all</emphasis> in Mercurial's behaviour, with the sole 17.249 -exception of status-related commands running a whole lot faster than 17.250 -they used to. You should specifically expect that commands will not 17.251 -print different output; neither should they give different results. 17.252 -If either of these situations occurs, please report a bug. 17.253 -</para> 17.254 - 17.255 -</sect1> 17.256 -<sect1> 17.257 -<title>Flexible diff support with the <literal role="hg-ext">extdiff</literal> extension</title> 17.258 -<para>\label{sec:hgext:extdiff} 17.259 -</para> 17.260 - 17.261 -<para>Mercurial's built-in <command role="hg-cmd">hg diff</command> command outputs plaintext unified 17.262 -diffs. 17.263 -<!-- &interaction.extdiff.diff; --> 17.264 -If you would like to use an external tool to display modifications, 17.265 -you'll want to use the <literal role="hg-ext">extdiff</literal> extension. This will let you 17.266 -use, for example, a graphical diff tool. 17.267 -</para> 17.268 - 17.269 -<para>The <literal role="hg-ext">extdiff</literal> extension is bundled with Mercurial, so it's easy 17.270 -to set up. In the <literal role="rc-extensions">extensions</literal> section of your <filename role="special"> /.hgrc</filename>, 17.271 -simply add a one-line entry to enable the extension. 17.272 -</para> 17.273 -<programlisting> 17.274 -<para> [extensions] 17.275 - extdiff = 17.276 -</para> 17.277 -</programlisting> 17.278 -<para>This introduces a command named <command role="hg-ext-extdiff">extdiff</command>, which by 17.279 -default uses your system's <command>diff</command> command to generate a 17.280 -unified diff in the same form as the built-in <command role="hg-cmd">hg diff</command> command. 17.281 -<!-- &interaction.extdiff.extdiff; --> 17.282 -The result won't be exactly the same as with the built-in <command role="hg-cmd">hg diff</command> 17.283 -variations, because the output of <command>diff</command> varies from one 17.284 -system to another, even when passed the same options. 17.285 -</para> 17.286 - 17.287 -<para>As the <quote><literal>making snapshot</literal></quote> lines of output above imply, the 17.288 -<command role="hg-ext-extdiff">extdiff</command> command works by creating two snapshots of 17.289 -your source tree. The first snapshot is of the source revision; the 17.290 -second, of the target revision or working directory. The 17.291 -<command role="hg-ext-extdiff">extdiff</command> command generates these snapshots in a 17.292 -temporary directory, passes the name of each directory to an external 17.293 -diff viewer, then deletes the temporary directory. For efficiency, it 17.294 -only snapshots the directories and files that have changed between the 17.295 -two revisions. 17.296 -</para> 17.297 - 17.298 -<para>Snapshot directory names have the same base name as your repository. 17.299 -If your repository path is <filename class="directory">/quux/bar/foo</filename>, then <filename class="directory">foo</filename> 17.300 -will be the name of each snapshot directory. Each snapshot directory 17.301 -name has its changeset ID appended, if appropriate. If a snapshot is 17.302 -of revision <literal>a631aca1083f</literal>, the directory will be named 17.303 -<filename class="directory">foo.a631aca1083f</filename>. A snapshot of the working directory won't 17.304 -have a changeset ID appended, so it would just be <filename class="directory">foo</filename> in 17.305 -this example. To see what this looks like in practice, look again at 17.306 -the <command role="hg-ext-extdiff">extdiff</command> example above. Notice that the diff has 17.307 -the snapshot directory names embedded in its header. 17.308 -</para> 17.309 - 17.310 -<para>The <command role="hg-ext-extdiff">extdiff</command> command accepts two important options. 17.311 -The <option role="hg-ext-extdiff-cmd-extdiff-opt">-p</option> option lets you choose a program to 17.312 -view differences with, instead of <command>diff</command>. With the 17.313 -<option role="hg-ext-extdiff-cmd-extdiff-opt">-o</option> option, you can change the options that 17.314 -<command role="hg-ext-extdiff">extdiff</command> passes to the program (by default, these 17.315 -options are <quote><literal>-Npru</literal></quote>, which only make sense if you're 17.316 -running <command>diff</command>). In other respects, the 17.317 -<command role="hg-ext-extdiff">extdiff</command> command acts similarly to the built-in 17.318 -<command role="hg-cmd">hg diff</command> command: you use the same option names, syntax, and 17.319 -arguments to specify the revisions you want, the files you want, and 17.320 -so on. 17.321 -</para> 17.322 - 17.323 -<para>As an example, here's how to run the normal system <command>diff</command> 17.324 -command, getting it to generate context diffs (using the 17.325 -<option role="cmd-opt-diff">-c</option> option) instead of unified diffs, and five lines of 17.326 -context instead of the default three (passing <literal>5</literal> as the 17.327 -argument to the <option role="cmd-opt-diff">-C</option> option). 17.328 -<!-- &interaction.extdiff.extdiff-ctx; --> 17.329 -</para> 17.330 - 17.331 -<para>Launching a visual diff tool is just as easy. Here's how to launch 17.332 -the <command>kdiff3</command> viewer. 17.333 -</para> 17.334 -<programlisting> 17.335 -<para> hg extdiff -p kdiff3 -o </quote> 17.336 -</para> 17.337 -</programlisting> 17.338 - 17.339 -<para>If your diff viewing command can't deal with directories, you can 17.340 -easily work around this with a little scripting. For an example of 17.341 -such scripting in action with the <literal role="hg-ext">mq</literal> extension and the 17.342 -<command>interdiff</command> command, see 17.343 -section <xref linkend="mq-collab:tips:interdiff"/>. 17.344 -</para> 17.345 - 17.346 -<sect2> 17.347 -<title>Defining command aliases</title> 17.348 - 17.349 -<para>It can be cumbersome to remember the options to both the 17.350 -<command role="hg-ext-extdiff">extdiff</command> command and the diff viewer you want to use, 17.351 -so the <literal role="hg-ext">extdiff</literal> extension lets you define <emphasis>new</emphasis> commands 17.352 -that will invoke your diff viewer with exactly the right options. 17.353 -</para> 17.354 - 17.355 -<para>All you need to do is edit your <filename role="special"> /.hgrc</filename>, and add a section named 17.356 -<literal role="rc-extdiff">extdiff</literal>. Inside this section, you can define multiple 17.357 -commands. Here's how to add a <literal>kdiff3</literal> command. Once you've 17.358 -defined this, you can type <quote><literal>hg kdiff3</literal></quote> and the 17.359 -<literal role="hg-ext">extdiff</literal> extension will run <command>kdiff3</command> for you. 17.360 -</para> 17.361 -<programlisting> 17.362 -<para> [extdiff] 17.363 - cmd.kdiff3 = 17.364 -</para> 17.365 -</programlisting> 17.366 -<para>If you leave the right hand side of the definition empty, as above, 17.367 -the <literal role="hg-ext">extdiff</literal> extension uses the name of the command you defined 17.368 -as the name of the external program to run. But these names don't 17.369 -have to be the same. Here, we define a command named <quote>\texttt{hg 17.370 - wibble}</quote>, which runs <command>kdiff3</command>. 17.371 -</para> 17.372 -<programlisting> 17.373 -<para> [extdiff] 17.374 - cmd.wibble = kdiff3 17.375 -</para> 17.376 -</programlisting> 17.377 - 17.378 -<para>You can also specify the default options that you want to invoke your 17.379 -diff viewing program with. The prefix to use is <quote><literal>opts.</literal></quote>, 17.380 -followed by the name of the command to which the options apply. This 17.381 -example defines a <quote><literal>hg vimdiff</literal></quote> command that runs the 17.382 -<command>vim</command> editor's <literal>DirDiff</literal> extension. 17.383 -</para> 17.384 -<programlisting> 17.385 -<para> [extdiff] 17.386 - cmd.vimdiff = vim 17.387 - opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)' 17.388 -</para> 17.389 -</programlisting> 17.390 - 17.391 -</sect2> 17.392 -</sect1> 17.393 -<sect1> 17.394 -<title>Cherrypicking changes with the <literal role="hg-ext">transplant</literal> extension</title> 17.395 -<para>\label{sec:hgext:transplant} 17.396 -</para> 17.397 - 17.398 -<para>Need to have a long chat with Brendan about this. 17.399 -</para> 17.400 - 17.401 -</sect1> 17.402 -<sect1> 17.403 -<title>Send changes via email with the <literal role="hg-ext">patchbomb</literal> extension</title> 17.404 -<para>\label{sec:hgext:patchbomb} 17.405 -</para> 17.406 - 17.407 -<para>Many projects have a culture of <quote>change review</quote>, in which people 17.408 -send their modifications to a mailing list for others to read and 17.409 -comment on before they commit the final version to a shared 17.410 -repository. Some projects have people who act as gatekeepers; they 17.411 -apply changes from other people to a repository to which those others 17.412 -don't have access. 17.413 -</para> 17.414 - 17.415 -<para>Mercurial makes it easy to send changes over email for review or 17.416 -application, via its <literal role="hg-ext">patchbomb</literal> extension. The extension is so 17.417 -namd because changes are formatted as patches, and it's usual to send 17.418 -one changeset per email message. Sending a long series of changes by 17.419 -email is thus much like <quote>bombing</quote> the recipient's inbox, hence 17.420 -<quote>patchbomb</quote>. 17.421 -</para> 17.422 - 17.423 -<para>As usual, the basic configuration of the <literal role="hg-ext">patchbomb</literal> extension 17.424 -takes just one or two lines in your <filename role="special"> /.hgrc</filename>. 17.425 -</para> 17.426 -<programlisting> 17.427 -<para> [extensions] 17.428 - patchbomb = 17.429 -</para> 17.430 -</programlisting> 17.431 -<para>Once you've enabled the extension, you will have a new command 17.432 -available, named <command role="hg-ext-patchbomb">email</command>. 17.433 -</para> 17.434 - 17.435 -<para>The safest and best way to invoke the <command role="hg-ext-patchbomb">email</command> 17.436 -command is to <emphasis>always</emphasis> run it first with the 17.437 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option. This will show you what the 17.438 -command <emphasis>would</emphasis> send, without actually sending anything. Once 17.439 -you've had a quick glance over the changes and verified that you are 17.440 -sending the right ones, you can rerun the same command, with the 17.441 -<option role="hg-ext-patchbomb-cmd-email-opt">-n</option> option removed. 17.442 -</para> 17.443 - 17.444 -<para>The <command role="hg-ext-patchbomb">email</command> command accepts the same kind of 17.445 -revision syntax as every other Mercurial command. For example, this 17.446 -command will send every revision between 7 and <literal>tip</literal>, 17.447 -inclusive. 17.448 -</para> 17.449 -<programlisting> 17.450 -<para> hg email -n 7:tip 17.451 -</para> 17.452 -</programlisting> 17.453 -<para>You can also specify a <emphasis>repository</emphasis> to compare with. If you 17.454 -provide a repository but no revisions, the <command role="hg-ext-patchbomb">email</command> 17.455 -command will send all revisions in the local repository that are not 17.456 -present in the remote repository. If you additionally specify 17.457 -revisions or a branch name (the latter using the 17.458 -<option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option), this will constrain the 17.459 -revisions sent. 17.460 -</para> 17.461 - 17.462 -<para>It's perfectly safe to run the <command role="hg-ext-patchbomb">email</command> command 17.463 -without the names of the people you want to send to: if you do this, 17.464 -it will just prompt you for those values interactively. (If you're 17.465 -using a Linux or Unix-like system, you should have enhanced 17.466 -<literal>readline</literal>-style editing capabilities when entering those 17.467 -headers, too, which is useful.) 17.468 -</para> 17.469 - 17.470 -<para>When you are sending just one revision, the <command role="hg-ext-patchbomb">email</command> 17.471 -command will by default use the first line of the changeset 17.472 -description as the subject of the single email message it sends. 17.473 -</para> 17.474 - 17.475 -<para>If you send multiple revisions, the <command role="hg-ext-patchbomb">email</command> command 17.476 -will usually send one message per changeset. It will preface the 17.477 -series with an introductory message, in which you should describe the 17.478 -purpose of the series of changes you're sending. 17.479 -</para> 17.480 - 17.481 -<sect2> 17.482 -<title>Changing the behaviour of patchbombs</title> 17.483 - 17.484 -<para>Not every project has exactly the same conventions for sending changes 17.485 -in email; the <literal role="hg-ext">patchbomb</literal> extension tries to accommodate a 17.486 -number of variations through command line options. 17.487 -</para> 17.488 -<itemizedlist> 17.489 -<listitem><para>You can write a subject for the introductory message on the 17.490 - command line using the <option role="hg-ext-patchbomb-cmd-email-opt">-s</option> option. This 17.491 - takes one argument, the text of the subject to use. 17.492 -</para> 17.493 -</listitem> 17.494 -<listitem><para>To change the email address from which the messages originate, 17.495 - use the <option role="hg-ext-patchbomb-cmd-email-opt">-f</option> option. This takes one 17.496 - argument, the email address to use. 17.497 -</para> 17.498 -</listitem> 17.499 -<listitem><para>The default behaviour is to send unified diffs (see 17.500 - section <xref linkend="sec:mq:patch"/> for a description of the format), one per 17.501 - message. You can send a binary bundle instead with the 17.502 - <option role="hg-ext-patchbomb-cmd-email-opt">-b</option> option. 17.503 -</para> 17.504 -</listitem> 17.505 -<listitem><para>Unified diffs are normally prefaced with a metadata header. You 17.506 - can omit this, and send unadorned diffs, with the 17.507 - <option role="hg-ext-patchbomb-cmd-email-opt">--plain</option> option. 17.508 -</para> 17.509 -</listitem> 17.510 -<listitem><para>Diffs are normally sent <quote>inline</quote>, in the same body part as the 17.511 - description of a patch. This makes it easiest for the largest 17.512 - number of readers to quote and respond to parts of a diff, as some 17.513 - mail clients will only quote the first MIME body part in a message. 17.514 - If you'd prefer to send the description and the diff in separate 17.515 - body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">-a</option> option. 17.516 -</para> 17.517 -</listitem> 17.518 -<listitem><para>Instead of sending mail messages, you can write them to an 17.519 - <literal>mbox</literal>-format mail folder using the 17.520 - <option role="hg-ext-patchbomb-cmd-email-opt">-m</option> option. That option takes one 17.521 - argument, the name of the file to write to. 17.522 -</para> 17.523 -</listitem> 17.524 -<listitem><para>If you would like to add a <command>diffstat</command>-format summary to 17.525 - each patch, and one to the introductory message, use the 17.526 - <option role="hg-ext-patchbomb-cmd-email-opt">-d</option> option. The <command>diffstat</command> 17.527 - command displays a table containing the name of each file patched, 17.528 - the number of lines affected, and a histogram showing how much each 17.529 - file is modified. This gives readers a qualitative glance at how 17.530 - complex a patch is. 17.531 -</para> 17.532 -</listitem></itemizedlist> 17.533 - 17.534 -</sect2> 17.535 -</sect1> 17.536 +<chapter id="chap:hgext"> 17.537 + <?dbhtml filename="adding-functionality-with-extensions.html"?> 17.538 + <title>Adding functionality with extensions</title> 17.539 + 17.540 + <para id="x_4fe">While the core of Mercurial is quite complete from a 17.541 + functionality standpoint, it's deliberately shorn of fancy 17.542 + features. This approach of preserving simplicity keeps the 17.543 + software easy to deal with for both maintainers and users.</para> 17.544 + 17.545 + <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 17.546 + command set: you can add features to it as 17.547 + <emphasis>extensions</emphasis> (sometimes known as 17.548 + <emphasis>plugins</emphasis>). We've already discussed a few of 17.549 + these extensions in earlier chapters.</para> 17.550 + <itemizedlist> 17.551 + <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/> 17.552 + covers the <literal role="hg-ext">fetch</literal> extension; 17.553 + this combines pulling new changes and merging them with local 17.554 + changes into a single command, <command 17.555 + role="hg-ext-fetch">fetch</command>.</para> 17.556 + </listitem> 17.557 + <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered 17.558 + several extensions that are useful for hook-related 17.559 + functionality: <literal role="hg-ext">acl</literal> adds 17.560 + access control lists; <literal 17.561 + role="hg-ext">bugzilla</literal> adds integration with the 17.562 + Bugzilla bug tracking system; and <literal 17.563 + role="hg-ext">notify</literal> sends notification emails on 17.564 + new changes.</para> 17.565 + </listitem> 17.566 + <listitem><para id="x_502">The Mercurial Queues patch management extension is 17.567 + so invaluable that it merits two chapters and an appendix all 17.568 + to itself. <xref linkend="chap:mq"/> covers the 17.569 + basics; <xref 17.570 + linkend="chap:mq-collab"/> discusses advanced topics; 17.571 + and <xref linkend="chap:mqref"/> goes into detail on 17.572 + each 17.573 + command.</para> 17.574 + </listitem></itemizedlist> 17.575 + 17.576 + <para id="x_503">In this chapter, we'll cover some of the other extensions that 17.577 + are available for Mercurial, and briefly touch on some of the 17.578 + machinery you'll need to know about if you want to write an 17.579 + extension of your own.</para> 17.580 + <itemizedlist> 17.581 + <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>, 17.582 + we'll discuss the possibility of <emphasis>huge</emphasis> 17.583 + performance improvements using the <literal 17.584 + role="hg-ext">inotify</literal> extension.</para> 17.585 + </listitem></itemizedlist> 17.586 + 17.587 + <sect1 id="sec:hgext:inotify"> 17.588 + <title>Improve performance with the <literal 17.589 + role="hg-ext">inotify</literal> extension</title> 17.590 + 17.591 + <para id="x_505">Are you interested in having some of the most common 17.592 + Mercurial operations run as much as a hundred times faster? 17.593 + Read on!</para> 17.594 + 17.595 + <para id="x_506">Mercurial has great performance under normal circumstances. 17.596 + For example, when you run the <command role="hg-cmd">hg 17.597 + status</command> command, Mercurial has to scan almost every 17.598 + directory and file in your repository so that it can display 17.599 + file status. Many other Mercurial commands need to do the same 17.600 + work behind the scenes; for example, the <command 17.601 + role="hg-cmd">hg diff</command> command uses the status 17.602 + machinery to avoid doing an expensive comparison operation on 17.603 + files that obviously haven't changed.</para> 17.604 + 17.605 + <para id="x_507">Because obtaining file status is crucial to good 17.606 + performance, the authors of Mercurial have optimised this code 17.607 + to within an inch of its life. However, there's no avoiding the 17.608 + fact that when you run <command role="hg-cmd">hg 17.609 + status</command>, Mercurial is going to have to perform at 17.610 + least one expensive system call for each managed file to 17.611 + determine whether it's changed since the last time Mercurial 17.612 + checked. For a sufficiently large repository, this can take a 17.613 + long time.</para> 17.614 + 17.615 + <para id="x_508">To put a number on the magnitude of this effect, I created a 17.616 + repository containing 150,000 managed files. I timed <command 17.617 + role="hg-cmd">hg status</command> as taking ten seconds to 17.618 + run, even when <emphasis>none</emphasis> of those files had been 17.619 + modified.</para> 17.620 + 17.621 + <para id="x_509">Many modern operating systems contain a file notification 17.622 + facility. If a program signs up to an appropriate service, the 17.623 + operating system will notify it every time a file of interest is 17.624 + created, modified, or deleted. On Linux systems, the kernel 17.625 + component that does this is called 17.626 + <literal>inotify</literal>.</para> 17.627 + 17.628 + <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 17.629 + extension talks to the kernel's <literal>inotify</literal> 17.630 + component to optimise <command role="hg-cmd">hg status</command> 17.631 + commands. The extension has two components. A daemon sits in 17.632 + the background and receives notifications from the 17.633 + <literal>inotify</literal> subsystem. It also listens for 17.634 + connections from a regular Mercurial command. The extension 17.635 + modifies Mercurial's behavior so that instead of scanning the 17.636 + filesystem, it queries the daemon. Since the daemon has perfect 17.637 + information about the state of the repository, it can respond 17.638 + with a result instantaneously, avoiding the need to scan every 17.639 + directory and file in the repository.</para> 17.640 + 17.641 + <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 17.642 + taking to run <command role="hg-cmd">hg status</command> on a 17.643 + 150,000 file repository. With the <literal 17.644 + role="hg-ext">inotify</literal> extension enabled, the time 17.645 + dropped to 0.1 seconds, a factor of <emphasis>one 17.646 + hundred</emphasis> faster.</para> 17.647 + 17.648 + <para id="x_50c">Before we continue, please pay attention to some 17.649 + caveats.</para> 17.650 + <itemizedlist> 17.651 + <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 17.652 + extension is Linux-specific. Because it interfaces directly 17.653 + to the Linux kernel's <literal>inotify</literal> subsystem, 17.654 + it does not work on other operating systems.</para> 17.655 + </listitem> 17.656 + <listitem><para id="x_50e">It should work on any Linux distribution that 17.657 + was released after early 2005. Older distributions are 17.658 + likely to have a kernel that lacks 17.659 + <literal>inotify</literal>, or a version of 17.660 + <literal>glibc</literal> that does not have the necessary 17.661 + interfacing support.</para> 17.662 + </listitem> 17.663 + <listitem><para id="x_50f">Not all filesystems are suitable for use with 17.664 + the <literal role="hg-ext">inotify</literal> extension. 17.665 + Network filesystems such as NFS are a non-starter, for 17.666 + example, particularly if you're running Mercurial on several 17.667 + systems, all mounting the same network filesystem. The 17.668 + kernel's <literal>inotify</literal> system has no way of 17.669 + knowing about changes made on another system. Most local 17.670 + filesystems (e.g. ext3, XFS, ReiserFS) should work 17.671 + fine.</para> 17.672 + </listitem></itemizedlist> 17.673 + 17.674 + <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 17.675 + not yet shipped with Mercurial as of May 2007, so it's a little 17.676 + more involved to set up than other extensions. But the 17.677 + performance improvement is worth it!</para> 17.678 + 17.679 + <para id="x_511">The extension currently comes in two parts: a set of patches 17.680 + to the Mercurial source code, and a library of Python bindings 17.681 + to the <literal>inotify</literal> subsystem.</para> 17.682 + <note> 17.683 + <para id="x_512"> There are <emphasis>two</emphasis> Python 17.684 + <literal>inotify</literal> binding libraries. One of them is 17.685 + called <literal>pyinotify</literal>, and is packaged by some 17.686 + Linux distributions as <literal>python-inotify</literal>. 17.687 + This is <emphasis>not</emphasis> the one you'll need, as it is 17.688 + too buggy and inefficient to be practical.</para> 17.689 + </note> 17.690 + <para id="x_513">To get going, it's best to already have a functioning copy 17.691 + of Mercurial installed.</para> 17.692 + <note> 17.693 + <para id="x_514"> If you follow the instructions below, you'll be 17.694 + <emphasis>replacing</emphasis> and overwriting any existing 17.695 + installation of Mercurial that you might already have, using 17.696 + the latest <quote>bleeding edge</quote> Mercurial code. Don't 17.697 + say you weren't warned!</para> 17.698 + </note> 17.699 + <orderedlist> 17.700 + <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 17.701 + binding repository. Build and install it.</para> 17.702 + <programlisting>hg clone http://hg.kublai.com/python/inotify 17.703 +cd inotify 17.704 +python setup.py build --force 17.705 +sudo python setup.py install --skip-build</programlisting> 17.706 + </listitem> 17.707 + <listitem><para id="x_516">Clone the <filename 17.708 + class="directory">crew</filename> Mercurial repository. 17.709 + Clone the <literal role="hg-ext">inotify</literal> patch 17.710 + repository so that Mercurial Queues will be able to apply 17.711 + patches to your cope of the <filename 17.712 + class="directory">crew</filename> repository.</para> 17.713 + <programlisting>hg clone http://hg.intevation.org/mercurial/crew 17.714 +hg clone crew inotify 17.715 +hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 17.716 + </listitem> 17.717 + <listitem><para id="x_517">Make sure that you have the Mercurial Queues 17.718 + extension, <literal role="hg-ext">mq</literal>, enabled. If 17.719 + you've never used MQ, read <xref 17.720 + linkend="sec:mq:start"/> to get started 17.721 + quickly.</para> 17.722 + </listitem> 17.723 + <listitem><para id="x_518">Go into the <filename 17.724 + class="directory">inotify</filename> repo, and apply all 17.725 + of the <literal role="hg-ext">inotify</literal> patches 17.726 + using the <option role="hg-ext-mq-cmd-qpush-opt">hg 17.727 + -a</option> option to the <command 17.728 + role="hg-ext-mq">qpush</command> command.</para> 17.729 + <programlisting>cd inotify 17.730 +hg qpush -a</programlisting> 17.731 + </listitem> 17.732 + <listitem><para id="x_519"> If you get an error message from <command 17.733 + role="hg-ext-mq">qpush</command>, you should not continue. 17.734 + Instead, ask for help.</para> 17.735 + </listitem> 17.736 + <listitem><para id="x_51a">Build and install the patched version of 17.737 + Mercurial.</para> 17.738 + <programlisting>python setup.py build --force 17.739 +sudo python setup.py install --skip-build</programlisting> 17.740 + </listitem> 17.741 + </orderedlist> 17.742 + <para id="x_51b">Once you've build a suitably patched version of Mercurial, 17.743 + all you need to do to enable the <literal 17.744 + role="hg-ext">inotify</literal> extension is add an entry to 17.745 + your <filename role="special">~/.hgrc</filename>.</para> 17.746 + <programlisting>[extensions] inotify =</programlisting> 17.747 + <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 17.748 + is enabled, Mercurial will automatically and transparently start 17.749 + the status daemon the first time you run a command that needs 17.750 + status in a repository. It runs one status daemon per 17.751 + repository.</para> 17.752 + 17.753 + <para id="x_51d">The status daemon is started silently, and runs in the 17.754 + background. If you look at a list of running processes after 17.755 + you've enabled the <literal role="hg-ext">inotify</literal> 17.756 + extension and run a few commands in different repositories, 17.757 + you'll thus see a few <literal>hg</literal> processes sitting 17.758 + around, waiting for updates from the kernel and queries from 17.759 + Mercurial.</para> 17.760 + 17.761 + <para id="x_51e">The first time you run a Mercurial command in a repository 17.762 + when you have the <literal role="hg-ext">inotify</literal> 17.763 + extension enabled, it will run with about the same performance 17.764 + as a normal Mercurial command. This is because the status 17.765 + daemon needs to perform a normal status scan so that it has a 17.766 + baseline against which to apply later updates from the kernel. 17.767 + However, <emphasis>every</emphasis> subsequent command that does 17.768 + any kind of status check should be noticeably faster on 17.769 + repositories of even fairly modest size. Better yet, the bigger 17.770 + your repository is, the greater a performance advantage you'll 17.771 + see. The <literal role="hg-ext">inotify</literal> daemon makes 17.772 + status operations almost instantaneous on repositories of all 17.773 + sizes!</para> 17.774 + 17.775 + <para id="x_51f">If you like, you can manually start a status daemon using 17.776 + the <command role="hg-ext-inotify">inserve</command> command. 17.777 + This gives you slightly finer control over how the daemon ought 17.778 + to run. This command will of course only be available when the 17.779 + <literal role="hg-ext">inotify</literal> extension is 17.780 + enabled.</para> 17.781 + 17.782 + <para id="x_520">When you're using the <literal 17.783 + role="hg-ext">inotify</literal> extension, you should notice 17.784 + <emphasis>no difference at all</emphasis> in Mercurial's 17.785 + behavior, with the sole exception of status-related commands 17.786 + running a whole lot faster than they used to. You should 17.787 + specifically expect that commands will not print different 17.788 + output; neither should they give different results. If either of 17.789 + these situations occurs, please report a bug.</para> 17.790 + 17.791 + </sect1> 17.792 + <sect1 id="sec:hgext:extdiff"> 17.793 + <title>Flexible diff support with the <literal 17.794 + role="hg-ext">extdiff</literal> extension</title> 17.795 + 17.796 + <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 17.797 + diff</command> command outputs plaintext unified diffs.</para> 17.798 + 17.799 + &interaction.extdiff.diff; 17.800 + 17.801 + <para id="x_522">If you would like to use an external tool to display 17.802 + modifications, you'll want to use the <literal 17.803 + role="hg-ext">extdiff</literal> extension. This will let you 17.804 + use, for example, a graphical diff tool.</para> 17.805 + 17.806 + <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 17.807 + bundled with Mercurial, so it's easy to set up. In the <literal 17.808 + role="rc-extensions">extensions</literal> section of your 17.809 + <filename role="special">~/.hgrc</filename>, simply add a 17.810 + one-line entry to enable the extension.</para> 17.811 + <programlisting>[extensions] 17.812 +extdiff =</programlisting> 17.813 + <para id="x_524">This introduces a command named <command 17.814 + role="hg-ext-extdiff">extdiff</command>, which by default uses 17.815 + your system's <command>diff</command> command to generate a 17.816 + unified diff in the same form as the built-in <command 17.817 + role="hg-cmd">hg diff</command> command.</para> 17.818 + 17.819 + &interaction.extdiff.extdiff; 17.820 + 17.821 + <para id="x_525">The result won't be exactly the same as with the built-in 17.822 + <command role="hg-cmd">hg diff</command> variations, because the 17.823 + output of <command>diff</command> varies from one system to 17.824 + another, even when passed the same options.</para> 17.825 + 17.826 + <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 17.827 + lines of output above imply, the <command 17.828 + role="hg-ext-extdiff">extdiff</command> command works by 17.829 + creating two snapshots of your source tree. The first snapshot 17.830 + is of the source revision; the second, of the target revision or 17.831 + working directory. The <command 17.832 + role="hg-ext-extdiff">extdiff</command> command generates 17.833 + these snapshots in a temporary directory, passes the name of 17.834 + each directory to an external diff viewer, then deletes the 17.835 + temporary directory. For efficiency, it only snapshots the 17.836 + directories and files that have changed between the two 17.837 + revisions.</para> 17.838 + 17.839 + <para id="x_527">Snapshot directory names have the same base name as your 17.840 + repository. If your repository path is <filename 17.841 + class="directory">/quux/bar/foo</filename>, then <filename 17.842 + class="directory">foo</filename> will be the name of each 17.843 + snapshot directory. Each snapshot directory name has its 17.844 + changeset ID appended, if appropriate. If a snapshot is of 17.845 + revision <literal>a631aca1083f</literal>, the directory will be 17.846 + named <filename class="directory">foo.a631aca1083f</filename>. 17.847 + A snapshot of the working directory won't have a changeset ID 17.848 + appended, so it would just be <filename 17.849 + class="directory">foo</filename> in this example. To see what 17.850 + this looks like in practice, look again at the <command 17.851 + role="hg-ext-extdiff">extdiff</command> example above. Notice 17.852 + that the diff has the snapshot directory names embedded in its 17.853 + header.</para> 17.854 + 17.855 + <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 17.856 + accepts two important options. The <option 17.857 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 17.858 + lets you choose a program to view differences with, instead of 17.859 + <command>diff</command>. With the <option 17.860 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, 17.861 + you can change the options that <command 17.862 + role="hg-ext-extdiff">extdiff</command> passes to the program 17.863 + (by default, these options are 17.864 + <quote><literal>-Npru</literal></quote>, which only make sense 17.865 + if you're running <command>diff</command>). In other respects, 17.866 + the <command role="hg-ext-extdiff">extdiff</command> command 17.867 + acts similarly to the built-in <command role="hg-cmd">hg 17.868 + diff</command> command: you use the same option names, syntax, 17.869 + and arguments to specify the revisions you want, the files you 17.870 + want, and so on.</para> 17.871 + 17.872 + <para id="x_529">As an example, here's how to run the normal system 17.873 + <command>diff</command> command, getting it to generate context 17.874 + diffs (using the <option role="cmd-opt-diff">-c</option> option) 17.875 + instead of unified diffs, and five lines of context instead of 17.876 + the default three (passing <literal>5</literal> as the argument 17.877 + to the <option role="cmd-opt-diff">-C</option> option).</para> 17.878 + 17.879 + &interaction.extdiff.extdiff-ctx; 17.880 + 17.881 + <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 17.882 + launch the <command>kdiff3</command> viewer.</para> 17.883 + <programlisting>hg extdiff -p kdiff3 -o</programlisting> 17.884 + 17.885 + <para id="x_52b">If your diff viewing command can't deal with directories, 17.886 + you can easily work around this with a little scripting. For an 17.887 + example of such scripting in action with the <literal 17.888 + role="hg-ext">mq</literal> extension and the 17.889 + <command>interdiff</command> command, see <xref 17.890 + linkend="mq-collab:tips:interdiff"/>.</para> 17.891 + 17.892 + <sect2> 17.893 + <title>Defining command aliases</title> 17.894 + 17.895 + <para id="x_52c">It can be cumbersome to remember the options to both the 17.896 + <command role="hg-ext-extdiff">extdiff</command> command and 17.897 + the diff viewer you want to use, so the <literal 17.898 + role="hg-ext">extdiff</literal> extension lets you define 17.899 + <emphasis>new</emphasis> commands that will invoke your diff 17.900 + viewer with exactly the right options.</para> 17.901 + 17.902 + <para id="x_52d">All you need to do is edit your <filename 17.903 + role="special">~/.hgrc</filename>, and add a section named 17.904 + <literal role="rc-extdiff">extdiff</literal>. Inside this 17.905 + section, you can define multiple commands. Here's how to add 17.906 + a <literal>kdiff3</literal> command. Once you've defined 17.907 + this, you can type <quote><literal>hg kdiff3</literal></quote> 17.908 + and the <literal role="hg-ext">extdiff</literal> extension 17.909 + will run <command>kdiff3</command> for you.</para> 17.910 + <programlisting>[extdiff] 17.911 +cmd.kdiff3 =</programlisting> 17.912 + <para id="x_52e">If you leave the right hand side of the definition empty, 17.913 + as above, the <literal role="hg-ext">extdiff</literal> 17.914 + extension uses the name of the command you defined as the name 17.915 + of the external program to run. But these names don't have to 17.916 + be the same. Here, we define a command named 17.917 + <quote><literal>hg wibble</literal></quote>, which runs 17.918 + <command>kdiff3</command>.</para> 17.919 + <programlisting>[extdiff] 17.920 + cmd.wibble = kdiff3</programlisting> 17.921 + 17.922 + <para id="x_52f">You can also specify the default options that you want to 17.923 + invoke your diff viewing program with. The prefix to use is 17.924 + <quote><literal>opts.</literal></quote>, followed by the name 17.925 + of the command to which the options apply. This example 17.926 + defines a <quote><literal>hg vimdiff</literal></quote> command 17.927 + that runs the <command>vim</command> editor's 17.928 + <literal>DirDiff</literal> extension.</para> 17.929 + <programlisting>[extdiff] 17.930 + cmd.vimdiff = vim 17.931 +opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> 17.932 + 17.933 + </sect2> 17.934 + </sect1> 17.935 + <sect1 id="sec:hgext:transplant"> 17.936 + <title>Cherrypicking changes with the <literal 17.937 + role="hg-ext">transplant</literal> extension</title> 17.938 + 17.939 + <para id="x_530">Need to have a long chat with Brendan about this.</para> 17.940 + 17.941 + </sect1> 17.942 + <sect1 id="sec:hgext:patchbomb"> 17.943 + <title>Send changes via email with the <literal 17.944 + role="hg-ext">patchbomb</literal> extension</title> 17.945 + 17.946 + <para id="x_531">Many projects have a culture of <quote>change 17.947 + review</quote>, in which people send their modifications to a 17.948 + mailing list for others to read and comment on before they 17.949 + commit the final version to a shared repository. Some projects 17.950 + have people who act as gatekeepers; they apply changes from 17.951 + other people to a repository to which those others don't have 17.952 + access.</para> 17.953 + 17.954 + <para id="x_532">Mercurial makes it easy to send changes over email for 17.955 + review or application, via its <literal 17.956 + role="hg-ext">patchbomb</literal> extension. The extension is 17.957 + so named because changes are formatted as patches, and it's usual 17.958 + to send one changeset per email message. Sending a long series 17.959 + of changes by email is thus much like <quote>bombing</quote> the 17.960 + recipient's inbox, hence <quote>patchbomb</quote>.</para> 17.961 + 17.962 + <para id="x_533">As usual, the basic configuration of the <literal 17.963 + role="hg-ext">patchbomb</literal> extension takes just one or 17.964 + two lines in your <filename role="special"> 17.965 + /.hgrc</filename>.</para> 17.966 + <programlisting>[extensions] 17.967 +patchbomb =</programlisting> 17.968 + <para id="x_534">Once you've enabled the extension, you will have a new 17.969 + command available, named <command 17.970 + role="hg-ext-patchbomb">email</command>.</para> 17.971 + 17.972 + <para id="x_535">The safest and best way to invoke the <command 17.973 + role="hg-ext-patchbomb">email</command> command is to 17.974 + <emphasis>always</emphasis> run it first with the <option 17.975 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 17.976 + This will show you what the command <emphasis>would</emphasis> 17.977 + send, without actually sending anything. Once you've had a 17.978 + quick glance over the changes and verified that you are sending 17.979 + the right ones, you can rerun the same command, with the <option 17.980 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 17.981 + removed.</para> 17.982 + 17.983 + <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 17.984 + accepts the same kind of revision syntax as every other 17.985 + Mercurial command. For example, this command will send every 17.986 + revision between 7 and <literal>tip</literal>, inclusive.</para> 17.987 + <programlisting>hg email -n 7:tip</programlisting> 17.988 + <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 17.989 + compare with. If you provide a repository but no revisions, the 17.990 + <command role="hg-ext-patchbomb">email</command> command will 17.991 + send all revisions in the local repository that are not present 17.992 + in the remote repository. If you additionally specify revisions 17.993 + or a branch name (the latter using the <option 17.994 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 17.995 + this will constrain the revisions sent.</para> 17.996 + 17.997 + <para id="x_538">It's perfectly safe to run the <command 17.998 + role="hg-ext-patchbomb">email</command> command without the 17.999 + names of the people you want to send to: if you do this, it will 17.1000 + just prompt you for those values interactively. (If you're 17.1001 + using a Linux or Unix-like system, you should have enhanced 17.1002 + <literal>readline</literal>-style editing capabilities when 17.1003 + entering those headers, too, which is useful.)</para> 17.1004 + 17.1005 + <para id="x_539">When you are sending just one revision, the <command 17.1006 + role="hg-ext-patchbomb">email</command> command will by 17.1007 + default use the first line of the changeset description as the 17.1008 + subject of the single email message it sends.</para> 17.1009 + 17.1010 + <para id="x_53a">If you send multiple revisions, the <command 17.1011 + role="hg-ext-patchbomb">email</command> command will usually 17.1012 + send one message per changeset. It will preface the series with 17.1013 + an introductory message, in which you should describe the 17.1014 + purpose of the series of changes you're sending.</para> 17.1015 + 17.1016 + <sect2> 17.1017 + <title>Changing the behavior of patchbombs</title> 17.1018 + 17.1019 + <para id="x_53b">Not every project has exactly the same conventions for 17.1020 + sending changes in email; the <literal 17.1021 + role="hg-ext">patchbomb</literal> extension tries to 17.1022 + accommodate a number of variations through command line 17.1023 + options.</para> 17.1024 + <itemizedlist> 17.1025 + <listitem><para id="x_53c">You can write a subject for the introductory 17.1026 + message on the command line using the <option 17.1027 + role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 17.1028 + option. This takes one argument, the text of the subject 17.1029 + to use.</para> 17.1030 + </listitem> 17.1031 + <listitem><para id="x_53d">To change the email address from which the 17.1032 + messages originate, use the <option 17.1033 + role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 17.1034 + option. This takes one argument, the email address to 17.1035 + use.</para> 17.1036 + </listitem> 17.1037 + <listitem><para id="x_53e">The default behavior is to send unified diffs 17.1038 + (see <xref linkend="sec:mq:patch"/> for a 17.1039 + description of the 17.1040 + format), one per message. You can send a binary bundle 17.1041 + instead with the <option 17.1042 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 17.1043 + option.</para> 17.1044 + </listitem> 17.1045 + <listitem><para id="x_53f">Unified diffs are normally prefaced with a 17.1046 + metadata header. You can omit this, and send unadorned 17.1047 + diffs, with the <option 17.1048 + role="hg-ext-patchbomb-cmd-email-opt">hg 17.1049 + --plain</option> option.</para> 17.1050 + </listitem> 17.1051 + <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 17.1052 + in the same body part as the description of a patch. This 17.1053 + makes it easiest for the largest number of readers to 17.1054 + quote and respond to parts of a diff, as some mail clients 17.1055 + will only quote the first MIME body part in a message. If 17.1056 + you'd prefer to send the description and the diff in 17.1057 + separate body parts, use the <option 17.1058 + role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 17.1059 + option.</para> 17.1060 + </listitem> 17.1061 + <listitem><para id="x_541">Instead of sending mail messages, you can 17.1062 + write them to an <literal>mbox</literal>-format mail 17.1063 + folder using the <option 17.1064 + role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 17.1065 + option. That option takes one argument, the name of the 17.1066 + file to write to.</para> 17.1067 + </listitem> 17.1068 + <listitem><para id="x_542">If you would like to add a 17.1069 + <command>diffstat</command>-format summary to each patch, 17.1070 + and one to the introductory message, use the <option 17.1071 + role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> 17.1072 + option. The <command>diffstat</command> command displays 17.1073 + a table containing the name of each file patched, the 17.1074 + number of lines affected, and a histogram showing how much 17.1075 + each file is modified. This gives readers a qualitative 17.1076 + glance at how complex a patch is.</para> 17.1077 + </listitem></itemizedlist> 17.1078 + 17.1079 + </sect2> 17.1080 + </sect1> 17.1081 </chapter> 17.1082 17.1083 <!-- 17.1084 local variables: 17.1085 sgml-parent-document: ("00book.xml" "book" "chapter") 17.1086 end: 17.1087 ---> 17.1088 \ No newline at end of file 17.1089 +-->
18.1 --- a/it/web/index-home.html.in Sat Sep 12 17:58:26 2009 +0200 18.2 +++ b/it/web/index-home.html.in Sat Sep 12 17:58:56 2009 +0200 18.3 @@ -27,7 +27,7 @@ 18.4 18.5 <p>Mercurial è un progetto membro della <a href="http://conservancy.softwarefreedom.org/">Software Freedom Conservancy</a> (SFC), una meravigliosa organizzazione no-profit che offre ai progetti membro un supporto legale e amministrativo.</p> 18.6 18.7 - <p>Bryan O\’Sullivan, ha deciso di donare le proprie royalty sulle vendite di questo libro alla Software Freedom Conservancy e incoraggia anche i lettori a supportare il lavoro di questa organizzazione.</p> 18.8 + <p>Bryan O\’Sullivan ha deciso di donare le proprie royalty sulle vendite di questo libro alla Software Freedom Conservancy e incoraggia anche i lettori a supportare il lavoro di questa organizzazione.</p> 18.9 18.10 <p>La SFC può <a href="http://conservancy.softwarefreedom.org/?donate">accettare donazioni</a> (esenti dalle tasse secondo la disposizione IRS 501(c)(3), all\’interno degli Stati Uniti) per conto dei suoi progetti membro. Se volete supportare Mercurial direttamente, considerate la possibilità di fare una donazione alla SFC per destinarla al progetto.</p> 18.11
19.1 --- a/web/index.html.in Sat Sep 12 17:58:26 2009 +0200 19.2 +++ b/web/index.html.in Sat Sep 12 17:58:56 2009 +0200 19.3 @@ -9,24 +9,46 @@ 19.4 19.5 <p>This is the online home of the book “Mercurial: The 19.6 Definitive Guide”. 19.7 - It will be published in 2009 by O'Reilly Media.</p> 19.8 + It was published in 2009 by O'Reilly Media.</p> 19.9 19.10 - <p>I make the content <a href="/read/">freely available 19.11 - online</a>. If you like it, please make a note to buy a copy!</p> 19.12 + <p><a href="http://www.selenic.com/mercurial">Mercurial</a> is a 19.13 + fast, lightweight source control management system 19.14 + designed for easy and efficient handling of very large distributed 19.15 + projects. My book tells you what it is, why you should care, and 19.16 + how you can use it effectively.</p> 19.17 + 19.18 + <h2>Read it online</h2> 19.19 + 19.20 + <p>I make the content freely available online: you 19.21 + can <a href="/read/"><i>read it here</i></a>. If you like it, 19.22 + please <a href="#buy">buy a copy</a>!</p> 19.23 19.24 <p>For news updates, please 19.25 - visit <a href="http://www.serpentine.com/blog/">my blog</a>.</p> 19.26 + visit <a href="http://www.serpentine.com/blog/">my blog</a>. You 19.27 + should follow me on 19.28 + Twitter <a href="http://twitter.com/bos31337">here</a>.</p> 19.29 19.30 - <h2>You can contribute!</h2> 19.31 + <h2><a name="#buy">How</a> to buy</h2> 19.32 + 19.33 + <p>If you like the book, please support the work of the Software 19.34 + Freedom Conservancy (<a href="#sfc">see below</a>) by buying a 19.35 + copy.</p> 19.36 + 19.37 + <ul> 19.38 + <li><a href="http://www.amazon.com/gp/product/0596800673?ie=UTF8&tag=reaworhas-20&linkCode=as2&camp=1789&creative=390957&creativeASIN=0596800673">Amazon.com</a><img src="http://www.assoc-amazon.com/e/ir?t=reaworhas-20&l=as2&o=1&a=0596800673" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" /></li> 19.39 + <li><a href="http://oreilly.com/catalog/9780596800673/">O'Reilly Media</a></li> 19.40 + </ul> 19.41 + 19.42 + <h2>You should contribute!</h2> 19.43 19.44 <p>I publish the source code for this book 19.45 - as <a href="http://hg.serpentine.com/mercurial/book">a 19.46 + as <a href="http://bitbucket.org/bos/hgbook">a 19.47 Mercurial repository</a>. Please feel 19.48 welcome to clone it, make modifications to your copy, and send me 19.49 changes. Getting a copy of the source takes just a few seconds if 19.50 you have Mercurial installed:</p> 19.51 19.52 - <pre class="screen">hg clone http://hg.serpentine.com/mercurial/book</pre> 19.53 + <pre class="screen">hg clone http://bitbucket.org/bos/hgbook</pre> 19.54 19.55 <p>The online version of the book includes a comment system 19.56 that you can use to send feedback involving errors, omissions, and 19.57 @@ -36,22 +58,16 @@ 19.58 publishing project of your own, the source for the web application 19.59 is included with the book source at the link above.)</p> 19.60 19.61 - <h2>What is Mercurial?</h2> 19.62 - 19.63 - <p><a href="http://www.selenic.com/mercurial">Mercurial</a> is a 19.64 - fast, lightweight source control management system 19.65 - designed for easy and efficient handling of very large distributed 19.66 - projects.</p> 19.67 - 19.68 - <h2>How I help Mercurial and free software, and you can too</h2> 19.69 + <h2><a name="sfc">How</a> I help Mercurial and free software, and 19.70 + you can too</h2> 19.71 19.72 <p>Mercurial is a member of the <a href="http://conservancy.softwarefreedom.org/">Software Freedom Conservancy</a>, a 19.73 wonderful non-profit organisation that offers its member projects 19.74 legal and administrative advice.</p> 19.75 19.76 - <p>I am donating my royalties from the sales of this book (once it is 19.77 - published) to the Software Freedom Conservancy, and I encourage 19.78 - you to support their work, too.</p> 19.79 + <p>I donate my royalties from the sales of this book to the 19.80 + Software Freedom Conservancy, and I encourage you to support their 19.81 + work, too.</p> 19.82 19.83 <p>The SFC can 19.84 accept <a href="http://conservancy.softwarefreedom.org/?donate">accept