# HG changeset patch
# User Romain PELISSE <belaran@gmail.com>
# Date 1252781616 -7200
# Node ID a6b81cd31cfd5da20e0dc629ee65cc4f3b08eb58
# Parent  9d32b10fdb1ed71ebea7b04597cd4bea74b6045b
adding complete.xml - which generated but Bryan did add it also - as I have absolutly no personnality I do as he does

diff -r 9d32b10fdb1e -r a6b81cd31cfd fr/complete.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/fr/complete.xml	Sat Sep 12 20:53:36 2009 +0200
@@ -0,0 +1,16711 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+<book id="hg">
+  <title>Mercurial: The Definitive Guide</title>
+  
+  <!-- hg parents &#x2d;&#x2d;template '{node|short} ({date|shortdate})' 
+  <subtitle>Compiled from 8a1d3f1aff17 (2009-03-10)</subtitle>
+  -->
+  <subtitle>Compiled from $rev_id$</subtitle>
+  <bookinfo>
+    <edition>1</edition>
+    <isbn>9780596800673</isbn>
+    <authorgroup>
+      <author>
+        <firstname>Bryan</firstname>
+        <surname>O'Sullivan</surname>
+      </author>
+    </authorgroup>
+
+    <editor>
+      <firstname>Mike</firstname>
+      <surname>Loukides</surname>
+    </editor>
+
+    <copyright>
+      <year>2006</year>
+      <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Bryan O'Sullivan</holder>
+    </copyright>
+  </bookinfo>
+
+  <!-- BEGIN ch00 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<preface id="chap:preface">
+  <?dbhtml filename="preface.html"?>
+  <title>Preface</title>
+
+  <sect1>
+    <title>Un conte technique</title>
+
+    <para id="x_72e">Il y a quelques années, quand j'ai voulu expliqué
+    pourquoi je pensais que le gestion de révision distribuée est importante,
+    le domaine était encore si nouveau qu'il n'y avait presque aucune 
+    littérature publiée pour servir de référence aux personnes intéressées.</para>
+
+    <para id="x_72f">Bien qu'à cette époque je passais beaucoup de temps
+    à travailler sur les entrailles de Mercurial, je me suis mis à la 
+    rédaction de ce livre parce qu'il me semblait la manière la plus efficace
+    d'aider notre logiciel à atteindre un vaste auditoire, toujours avec 
+    l'idée que la gestion de révision devrait être distribuée par nature. J'ai 
+    publié ce libre en ligne sous une licence libre pour la même raison : pour 
+    diffuser la parole auprès du monde.</para>
+
+    <para id="x_730">Il y a un rythme familier à un bon livre sur un logiciel 
+    qui ressemble de près au fait de conter une histoire : Pourquoi ceci est ? 
+    Pourquoi ceci est important ? Comment peut il m'aider ? Comment m'en 
+    servir ? Dans ce livre, j'essaye de répondre à toutes ces questions pour
+    la gestion de révision distribuée en général, et pour Mercurial en 
+    particulier.</para>
+  </sect1>
+    
+  <sect1>
+    <title>Merci de votre soutien à Mercurial</title>
+
+    <para id="x_731">En achetant une copie de ce livre, vous soutenez le
+    développement et la liberté de Mercurial en particulier, et dans 
+    l'Open Source, au logiciel libre en général. O'Reilly Media et 
+    moi-même donnons les revenus issus des ventes de ce livre à la
+    Software Freedom Conservancy (<ulink url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 
+      qui fournit un support juridique à Mercurial et à de 
+      nombreux autres projets Open Source proéminents et de qualité.</para>
+  </sect1>
+
+  <sect1>
+    <title>Remerciements</title>
+
+    <para id="x_732">Ce livre n'aurait pas vu le jour sans les
+    efforts de Matt Mackal, l'auteur et le chef du projet Mercurial.
+    Il est assisté très efficacement par des centaines de contributeurs
+    volontaires à travers le monde.</para>
+
+    <para id="x_733">Les enfants, Cian et Ruairi, ont toujours été prêt
+    à m'aider à me reposer avec de merveilleux et impulsif jeux d'enfants. 
+    Je tiens aussi à remercier mon ex-femme, Shannon, pour son soutien.
+    </para>
+
+    <para id="x_734">Mes collègues et amis m'ont aidé et assisté de 
+    de nombreuses manières. Cette liste de personne est nécessaire mais très
+    incomplète : Stephen Hahn, Karyn Ritter, Bonnie Corwin, James Vasile,
+    Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh, Jeremy
+    Fitzhardinge, Rachel Chalmers.</para>
+
+    <para id="x_735">J'ai conçu ce livre de manière ouverte, en publiant
+    des brouillons des chapitres du livre sur des site web, au fur et à 
+    mesure que je les réalisais. Leurs lecteurs m'ont fait des retours 
+    utilisant l'application web que j'avais développée. A la fin de sa
+    conception, plus de 100 personnes m'avaient fait des commentaires, 
+    un chiffre incroyable quand l'on considère que ce système de 
+    commentaire n'a tourné que dans les deux derniers mois de la 
+    rédaction du livre.</para>
+
+    <para id="x_736">J'aimerais particulièrement remercier les 
+    personnes suivantes, dont les commentaires représentent plus
+    d'un tiers de l'ensemble de ces derniers. Je voudrais les 
+    remercier pour leur attention et effort à me faire des retours
+    très détaillés.</para>
+
+    <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
+      Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
+      Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
+      Parise.</para>
+
+    <para id="x_738">Je souhaite aussi remercier l'aide des personnes
+    qui ont découvert des erreurs et fournit des suggestions avisées
+    à travers tout le livre.</para>
+
+    <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
+      Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
+      Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
+      Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
+      Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
+      Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
+      Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
+      Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
+      David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
+      Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
+      Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
+      Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
+      Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
+      Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
+      Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
+      Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
+      Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
+      Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
+      Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
+      Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
+      Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
+      Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
+      Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
+      Ahmed Chaudhary.</para>
+  </sect1>
+
+  <sect1>
+    <title>Conventions utilisées dans ce livre</title>
+
+    <para id="x_73a">Les conventions typographiques suivantes sont utilisées dans ce livre :</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Italique</term>
+
+        <listitem>
+          <para id="x_73b">Indique les termes nouveaux, les URLs, les
+            adresses mail, les noms de fichiers et les extensions de
+            fichier.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal moreinfo="none">Taille constante</literal></term>
+
+        <listitem>
+          <para id="x_73c">Utilisé pour les extraits de code, comme 
+          dans les paragraphes pour référer aux éléments du programme,
+          tels que les variables ou les noms de fonctions, de bases
+          de données, de types de données, de variables d'environnement,
+          d'instructions, et de mots clés.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><userinput moreinfo="none">Taille constante avec gras</userinput></term>
+
+        <listitem>
+          <para id="x_73d">Afficher les commandes ou autres textes qui
+          devraient être saisis par l'utilisateur.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><replaceable>Constante avec italique</replaceable></term>
+
+        <listitem>
+          <para id="x_73e">Affiche les textes qui devraient être remplacés 
+          par une valeur définie par l'utilisateur ou des valeurs définies
+          selon le contexte.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <tip>
+      <para id="x_73f">Cette icône indique une astuce, une suggestion ou 
+      une note d'ordre général.</para>
+    </tip>
+
+    <caution>
+      <para id="x_740">Cette icône est un message d'alerte ou de prudence.</para>
+    </caution>
+  </sect1>
+
+  <sect1>
+    <title>Utiliser les exemples de code</title>
+
+    <para id="x_741">Ce livre est ici pour vous aider dans votre
+    travail. De manière générale, vous pouvez donc utiliser le code
+    de ce livre dans vos programmes et votre documentation. Vous
+    n'avez pas à nous contacter pour nous demander la permission
+    de le faire, à moins que vous ne reproduisiez une partie significative
+    du code. Par exemple, écrire un programme qui utilise plusieurs 
+    extraits de code du livre ne demande aucune autorisation particulière.
+    Vendre ou distribuer un CD-ROM provenant des livres O'Reilly demande
+    à l'inverse une autorisation. Répondre à une question en citant ce 
+    livre ou ses exemples de code ne demande aucune autorisation préalable.
+    Intégrer une grande quantité des codes d'exemples de ce livre dans
+    votre propre ouvrage demande une autorisation de notre part.</para>
+
+    <para id="x_742">Nous apprécions, sans l'exiger, que vous citiez 
+    l'ouvrage dans vos écrits l'utilisant, en indiquant le titre, 
+    l'auteur, l'éditeur et son ISBN. Par exemple: “<emphasis>Titre du 
+    livre</emphasis> par Son Auteur. Copyright 2008 O’Reilly Media, Inc.,
+    978-0-596-xxxx-x.”</para>
+
+    <para id="x_743">Si vous estimez que votre usage des exemples de code
+    dépasse le cadre défini ci dessus, n'hésitez pas à nous contacter :
+      <email>permissions@oreilly.com</email>.</para>
+  </sect1>
+
+  <sect1>
+    <title>Safari® Books Online</title>
+
+    <note role="safarienabled">
+      <para id="x_744">Quand vous voyez l'icône de Safari® Books Online 
+      sur la couverture d'un de vos livres techniques préférés, cela signifie
+      que le livre est disponible, en ligne, à travers le O’Reilly Network Safari
+        Bookshelf.</para>
+    </note>
+
+    <para id="x_745">Safari offre une solution qui est meilleure que
+    les e-books. C'est une bibliothèque virtuelle qui vous laisse
+    aisément rechercher dans des milliers de livres, mais aussi 
+    copier-coller leurs exemples, télécharger des chapitres, et 
+    trouver des réponses rapides quand vous avez besoin d'une 
+    information précise et à jour. Essayez le gratuitement :
+    <ulink role="orm:hideurl:ital" url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
+  </sect1>
+
+  <sect1>
+    <title>Comment nous contacter</title>
+
+    <para id="x_746">Merci d'adresser vos commentaires et vos questions
+    sur ce livre à son éditeur:</para>
+
+    <simplelist type="vert">
+      <member>O’Reilly Media, Inc.</member>
+
+      <member>1005 Gravenstein Highway North</member>
+
+      <member>Sebastopol, CA 95472</member>
+
+      <member>800-998-9938 (in the United States or Canada)</member>
+
+      <member>707-829-0515 (international or local)</member>
+
+      <member>707 829-0104 (fax)</member>
+    </simplelist>
+
+    <para id="x_747">Nous avons une page web pour cet ouvrage, où nous
+    publions des errata, des exemples, et encore d'autres informations
+    additionnelles. Vous pouvez accéder à cette page par l'URL suivante:
+    </para>
+
+    <simplelist type="vert">
+      <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog           page&gt;"/></member>
+    </simplelist>
+
+    <remark>N'oubliez pas de mettre à jour l'attribut &lt;url&gt; aussi.</remark>
+
+    <para id="x_748">Pour commenter ou poser des questions techniques 
+    sur cet ouvrage, envoyez un email à :</para>
+
+    <simplelist type="vert">
+      <member><email>bookquestions@oreilly.com</email></member>
+    </simplelist>
+
+    <para id="x_749">Pour plus d'informations sur nos livres, nos
+    conférences, nos centres d'informations, et le réseau O’Reilly, 
+    voyez notre site web :</para>
+
+    <simplelist type="vert">
+      <member><ulink url="http://www.oreilly.com"/></member>
+    </simplelist>
+  </sect1>
+</preface>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "preface")
+end:
+-->
+
+  <!-- BEGIN ch01 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:intro">
+  <?dbhtml filename="how-did-we-get-here.html"?>
+  <title>Comment en est on arrivé là ?</title>
+
+<sect1>
+<title>À propos de la gestion source</title>
+
+    <para id="x_6d">La gestion de sources est un processus permettant de gérer différentes
+versions de la même information. Dans sa forme la plus simple, c'est
+ce que tout le monde fait manuellement : quand vous modifiez
+un fichier, vous le sauvegardez sous un nouveau nom contenant un numéro,
+à chaque fois plus grand que celui de la version précédente.</para>
+
+    <para id="x_6e">Ce genre de gestion de version manuelle est cependant facilement sujette
+aux erreurs, ainsi, depuis longtemps, des logiciels existent pour
+résoudre cette problématique. Les premiers outils de gestion de sources
+étaient destinés à aider un seul utilisateur, à automatiser la gestion
+des versions d'un seul fichier. Dans les dernières décades, cette cible
+s'est largement agrandie, ils gèrent désormais de multiples fichiers, et
+aident un grand nombre de personnes à travailler ensemble. Les outils les
+plus modernes n'ont aucune difficulté à gérer plusieurs milliers de
+personnes travaillant ensemble sur des projets regroupant plusieurs
+centaines de milliers de fichiers.</para>
+
+    <para id="x_6f">L'arrivée de la gestion de révision distribuée est
+    relativement récente, et, pour le moment, ce nouveau domaine a grandi
+    grâce à la volonté des gens d'explorer ces territoires encore inconnus.
+    </para>
+
+    <para id="x_70">J'écris un livre sur la gestion de révision distribuée
+    parce que je pense qu'il s'agit d'un sujet important qui mérite un guide
+    du terrain. J'ai choisi d'écrire un livre sur Mercurial car il est
+    l'outil le plus facile pour découvrir ce nouveau domaine, tout en étant
+    un outil efficace qui répond aux demandes d'environnements réels et
+    difficiles, là où d'autres outils de gestions de versions s'effondrent.</para>
+
+    <sect2>
+      <title>Pourquoi utiliser un gestionnaire de source ?</title>
+
+      <para id="x_71">Il y a de nombreuses raisons pour que vous ou votre équipe souhaitiez
+utiliser un outil automatisant la gestion de version pour votre projet.</para>
+
+      <itemizedlist>
+	<listitem><para id="x_72">L'outil se chargera de suivre l'évolution de votre projet, sans
+que vous ayez à le faire. Pour chaque modification, vous aurez à votre
+disposition un journal indiquant <emphasis>qui</emphasis> a fait quoi, <emphasis>pourquoi</emphasis>
+il l'a fait, <emphasis>quand</emphasis> il l'a fait, et
+<emphasis>ce</emphasis> qu'il a modifié.</para>
+</listitem>
+<listitem><para id="x_73">Quand vous travaillez avec d'autres personnes, les logiciels de
+gestion de source facilitent le travail collaboratif. Par exemple, quand
+plusieurs personnes font, plus ou moins simultanément, des modifications
+incompatibles, le logiciel vous aidera à identifier et à résoudre les conflits.</para>
+</listitem>
+<listitem><para id="x_74">L'outil vous aidera à réparer vos erreurs. Si vous effectuez un changement
+qui se révèle être une erreur, vous pourrez revenir à une version
+antérieure d'un fichier ou même d'un ensemble de fichiers. En fait, un outil de
+gestion de source <emphasis>vraiment</emphasis> efficace vous permettra d'identifier à quel
+moment le problème est apparu (voir la section <xref linkend="sec:undo:bisect"/> pour plus
+de détails).</para>
+</listitem>
+<listitem><para id="x_75">L'outil vous permettra aussi de travailler sur plusieurs versions différentes
+de votre projet et de gérer l'écart entre chacune.</para>
+</listitem></itemizedlist>
+<para id="x_76">La plupart de ces raisons ont autant d'importances —du
+  moins en théorie— que vous travailliez sur un projet pour vous, ou
+  avec une centaine d'autres personnes.
+</para>
+
+<para id="x_77">Une question fondamentale à propos des outils de gestion de
+  source, qu'il s'agisse du projet d'une personne ou d'une grande équipe, est
+  quels sont ses <emphasis>avantages</emphasis> par rapport à ses
+  <emphasis>coûts</emphasis>. Un outil qui est difficile à utiliser ou à
+  comprendre exigera un lourd effort d'adaptation.
+</para>
+
+<para id="x_78">)Un projet de cinq milles personnes s'effondrera très
+  certainement de lui même sans aucun processus et outil de gestion de
+  source. Dans ce cas, le coût d'utilisation d'un logiciel de gestion de
+  source est dérisoire puisque <emphasis>sans</emphasis>, l'échec est presque
+  garanti.
+</para>
+
+<para id="x_79">D'un autre coté, un <quote>rapide hack</quote> d'une personne
+  peut sembler un contexte bien pauvre pour utiliser un outil de gestion de
+  source, car, bien évidement le coût d'utilisation dépasse le coût total du
+  projet. N'est ce pas ?
+</para>
+
+      <para id="x_7a">Mercurial supporte ces <emphasis>deux</emphasis>
+        échelles de travail. Vous pouvez apprendre les bases en quelques
+        minutes seulement, et, grâce à sa performance, vous pouvez l'utiliser
+        avec facilité sur le plus petit des projets. Cette simplicité
+        signifie que vous n'avez pas de concept obscurs ou de séquence de
+        commandes défiant l'imagination, sans aucune corrélation avec
+        <emphasis>ce que vous êtes entrain de faire</emphasis>. En même
+        temps, ces mêmes performances et sa nature
+        <quote>peer-to-peer</quote> vous permettent d'adapter, sans
+        difficulté, son utilisation à de très grands projets.
+</para>
+
+      <para id="x_7b">Aucun outil de gestion de source ne peut sauver un
+        projet mal mené, mais un bon outil peut rendre beaucoup plus fluide
+        votre travail.
+</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Les multiples noms de la gestion de source</title>
+
+      <para id="x_7c">La gestion de source
+        <!-- TODO:<footnote><J'ai utilisé systématiquement le terme
+            <quote>gestion de source</quote> à travers tout l'ouvrage. Ce
+            n'est pas forcement la meilleure traduction, et ceci peut rendre
+            la lecture un peu lourde, mais je pense que le document y gagne
+            en clarté et en précision. -->
+        est un domaine tellement large qu'il n'existe pas qu'un seul nom ou
+        acronyme pour le désigner. Voici quelques noms ou acronymes que vous
+        rencontrerez le plus souvent.
+        <!-- TODO:<footnote> J'ai conservé la liste des noms en anglais pour
+          des raisons de commodité (ils sont plus <quote>googelable</quote>).
+          En outre, j'ai opté  pour conserver l'ensemble des opérations de
+          Mercurial (\textit{commit},\textit{push}, \textit{pull},...) en
+          anglais, là aussi pour faciliter la lecture d'autres documents en
+          anglais, ainsi que l'utilisation de Mercurial. -->
+</para>
+
+<para>:
+</para>
+
+      <itemizedlist>
+	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
+	<listitem><para id="x_7e">Software configuration management (SCM), ou
+	    configuration management</para></listitem>
+	<listitem><para id="x_7f">Source code management</para></listitem>
+	<listitem><para id="x_80">Source code control, ou source control</para></listitem>
+	<listitem><para id="x_81">Version control (VCS)</para></listitem></itemizedlist>
+
+ <para id="x_82">Certaines personnes prétendent que ces termes ont en fait
+   des sens différents mais en pratique ils se recouvrent tellement qu'il n'y
+   a pas réellement de manière pertinente de les distinguer. </para>
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+
+<title>A propos des exemples dans ce livre</title>
+
+    <para id="x_84">Ce livre prend une approche non usuel pour les exemples
+      de code. Tous les exemples sont en <quote>live</quote> — Chacun
+      est actuellement le résultat d'un script shell qui exécute les
+      commandes Mercurial que vous voyez. A chaque fois qu'une image du livre
+      est construite à partir des sources, tous les scripts d'exemple sont
+      lancés automatiquement, et leurs résultats effectifs sont comparés aux
+      résultats attendus.</para>
+
+    <para id="x_85">L'avantage de dette approche est que les exemples sont
+      toujours précis ; ils décrivent <emphasis>exactement</emphasis> la
+      conduite de la version de Mercurial qui est mentionnée en entête du
+      livre. Si je met à jour la version de Mercurial que je suis en train de
+      documenter, et que la sortie de certaines commandes change, la
+      construction du livre échoue.</para>
+
+    <para id="x_86">
+      Il existe un petit désavantage à cette approche qui est que les dates et
+      heures que vous verrez dans les exemples tendent à être
+      <quote>écrasés</quote> ensemble, dans le sens où elles ne sont pas
+      celles qu'elles auraient été si un humain avait tapé les commandes. En
+      effet, humain ne peut pas taper plus d'une commande toutes les quelques
+      secondes, avec le temps qui s'écoule, mes scripts d'exemples exécutent
+      plusieurs commandes en une seconde.
+    </para>
+
+    <para id="x_87">Une circonstance de ceci est que plusieurs commits
+      consécutifs dans un exemple peuvent apparaître comme ayant eu lieu
+      durant la même seconde.
+      Vous pouvez observer le phénomène dans l'exemple <literal role="hg-ext" moreinfo="none">bisect</literal> dans <xref linkend="sec:undo:bisect"/>
+    </para>
+
+    <para id="x_88">Donc, lorsque vous lisez ces exemples, ne prêtez pas trop
+      d'importance aux dates et heures que vous voyez dans la sortie des
+      commandes. Cependant, <emphasis>soyez</emphasis> confiants que le
+      comportement que vous voyez est consistent et reproductible 
+    </para>
+
+  </sect1>
+
+<!-- The next section has disapper from this part of the book. it may be splaced somewhere else... t-->
+
+  <sect1>
+    <title>Tendances de la gestion de source</title>
+
+    <para id="x_89">Il y a eu une tendance évidente dans le développement et
+      l'utilisation d'outils de gestion de source depuis les quatre dernières
+      décades, au fur et à mesure que les utilisateurs se sont habitués à
+      leur outils et se sont sentis contraints par leurs limitations.
+    </para>
+
+    <para id="x_8a">La première génération commença simplement par gérer un
+      fichier unique sur un ordinateur individuel. Cependant, même si ces
+      outils présentaient une grande avancée par rapport à la gestion
+      manuelle des versions, leur modèle de verrouillage et leur utilisation
+      limitée à un seul ordinateur rendaient leur utilisation possible
+      uniquement dans une très petite équipe.
+    </para>
+
+    <para id="x_8b">La seconde génération a assoupli ces contraintes en
+      adoptant une architecture réseau et centralisée, permettant de gérer
+      plusieurs projets entiers en même temps. Alors que les projets
+      grandirent en taille, ils rencontrèrent de nouveaux problèmes. Avec les
+      clients discutant régulièrement avec le serveurs, la montée en charge
+      devint un réel problème sur les gros projets. Une connexion réseau peu
+      fiable pouvait complètement empêcher les utilisateurs distants de
+      dialoguer avec le serveur. Alors que les projets <emphasis remap="it">Open Source</emphasis> commencèrent à mettre en place des
+      accès en lecture seule disponible anonymement, les utilisateurs sans
+      les privilèges de <quote>commit</quote> réalisèrent qu'ils ne pouvaient
+      pas utiliser les outils pour collaborer naturellement avec le projet,
+      comme ils ne pouvaient pas non plus enregistrer leurs modifications.
+    </para>
+
+    <para id="x_8c">La génération actuelle des outils de gestion de source
+      est <quote>peer-to-peer</quote> par nature. Tous ces systèmes ont
+      abandonné la dépendance à un serveur central, et ont permis à leur
+      utilisateur de distribuer les données de leur gestion de source à qui
+      en a besoin. La collaboration à travers Internet a transformé la
+      contrainte technologique en une simple question de choix et de
+      consensus. Les outils modernes peuvent maintenant fonctionner en mode
+      déconnecté sans limite et de manière autonome, la connexion au réseau
+      n'étant nécessaire que pour synchroniser les modifications avec les
+      autres dépôts.
+    </para>
+  </sect1>
+    
+  <sect1>
+    <title>Quelques avantages des gestionnaires de source distribués</title>
+      
+    <para id="x_8d">Même si les gestionnaire de source distribués sont depuis
+      plusieurs années assez robustes et aussi utilisables que leurs
+      prédécesseurs, les utilisateurs d'autres outils n'y ont pas encore été
+      sensibilisés. Les gestionnaires de source distribués se distinguent
+      particulièrement de leurs équivalents centralisés de nombreuses
+      manières.
+    </para>
+
+    <para id="x_8e">Pour un développeur individuel, ils restent beaucoup plus
+      rapides que les outils centralisés. Cela pour une raison simple : un
+      outil centralisé doit toujours dialoguer à travers le réseau pour la
+      plupart des opérations, car presque toutes les métadonnées sont
+      stockées sur la seule copie du serveur central. Un outil distribué
+      stocke toute ses métadonnées localement. À tâche égale, effectuer un
+      échange avec le réseau ajoute un délai aux outils centralisés. Ne
+      sous-estimez pas la valeur d'un outil rapide : vous allez passer
+      beaucoup de temps à interagir avec un logiciel de gestion de source.
+    </para>
+
+    <para id="x_8f">Les outils distribués sont complètement indépendants des
+      aléas de votre serveur, d'autant plus qu'ils répliquent les métadonnées
+      à beaucoup d'endroits. Si votre serveur central prend feu, vous avez
+      intérêt à ce que les médias de sauvegardes soient fiables, et que votre
+      dernier <quote>backup</quote> soit récent et fonctionne sans problème.
+      Avec un outil distribué, vous avez autant de <quote>backup</quote> que
+      de contributeurs.
+    </para>
+
+    <para id="x_90">En outre, la fiabilité de votre réseau affectera beaucoup
+      moins les outils distribués. Vous ne pouvez même pas utiliser un outil
+      centralisé sans connexion réseau, à l'exception de quelques commandes,
+      très limitées. Avec un outil distribué, si votre connexion réseau tombe
+      pendant que vous travaillez, vous pouvez ne même pas vous en rendre
+      compte. La seule chose que vous ne serez pas capable de faire sera de
+      communiquer avec des dépôts distants, opération somme toute assez rare
+      en comparaison aux opérations locales. Si vous avez une équipe de
+      collaborateurs très dispersée ceci peut être significatif.
+    </para>
+
+    <sect2>
+      <title>Avantages pour les projets Open Source</title>
+
+      <para id="x_91">Si vous prenez goût à un projet <emphasis remap="it">Open Source</emphasis> et que vous décidez de commencer
+        à toucher à son code, et que le projet utilise un gestionnaire de
+        source distribué, vous êtes immédiatement un "pair" avec les
+        personnes formant le <quote>cœur</quote> du projet. S'ils publient
+        leurs dépôts, vous pouvez immédiatement copier leurs historiques de
+        projet, faire des modifications, enregistrer votre travail en
+        utilisant les mêmes outils qu'eux. Par comparaison avec un outil
+        centralisé, vous devez utiliser un logiciel en mode <quote>lecture
+          seule</quote> à moins que quelqu'un ne vous donne les privilèges de
+        <quote>commit</quote> sur le serveur central. Avant ça, vous ne serez
+        pas capable d'enregistrer vos modifications, et vos propres
+        modifications risqueront de se corrompre chaque fois que vous
+        essayerez de mettre à jour à votre espace de travail avec le serveur
+        central.
+      </para>
+
+    <sect3>
+      <title>Le non-problème du "fork"</title>
+      
+      <para id="x_92">Il a été souvent suggéré que les gestionnaires de
+        source distribués posent un risque pour les projets <emphasis remap="it">Open Source</emphasis> car ils facilitent grandement la
+        création de <quote>fork</quote>.
+        <!--footnote{NdT:Création d'une <ulink url="version alternative du
+          logiciel">version alternative du
+          logiciel</ulink>{http://fr.wikipedia.org/wiki/Fork#Embranchement_d.27un_projet_informatique}
+        -->
+        Un <quote>fork</quote> apparait quand il y des divergences d'opinion
+        ou d'attitude au sein d'un groupe de développeurs qui aboutissent à
+        la décision de ne plus travailler ensemble. Chaque parti s'empare
+        d'une copie plus ou moins complète du code source du projet et
+        continue dans sa propre direction.
+      </para>
+
+
+      <para id="x_93">Parfois ces différents partis décident de se
+        réconcilier. Avec un serveur central, l'aspect
+        <emphasis>technique</emphasis> de cette réconciliation est un
+        processus douloureux, et essentiellement manuel. Vous devez décider
+        quelle modification est <quote>la gagnante</quote>, et replacer, par
+        un moyen ou un autre, les modifications de l'autre équipe dans
+        l'arborescence du projet. Ceci implique généralement la perte d'une
+        partie de l'historique d'un des partis, ou même des deux.
+      </para>
+    
+      <para id="x_94">Ce que les outils distribués permettent à ce sujet est
+        probablement la <emphasis>meilleure</emphasis> façon de développer un
+        projet. Chaque modification que vous effectuez est potentiellement un
+        <quote>fork</quote>. La grande force de cette approche est que les
+        gestionnaires de source distribués doivent être vraiment très
+        efficaces pour <emphasis>fusionner (merge)</emphasis>
+        <!-- TODO footnote{NdT:j'ai choisi de traduire ici <emphasis
+          remap="it">merging</emphasis> par <quote>fusionner</quote> pour des
+        raisons de clarté} -->
+        des <quote>forks</quote>, car les <quote>forks</quote>, dans ce
+        contexte, arrivent tout le temps.
+      </para>
+      
+      <para id="x_95">Si chaque altération que n'importe qui effectue, à tout
+        moment, est vue comme un <quote>fork</quote> à fusionner, alors ce
+        que le monde de l'<emphasis remap="it">Open Source</emphasis> voit
+        comme un <quote>fork</quote> devient <emphasis>uniquement</emphasis>
+        une problématique sociale. En fait, les outils de gestions de source
+        distribués <emphasis>réduisent</emphasis> les chances de
+        <quote>fork</quote> :
+      </para>
+        
+      <itemizedlist>
+        <listitem>
+        <para>Ils éliminent la distinction sociale qu'imposent les outils
+          centralisés entre les membres du projets (ceux qui ont accès au
+          <quote>commit</quote>) et ceux de l'extérieur (ce qui ne l'ont
+          pas).
+        </para>
+        <para>Ils rendent plus facile la réconciliation après un
+          <quote>fork</quote> social, car tout ce qu'elle implique est une
+          simple fusion.
+        </para>
+        </listitem>
+      </itemizedlist>
+
+      <para id="x_98">Certaines personnes font de la résistance envers les
+        gestionnaires de source distribués parce qu'ils veulent garder un
+        contrôle ferme sur leur projet, et ils pensent que les outils
+        centralisés leur fournissent ce contrôle. Néanmoins, si c'est votre
+        cas, sachez que si vous publiez votre dépôt CVS ou Subversion de
+        manière publique, il existe une quantité d'outils disponibles pour
+        récupérer entièrement votre projet et son historique (quoique
+        lentement) et le récréer ailleurs, sans votre contrôle. En fait,
+        votre contrôle sur votre projet est illusoire, vous ne faites
+        qu'interdire à vos collaborateurs de travailler de manière fluide, en
+        disposant d'un miroir ou d'un <quote>fork</quote> de votre
+        historique.
+      </para>
+
+    </sect3>
+    </sect2>
+    <sect2>
+      <title>Avantages pour les projets commerciaux</title>
+
+      <para id="x_99">Beaucoup de projets commerciaux sont réalisés par des
+        équipes éparpillées à travers le globe. Les contributeurs qui sont
+        loin du serveur central devront subir des commandes lentes et même
+        parfois peu fiables. Les solutions propriétaires de gestion de source
+        tentent de palier ce problème avec des réplications de sites distants
+        qui sont à la fois coûteuses à mettre en place et lourdes à
+        administrer. Un système distribué ne souffre pas de ce genre de
+        problèmes. En outre, il est très aisé de mettre en place plusieurs
+        serveurs de références, disons un par site, de manière à ce qu'il n'y
+        ait pas de communication redondante entre les dépôts, sur une
+        connexion longue distance souvent onéreuse.
+      </para>
+
+      <para id="x_9a">Les systèmes de gestion de source supportent
+        généralement assez mal la monté en charge. Il n'est pas rare pour un
+        gestionnaire de source centralisé pourtant onéreux de s'effondrer
+        sous la charge combinée d'une douzaine d'utilisateurs concurrents
+        seulement. Une fois encore, la réponse à cette problématique est
+        généralement encore la mise en place d'un ensemble complexe de
+        serveurs synchronisés par un mécanisme de réplication. Dans le cas
+        d'un gestionnaire de source distribué, la charge du serveur central
+        — si vous avez un— est plusieurs fois inférieure (car
+        toutes les données sont déjà répliquées ailleurs), un simple serveur,
+        pas très cher, peut gérer les besoins d'une plus grande équipe, et la
+        réplication pour balancer la charge devient le travail d'un simple
+        script.
+      </para>
+
+      <para id="x_9b">Si vous avez des employés sur le terrain, en train de
+        chercher à résoudre un souci sur le site d'un client, ils
+        bénéficieront aussi d'un gestionnaire de source distribué. Cet outil
+        leur permettra de générer des versions personnalisées, d'essayer
+        différentes solutions, en les isolant aisément les unes des autres,
+        et de rechercher efficacement à travers l'historique des sources, la
+        cause des bugs ou des régressions, tout ceci sans avoir besoin de la
+        moindre connexion au réseau de votre compagnie.
+      </para>
+
+    </sect2>
+    </sect1>
+    <sect1>
+      <title>Pourquoi choisir Mercurial?</title>
+
+      <para id="x_9c">Mercurial a plusieurs caractéristiques qui en font un
+        choix particulièrement pertinent pour la gestion de source :
+      </para>
+    <itemizedlist>
+      <listitem><para id="x_9d">Il est simple à apprendre et à utiliser.</para></listitem>
+      <listitem><para id="x_9e">Il est léger.</para></listitem>
+      <listitem><para id="x_9f">Il s'adapte très bien à la charge.</para></listitem>
+      <listitem><para id="x_a0">Il se personnalise facilement.</para></listitem>
+    </itemizedlist>
+
+    <para id="x_a1">Si vous êtes déjà familier d'un outil de gestion de
+      source, vous serez capable de l'utiliser en moins de 5 minutes. Sinon,
+      ça ne sera pas beaucoup plus long. Les commandes utilisées par
+      Mercurial, comme ses fonctionnalités, sont généralement uniformes et
+      cohérentes, et vous pouvez ainsi garder en tête simplement quelques
+      règles générales, plutôt qu'un lot complexe d'exceptions.
+    </para>
+
+    <para id="x_a2">Sur un petit projet, vous pouvez commencer à travailler
+      avec Mercurial en quelques instants. Ajouter des modifications ou des
+      branches, transférer ces modifications (localement ou via le réseau),
+      et les opérations d'historique ou de statut sont aussi très rapides.
+      Mercurial reste hors de votre chemin grâce à sa simplicité
+      d'utilisation et sa rapidité d'exécution.
+    </para>
+
+    <para id="x_a3">L'utilité de Mercurial ne se limite pas à de petits
+      projets: il est aussi utilisé par des projets ayant des centaines ou
+      même des milliers de contributeurs, avec plusieurs dizaines de milliers
+      de fichiers, et des centaines de méga octets de code source.
+    </para>
+
+    <para id="x_a4">Si les fonctionnalités au cœur de Mercurial ne sont pas
+      suffisantes pour vous, il est très aisé d'en construire d'autres.
+      Mercurial est adapté à l'utilisation de scripts, et son implémentation
+      interne en Python, propre et claire, rend encore plus facile l'ajout de
+      fonctionnalités sous forme d'extensions. Il en existe déjà un certain
+      nombre de très populaires et très utiles, dont le périmètre va de la
+      recherche de bugs à l'amélioration des performances.
+    </para>
+
+  </sect1>
+  <sect1>
+    <title>Mercurial comparé aux autres outils</title>
+
+    <para id="x_a5">Avant que vous n'alliez plus loin, comprenez bien que
+      cette section reflète mes propres expériences, et elle est donc (j'ose
+      le dire) peu objective. Néanmoins, j'ai utilisé les outils de gestion
+      de source listés ci dessous, dans la plupart des cas, pendant plusieurs
+      années.
+    </para>
+
+    <sect2>
+      <title>Subversion</title>
+
+      <para id="x_a6">Subversion est un des outils de gestion de source les
+        plus populaire, il fût développé pour remplacer CVS. Il a une
+        architecture client/server centralisée.
+      </para>
+
+      <para id="x_a7">Subversion et Mercurial ont des noms de commandes très
+        similaires pour les mêmes opérations, ainsi si vous êtes familier
+        avec l'un, c'est facile d'apprendre l'autre. Ces deux outils sont
+        portables sur les systèmes d'exploitation les plus populaires.
+      </para>
+
+      <para id="x_a8">Avant la version 1.5, Subversion n'offrait aucune forme
+        de support pour les fusions. Lors de l'écriture de ce livre, ses
+        capacités de fusion étaient nouvelles, et réputées pour être <ulink url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">
+          complexes et buguées</ulink>.
+      </para>
+
+      <para id="x_a9">Mercurial dispose d'un avantage substantiel en terme de
+        performance par rapport à Subversion sur la plupart des opérations
+        que j'ai pu tester. J'ai mesuré une différence de performance allant
+        de deux à six fois plus rapide avec le système de stockage de fichier
+        local de Subversion 1.4.3 (<emphasis>ra_local</emphasis>), qui est la
+        méthode d'accès la plus rapide disponible. Dans un déploiement plus
+        réaliste, impliquant un stockage réseau, Subversion serait encore
+        plus désavantagé. Parce que la plupart des commandes Subversion
+        doivent communiquer avec le serveur et que Subversion n'a pas de
+        mécanisme de réplication, la capacité du serveur et la bande passante
+        sont devenues des goulots d'étranglement pour les projets de taille
+        moyenne ou grande.
+      </para>
+
+      <para id="x_aa">En outre, Subversion implique une surcharge
+        substantielle dans le stockage local de certaines données, pour
+        éviter des transactions avec le serveur, pour certaines opérations
+        communes, telles que la recherche des fichiers modifiés
+        (<literal moreinfo="none">status</literal>) et l'affichage des modifications par
+        rapport à la révision courante (<literal moreinfo="none">diff</literal>). En
+        conséquence, un répertoire de travail Subversion a souvent la même
+        taille, ou est plus grand, qu'un dépôt Mercurial et son espace de
+        travail, et ceci bien que le dépôt Mercurial contienne l'intégralité
+        de l'historique.
+      </para>
+
+      <para id="x_ab">Subversion est largement supporté par les outils
+        tierces. Mercurial est actuellement encore en retrait de ce point de
+        vue. L'écart se réduit néanmoins, en effet, certains des outils
+        graphiques sont maintenant supérieurs à leurs équivalents Subversion.
+        Comme Mercurial, Subversion dispose d'un excellent manuel
+        utilisateur.
+      </para>
+
+      <para id="x_ac">Parce que Subversion ne stocke pas l'historique chez
+        ses clients, il est parfaitement adapté à la gestion de projets qui
+        doivent suivre un ensemble de larges fichiers binaires et opaques. Si
+        vous suivez une cinquantaine de versions d'un fichier incompressible
+        de 10MB, l'occupation disque coté client d'un projet sous Subversion
+        restera à peu près constante. A l'inverse, l'occupation disque du
+        même projet sous n'importe lequel des gestionnaires de source
+        distribués grandira rapidement, proportionnellement aux nombres de
+        versions, car les différences entre chaque révisions seront très
+        grandes.
+      </para>
+
+      <para id="x_ad">En outre, c'est souvent difficile ou, généralement,
+        impossible de fusionner des différences dans un fichier binaire. La
+        capacité de Subversion de verrouiller des fichiers, pour permettre à
+        l'utilisateur d'être le seul à le mettre à jour
+        (<quote>commit</quote>) temporairement, est un avantage significatif
+        dans un projet doté de beaucoup de fichiers binaires.
+      </para>
+
+      <para id="x_ae">Mercurial peut importer l'historique depuis un dépôt
+        Subversion. Il peut aussi exporter l'ensemble des révisions d'un
+        projet vers un dépôt Subversion. Ceci rend très facile de
+        <quote>prendre la température</quote> et d'utiliser Mercurial et
+        Subversion en parallèle, avant de décider de migrer vers Mercurial.
+        La conversion de l'historique est incrémentale, donc vous pouvez
+        effectuer une conversion initiale, puis de petites additions par la
+        suite pour ajouter les nouvelle modifications.
+      </para>
+
+
+    </sect2>
+    <sect2>
+      <title>Git</title>
+
+      <para id="x_af">Git est un outil de gestion de source distribué qui fût
+        développé pour gérer le code source de noyau de Linux. Comme
+        Mercurial, sa conception initiale a été inspirée par Monotone.
+      </para>
+
+      <para id="x_b0">Git dispose d'un ensemble conséquent de commandes, avec
+        plus de 139 commandes individuelles pour la version 1.5.0. Il a aussi
+        la réputation d'être difficile à apprendre. Comparé à Git, le point
+        fort de Mercurial est clairement sa simplicité.
+      </para>
+
+      <para id="x_b1">En terme de performance, Git est extrêmement rapide.
+        Dans la plupart des cas, il est plus rapide que Mercurial, tout du
+        moins sur Linux, alors que Mercurial peut être plus performant sur
+        d'autres opérations. Néanmoins, sur Windows, les performances et le
+        niveau de support général fourni par Git, au moment de l'écriture de
+        cet ouvrage, est bien derrière celui de Mercurial.
+      </para>
+
+      <para id="x_b2">Alors que le dépôt Mercurial ne demande aucune
+        maintenance, un dépôt Git exige d'exécuter manuellement et
+        régulièrement la commande <quote>repacks</quote> sur ses métadonnées.
+        Sans ceci, les performances de git se dégradent et la consommation de
+        l'espace disque augmente rapidement. Un serveur qui contient
+        plusieurs dépôts Git qui ne sont pas régulièrement et fréquemment
+        <quote>repacked</quote> deviendra un vrai problème lors des
+        <quote>backups</quote> du disque, et il y eu des cas, où un
+        <quote>backup</quote> journalier pouvait durer plus de 24 heures. Un
+        dépôt fraichement <quote>repacked</quote> sera légèrement plus petit
+        qu'un dépôt Mercurial, mais un dépôt non <quote>repacked</quote> est
+        beaucoup plus grand.
+      </para>
+
+      <para id="x_b3">Le cœur de Git est écrit en C. La plupart des commandes
+        Git sont implémentées sous forme de scripts Shell ou Perl, et la
+        qualité de ces scripts varie grandement. J'ai plusieurs fois constaté
+        que certains de ces scripts étaient chargés en mémoire aveuglément et
+        que la présence d'erreurs pouvait s'avérer fatal.
+      </para>
+
+      <para id="x_b4">Mercurial peut importer l'historique d'un dépôt Git.</para>
+
+    </sect2>
+    <sect2>
+      <title>CVS</title>
+
+      <para id="x_b5">CVS est probablement l'outil de gestion de source le
+        plus utilisé aujourd'hui dans le monde. À cause de son manque de
+        clarté interne, il n'est plus maintenu depuis plusieurs années.
+      </para>
+
+      <para id="x_b6">Il a une architecture client/serveur centralisée. Il ne
+        regroupe pas les modifications de fichiers dans une opération de
+        <quote>commit</quote> atomique, ce qui permet à ses utilisateurs de
+        <quote>casser le <emphasis>build</emphasis></quote> assez facilement
+        : une personne peut effectuer une opération de <quote>commit</quote>
+        sans problème puis être bloquée par besoin de fusion, avec comme
+        conséquence néfaste, que les autres utilisateurs ne récupèreront
+        qu'une partie de ses modifications. Ce problème affecte aussi la
+        manière de travailler avec l'historique du projet. Si vous voulez
+        voir toutes les modifications d'une personne du projet, vous devrez
+        injecter manuellement les descriptions et les <emphasis remap="it">timestamps</emphasis> des modifications de chacun des
+        fichiers impliqués (si vous savez au moins quels sont ces fichiers).
+      </para>
+
+      <para id="x_b7">CVS a une notion étrange des <emphasis remap="it">tags</emphasis> et des branches que je n'essayerai même
+        pas de décrire ici. Il ne supporte pas bien les opérations de
+        renommage d'un fichier ou d'un répertoire, ce qui facilite la
+        corruption de son dépôt. Il n'a presque pas pour ainsi dire de
+        contrôle de cohérence interne, il est donc pratiquement impossible de
+        dire si un dépôt est corrompu ni à quel point. Je ne recommanderai
+        pas CVS pour un projet existant ou nouveau.
+      </para>
+
+      <para id="x_b8">Mercurial peut importer l'historique d'un projet CVS.
+        Néanmoins, il y a quelques principes à respecter; ce qui est vrai
+        aussi pour les autres outils d'import de projet CVS. À cause de
+        l'absence de <quote>commit</quote> atomique et gestion de version de
+        l'arborescence, il n'est pas possible de reconstruire de manière
+        précise l'ensemble de l'historique. Un travail de
+        <quote>devinette</quote> est donc nécessaire, et les fichiers
+        renommés ne sont pas détectés. Parce qu'une bonne part de
+        l'administration d'un dépôt CVS est effectuée manuellement, et est
+        donc, sujette à erreur, il est courant que les imports CVS
+        rencontrent de nombreux problèmes avec les dépôt corrompus (des
+        <emphasis remap="it">timestamps</emphasis> de révision complètement
+        buggés et des fichiers verrouillés depuis des années sont deux des
+        problèmes les moins intéressants dont je me souvienne).
+      </para>
+
+      <para id="x_b9">Mercurial peut importer l'historique depuis un dépôt CVS.
+      </para>
+
+
+    </sect2>
+    <sect2>
+      <title>Outils propriétaires</title>
+
+      <para id="x_ba">Perforce a une architecture client/serveur centralisée,
+        sans aucun mécanisme de mise en cache de données coté client.
+        Contrairement à la plupart des outils modernes de gestion de source,
+        Perforce exige de ses utilisateurs d'exécuter une commande pour
+        informer le serveur central de tout fichier qu'ils souhaitent
+        modifier.
+      </para>
+
+      <para id="x_bb">Les performances de Perforce sont plutôt bonnes pour
+        des petites équipes, mais elles s'effondrent rapidement lorsque le
+        nombre d'utilisateurs augmente au delà de la douzaine. Des
+        installations de Perforce assez larges nécessitent le déploiement de
+        proxies pour supporter la montée en charge associée.
+      </para>
+
+    </sect2>
+    <sect2>
+      <title>Choisir un outil de gestion de source</title>
+
+      <para id="x_bc">A l'exception de CVS, tous les outils listés ci-dessus
+        ont des forces qui leur sont propres et qui correspondent à certaines
+        formes de projet. Il n'y a pas un seul meilleur outil de gestion de
+        source qui correspondrait le mieux à toutes les situations.
+      </para>
+
+      <para id="x_bd">En guise exemple, Subversion est un très bon choix
+        lorsqu'on travaille avec beaucoup de fichiers binaires, qui évoluent
+        régulièrement, grâce à sa nature centralisée et sa capacité à
+        verrouiller des fichiers.
+      </para>
+
+      <para id="x_be">Personnellement, je préfère Mercurial pour sa
+        simplicité, ses performances et sa bonne capacité de fusion, et il
+        m'a très bien rendu service de plusieurs années maintenant.
+      </para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Migrer depuis un outil à Mercurial</title>
+
+    <para id="x_bf">Mercurial est livré avec une extension nommée <literal role="hg-ext" moreinfo="none">convert</literal>, qui peut, de manière incrémentale
+      importer des révisions depuis différents autres outils de gestion de
+      source. Par <quote>incrémental</quote>, j'entends que vous pouvez
+      convertir l'historique entier du projet en une seule fois, puis
+      relancer l'outil d'import plus tard pour obtenir les modifications
+      effectuées depuis votre import initial.
+    </para>
+
+    <para id="x_c0">Les outils de gestion de source supportés par <literal role="hg-ext" moreinfo="none">convert</literal> sont :
+    </para>
+    <itemizedlist>
+      <listitem><para id="x_c1">Subversion</para></listitem>
+      <listitem><para id="x_c2">CVS</para></listitem>
+      <listitem><para id="x_c3">Git</para></listitem>
+      <listitem><para id="x_c4">Darcs</para></listitem>
+    </itemizedlist>
+
+    <para id="x_c5">En outre, <literal role="hg-ext" moreinfo="none">convert</literal> peut
+      exporter les modifications depuis Mercurial vers Subversion. Ceci rend
+      possible d'essayer Subversion en parallèle avant de choisir une
+      solution définitive, sans aucun risque de perte de données.
+    </para>
+
+    <para id="x_c6">La commande <command role="hg-ext-conver" moreinfo="none">convert</command> est très simple à utiliser.
+      Simplement, indiquez le chemin ou l'URL du dépôt de source, en lui
+      indiquant éventuellement le nom du chemin de destination, et la
+      conversion se met en route. Après cet import initial, il suffit de
+      relancer la commande encore une fois pour importer les modifications
+      effectuées depuis.
+    </para>
+  </sect1>
+
+  <sect1>
+    <title>Une courte histoire de la gestion de source</title>
+
+    <para id="x_c7">Le plus célèbre des anciens outils de gestion de source
+      est <emphasis remap="it">SCCS</emphasis> (Source Code Control System)},
+      que Marc Rochkind conçu dans les laboratoires de recherche de Bell
+      (<emphasis remap="it">Bell Labs</emphasis>), dans le début des années
+      70. <emphasis remap="it">SCCS</emphasis> ne fonctionnait que sur des
+      fichiers individuels, et obligeait chaque personne travaillant sur le
+      projet d'avoir un accès à un répertoire de travail commun, sur le même
+      système. Seulement une seule personne pouvait modifier un fichier au
+      même moment, ce fonctionnement était assuré par l'utilisation de verrou
+      (<quote>lock</quote>). Il était courant que des personnes verrouillent
+      des fichiers, et plus tard, oublient de le déverrouiller ; empêchant
+      n'importe qui d'autre de travailler sur ces fichiers sans l'aide de
+      l'administrateur...
+    </para>
+
+    <para id="x_c8">Walter Tichy a développé une alternative libre à
+      <emphasis remap="it">SCCS</emphasis> au début des années 80, qu'il
+      nomma <emphasis remap="it">RCS (Revision Control System)</emphasis>.
+      Comme <emphasis remap="it">SCCS</emphasis>, <emphasis remap="it">RCS</emphasis> demandait aux développeurs de travailler
+      sur le même répertoire partagé, et de verrouiller les fichiers pour se
+      prémunir de tout conflit issu de modifications concurrentes.
+    </para>
+
+    <para id="x_c9">Un peu plus tard dans les années 1980, Dick Grune utilisa
+      <emphasis remap="it">RCS</emphasis> comme une brique de base pour un
+      ensemble de scripts <emphasis remap="it">shell</emphasis> qu'il
+      intitula cmt, avant de la renommer en <emphasis remap="it">CVS
+        (Concurrent Versions System)</emphasis>.  La grande innovation de CVS
+      était que les développeurs pouvaient travailler simultanément et
+      indépendamment dans leur propre espace de travail. Ces espaces de
+      travail privés assuraient que les développeurs ne se marchent pas
+      mutuellement sur les pieds, comme c'était souvent le cas avec RCS et
+      SCCS. Tous les développeurs disposaient donc de leur copie de tous les
+      fichiers du projet, et ils pouvaient donc librement les modifier. Ils
+      devaient néanmoins effectuer la <quote>fusion</quote> (<emphasis remap="it"><quote>merge</quote></emphasis>) de leurs fichiers, avant
+      d'effectuer le <quote>commit</quote> de leurs modifications sur le dépôt
+      central.
+    </para>
+    
+    <para>Brian Berliner reprit les scripts de Grune's et les réécrit en C,
+      qu'il publia en 1989. Depuis, ce code a été modifié jusqu'à devenir la
+      version moderne de CVS. CVS a acquis ainsi la capacité de fonctionner
+      en réseau, transformant son architecture en client/serveur.
+      L'architecture de CVS est centralisée, seul le serveur a une copie de
+      l'historique du projet. L'espace de travail client ne contient qu'une
+      copie de la dernière version du projet, et quelques métadonnées pour
+      indiquer où le serveur se trouve. CVS a été un grand succès,
+      aujourd'hui il est probablement l'outil de gestion de contrôle le plus
+      utilisé au monde.
+    </para>
+    
+    <para>Au début des années 1990, Sun Microsystems développa un premier
+      outil de gestion de source distribué, nommé TeamWare. Un espace de
+      travail TeamWare contient une copie complète de l'historique du projet.
+      TeamWare n'a pas de notion de dépôt central. (CVS utilisait RCS pour le
+      stockage de l'historique, TeamWare utilisait SCCS).
+    </para>
+    
+    <para>Alors que les années 1990 avançaient, les utilisateurs ont pris
+      conscience d'un certain nombre de problèmes avec CVS. Il enregistrait
+      simultanément des modifications sur différents fichiers
+      individuellement, au lieu de les regrouper dans une seule opération
+      cohérente et atomique. Il ne gère pas bien sa hiérarchie de fichier, il
+      est donc assez aisé de créer le chaos en renommant les fichiers et les
+      répertoires. Pire encore, son code source est difficile à lire et à
+      maintenir, ce qui agrandit largement le <quote>niveau de
+        souffrance</quote> associé à la réparation de ces problèmes
+      d'architecture de manière prohibitive.
+    </para>
+    
+    <para>En 2001, Jim Blandy et Karl Fogel, deux développeurs qui avaient
+      travaillé sur CVS, initièrent un projet pour le remplacer par un outil
+      qui aurait une meilleure architecture et un code plus propre. Le
+      résultat, Subversion, ne quitte pas le modèle centralisé et
+      client/server de CVS, mais ajoute les opérations de
+      <quote>commit</quote> atomique sur de multiples fichiers, une meilleure
+      gestion des espaces de noms, et d'autres fonctionnalités qui en font un
+      meilleur outil que CVS. Depuis sa première publication, il est
+      rapidement devenu très populaire.
+    </para>
+    
+    <para>Plus ou moins simultanément, Graydon Hoare a commencé sur
+      l'ambitieux système de gestion distribué Monotone. Bien que Monotone
+      corrige plusieurs défauts de CVS tout en offrant une architecture
+      <quote>peer-to-peer</quote>, il va aussi plus loin que la plupart des
+      outils de révision de manière assez innovante. Il utilise des
+      <quote>hashs</quote> cryptographiques comme identifiants, et il a une
+      notion complète de <quote>confiance</quote> du code issu des
+      différentes sources.
+    </para>
+    
+    <para>Mercurial est né en 2005. Bien que très influencé par Monotone,
+      Mercurial se concentre sur la facilité d'utilisation, les performances
+      et la capacité à monter en charge pour de très gros projets.
+    </para>
+  
+  </sect1>
+
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch02 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:tour-basic">
+  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
+  <title>Une rapide présentation de Mercurial : les bases</title>
+
+  <sect1>
+    <title>Installer Mercurial sur votre système</title>
+
+    <para id="x_1">Des paquetages binaires de Mercurial sont disponibles pour la
+      plupart des systèmes d'exploitation, ce qui rend facile l'utilisation
+      immédiate de Mercurial sur votre ordinateur.</para>
+
+    <sect2>
+      <title>Windows</title>
+
+      <para id="x_c">La meilleur version de Mercurial pour Windows est
+        TortoiseHg, qui peut être téléchargée ici : <ulink url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>.
+        Ce logiciel n'a aucune dépendance exterieure; il fonctionne <quote>et
+          c'est tout</quote>. Il fournit aussi bien les outils en ligne de
+        commmande qu'une interface graphique.</para>
+ 
+    </sect2>
+
+    <sect2>
+      <title>Mac OS X</title>
+  
+      <para id="x_a">Lee Cantey publie un installeur de Mercurial pour Mac OS
+        X sur <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
+    </sect2>
+      
+    <sect2>
+      <title>Linux</title>
+
+      <para id="x_2">Parce que chaque distribution de Linux a ses propres
+        outils de gestion de paquets, politiques et rythmes de
+        développements, il est difficile de donner un ensemble
+        d'instructions unique pour installer les binaires de Mercurial. La
+        version de Mercurial avec laquelle vous vous retrouverez dépendra
+        grandement de l'activité de la personne en charge du paquetage pour
+        la distribution.</para>
+
+      <para id="x_3">Pour rester simple, je me concentrerai sur
+        l'installation de Mercurial en ligne de commande, sous les
+        distributions les plus courantes. La plupart des distributions
+        fournissent des gestionnaires graphiques de paquetage qui vous
+        permettront d'installer Mercurial en quelques clicks. Le paquetage
+        devrait se nommer <literal moreinfo="none">mercurial</literal>.</para>
+
+      <itemizedlist>
+        <listitem><para id="x_4">Ubuntu et Debian:</para>
+          <programlisting format="linespecific">apt-get install mercurial</programlisting></listitem>
+        <listitem><para id="x_5">Fedora:</para>
+          <programlisting format="linespecific">yum install mercurial</programlisting></listitem>
+        <listitem><para id="x_6">Gentoo:</para>
+           <programlisting format="linespecific">emerge mercurial</programlisting></listitem>
+        <listitem><para id="x_715">OpenSUSE:</para>
+          <programlisting format="linespecific">zypper install
+          mercurial</programlisting></listitem>
+      </itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title>Solaris</title>
+
+      <para id="x_09">SunFreeWare, à <ulink url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
+      fournit des paquets précompilés pour Mercurial.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Commencer à utiliser Mercurial</title>
+
+    <para id="x_e">Pour commencer, nous utiliserons la commande <command role="hg-cmd" moreinfo="none">hg version</command> pour vérifier si Mercurial est
+      installé proprement. Les informations affichées sur la version ne sont
+      pas réellement importantes en soit, c'est surtout de savoir si elles
+      s'affichent qui nous intéresse.</para>
+
+    <!-- BEGIN tour.version -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg version</userinput>
+Mercurial Distributed SCM (version 1.2.1)
+
+Copyright (C) 2005-2009 Matt Mackall &lt;mpm@selenic.com&gt; and others
+This is free software; see the source for copying conditions. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+</screen>
+<!-- END tour.version -->
+
+
+    <sect2>
+      <title>L'aide intégrée</title>
+
+      <para id="x_f">Mercurial fournit un système d'aide intégré, ce qui est
+        inestimable quand vous vous retrouvez coincé à essayer de vous
+        rappeler comment lancer une commande. Si vous êtes bloqué, exécutez
+        simplement <command role="hg-cmd" moreinfo="none">hg help</command>; elle affichera
+        une brève liste des commandes, avec une description pour chacune. Si
+        vous demandez de l'aide sur une commande spécifique (voir
+        ci-dessous), elle affichera des informations plus détaillées.</para>
+
+      <!-- BEGIN tour.help -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help init</userinput>
+hg init [-e CMD] [--remotecmd CMD] [DEST]
+
+create a new repository in the given directory
+
+    Initialize a new repository in the given directory. If the given
+    directory does not exist, it is created.
+
+    If no directory is given, the current directory is used.
+
+    It is possible to specify an ssh:// URL as the destination.
+    See 'hg help urls' for more information.
+
+options:
+
+ -e --ssh        specify ssh command to use
+    --remotecmd  specify hg command to run on the remote side
+
+use "hg -v help init" to show global options
+</screen>
+<!-- END tour.help -->
+
+
+      <para id="x_10">Pour un niveau d'informations encore plus détaillé 
+        (ce dont vous aurez rarement besoin), exécuter <command role="hg-cmd" moreinfo="none">hg 
+        help <option role="hg-opt-global">-v</option></command>.  L'option 
+        <option role="hg-opt-global">-v</option> est l'abréviation de 
+        <option role="hg-opt-global">--verbose</option>, et indique à Mercurial 
+        d'ficher plus d'informations que d'habitude.</para>
+
+     </sect2>
+  </sect1>
+  <sect1>
+    <title>Travailler avec un dépôt</title>
+
+    <para id="x_11">Avec Mercurial, tout se déroule au sein du 
+      <emphasis>dépôt</emphasis>. Le dépôt d'un projet contient tous 
+      les fichiers qui <quote>appartiennent</quote> au projet.</para>
+
+    <para id="x_12">Il n'y a rien de particulièrement magique au sujet de 
+      ce dépôt, c'est simplement une arborescence sur votre système de fichiers 
+      que Mercurial traite de manière spéciale. Vous pouvez renommer ou effacer 
+      ce répertoire à n'impporte quel moment, en utilisant la ligne de commande 
+      ou votre explorateur de fichiers.</para>
+
+    <sect2>
+      <title>Faire une copie locale de votre dépôt</title>
+      
+      <para id="x_13"><emphasis>Copier</emphasis> un dépôt est juste un 
+        peu spécial. Bien que vous puissiez utiliser une commande habituelle de 
+        copie pour copier votre dépôt, il vaut mieux utiliser une commande fournie par
+        Mercurial. Cette commande est appelée <command role="hg-cmd" moreinfo="none">hg clone</command>, 
+        car elle crée une copie identique à un dépôt existant.</para>
+
+      <!-- BEGIN tour.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone http://hg.serpentine.com/tutorial/hello</userinput>
+destination directory: hello
+requesting all changes
+adding changesets
+adding manifests
+adding file changes
+added 5 changesets with 5 changes to 2 files
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END tour.clone -->
+
+
+      <para id="x_67c">Un avantage de la commande <command role="hg-cmd" moreinfo="none">hg
+          clone</command> est que, comme nous l'avons vu ci dessus, elle nous
+        permet de faire de cloner les dépôts à travers le réseau. Un autre
+        est qu'elle se rappelle d'où a été cloné un dépôt, ce qui est utile
+        quand on veut mettre à jour le clone.</para>
+
+      <para id="x_14">Si votre opération de clonage réussit, vous devriez maintenant
+        avoir un répertoire local appelé <filename class="directory" moreinfo="none">hello</filename>. 
+        Ce répertoire contiendra quelques fichiers.</para>
+
+      <!-- BEGIN tour.ls -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
+total 4
+drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:05 hello
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls hello</userinput>
+Makefile  hello.c
+</screen>
+<!-- END tour.ls -->
+
+
+      <para id="x_15">Ces fichiers ont le même contenu et historique dans votre dépôt
+        qu'ils ont dans le dépôt que vous avez cloné.</para>
+
+      <para id="x_16">Chaque dépôt Mercurial est complet, autonome et
+        indépendant. Il contient sa propre copie privée des fichiers du
+        projet et de leur historique. Le clone d'un dépôt se souvient de la
+        localisation du dépôt à partir duquel il a été clôné, mais il ne
+        communique pas avec ce dernier, ou un autre, à moins que vous ne lui
+        demandiez.</para>
+
+      <para id="x_17">Ce que tout ceci signifie pour le moment est que nous
+        sommes libres d'expérimenter avec ce dépôt, confiants dans le fait
+        qu'il s'agit d'un <quote>bac à sable</quote> qui n'affectera personne
+        d'autre.</para>
+
+    </sect2>  
+    <sect2>
+      <title>Quel est le contenu d'un dépôt ?</title>
+
+      <para id="x_18">Prêtons plus attention un instant au contenu d'un dépôt. 
+        Nous voyons qu'il contient un répertoire nommé <filename class="directory" moreinfo="none">.hg
+        </filename>. C'est ici que Mercurial conserve toutes ses
+        métadonnées.</para>
+
+      <!-- BEGIN tour.ls-a -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -a</userinput>
+.  ..  .hg  Makefile  hello.c
+</screen>
+<!-- END tour.ls-a -->
+ 
+
+      <para id="x_19">Le contenu du répertoire <filename class="directory" moreinfo="none">.hg
+        </filename> et ses sous répertoires sont les seuls propres à Mercurial. 
+        Tous les autres fichiers et répertoires dans le dépôt sont à vous, et 
+        vous pouvez en faire ce que vous voulez.</para>
+
+      <para id="x_1a">Pour introduire un peu de terminologie, le répertoire 
+        <filename class="directory" moreinfo="none">.hg</filename> est un <quote>vrai</quote> 
+        dépôt, et tous les fichiers et les répertoires qui coexistent avec lui, 
+        sont désignés sous le nom <emphasis>espace de travail</emphasis>. Une 
+        manière facile de se rappeler cette distinction est de retenir que le 
+        <emphasis>dépôt</emphasis> contient l'<emphasis>historique</emphasis>
+        de votre projet, alors que l'<emphasis>espace de travail</emphasis> 
+        contient un "<emphasis>snapshot</emphasis>"  de votre projet à un certain 
+        point de son historique.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Une promenade dans l'historique</title>
+
+    <para id="x_1b">Une des premières choses que vous aurez envie 
+      de faire avec un nouveau dépôt, sera de comprendre son historique. 
+      La commande <command role="hg-cmd" moreinfo="none">hg log</command> vous donne une 
+      vue de l'historique.</para>
+
+    <!-- BEGIN tour.log -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
+changeset:   4:2278160e78d4
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:16:53 2008 +0200
+summary:     Trim comments.
+
+changeset:   3:0272e0d5a517
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:08:02 2008 +0200
+summary:     Get make to generate the final binary from a .o file.
+
+changeset:   2:fef857204a0c
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:05:04 2008 +0200
+summary:     Introduce a typo into hello.c.
+
+changeset:   1:82e55d328c8c
+user:        mpm@selenic.com
+date:        Fri Aug 26 01:21:28 2005 -0700
+summary:     Create a makefile
+
+changeset:   0:0a04b987be5a
+user:        mpm@selenic.com
+date:        Fri Aug 26 01:20:50 2005 -0700
+summary:     Create a standard "hello, world" program
+
+</screen>
+<!-- END tour.log -->
+
+
+    <para id="x_1c">Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
+      révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
+      appelons chacun de ces évènements enregistrés un <emphasis>changeset</emphasis>, parce
+      qu'il contient un ensemble de modifications sur plusieurs fichiers.</para>
+
+    <para id="x_1d">La commande <command role="hg-cmd" moreinfo="none">hg log</command> affiche 
+    ainsi ces informations :</para>
+
+    <itemizedlist>
+      <listitem><para id="x_1e"><literal moreinfo="none">changeset</literal> : Ce champ contient 
+        un nombre, séparé par deux points (:), d'une chaine hexadécimale. Il 
+        s'agit en fait d'<emphasis>identifiants</emphasis>  d'un changeset. Il y a 
+        deux identifiants car le numéro de la révision est plus court et plus à 
+        facile à saisir qu'une séquence hexadécimale.</para>
+      </listitem>
+      <listitem><para id="x_1f"><literal moreinfo="none">user</literal> : L'identité de la personne 
+        qui a créée ce  %%% laisser le terme anglais car il sera affiché
+        changeset. C'est un champ libre de forme, mais la plupart du
+        temps il contient le nom et l'email de la personne.</para>
+      </listitem>
+      <listitem><para id="x_20"><literal moreinfo="none">date</literal> : La date et l'heure à 
+        laquelle le \textit{changeset} a été créé, ainsi que le fuseau horaire dans 
+        lequelle il a été créé. (La date et l'heure sont locales à ce
+        \textit{fuseau}, elles indiquent donc quelle date et heure il était
+        pour la personne qui a créé ce changeset.</para>
+      </listitem>
+      <listitem><para id="x_21"><literal moreinfo="none">résumé</literal>: La première ligne du 
+        message que le créateur a associé à son changeset pour le décrire.</para>
+      </listitem>
+      <listitem><para id="x_67d">Certains changesets, comme le premier de la
+        liste ci-dessus ont un champ <literal moreinfo="none">tag</literal>. Le tag est une autre
+        façon d'identifier un changeset en lui donnant un nom simple à retenir.
+        (Le tag nommé <literal moreinfo="none">tip</literal> est spécial : il fait toujours
+        référence aux derniers changements dans le dépôt.)</para></listitem>
+    </itemizedlist>
+
+    <para id="x_22">Par défaut, la commande <command role="hg-cmd" moreinfo="none">hg log</command> 
+      n'affiche qu'un résumé, il manque beaucoup de détails.</para>
+
+    <para id="x_23">La figure <xref linkend="fig:tour-basic:history"/> fournit une 
+      représentation graphique de l'historique du dépôt <filename class="directory" moreinfo="none">hello
+      </filename>, pour rendre plus facile de voir dans quelle direction 
+      l'historique se <quote>déroule</quote>. Nous reviendrons régulièrement 
+      sur cette représentation dans ce chapitre et ceux qui suivent.</para>
+
+
+    <figure id="fig:tour-basic:history" float="0">
+      <title>Graphical history of the <filename class="directory" moreinfo="none">hello</filename> repository</title>
+      <mediaobject>
+        <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
+        <textobject><phrase>XXX add text</phrase></textobject>
+      </mediaobject>
+    </figure>
+
+
+    <sect2>
+      <title>Changesets, révisions, et collaboration</title>
+      
+      <para id="x_25">Comme l'anglais est réputé pour être un langage maladroit,
+        et que l'informatique est la source de bien des erreurs de terminologie
+        (pourquoi utiliser un seul terme quand quatre feront l'affaire ?), la
+        gestion de version a une variété de mots et de phrases qui veulent dire
+        la même chose. Si vous discutez d'historique de Mercurial avec d'autres
+        personnes, vous constaterez que souvent, le mot <quote>changeset</quote>
+        est contracté simplement en <quote>change</quote> ou (à l'écrit)
+        <quote>cset</quote>, et même parfois un changeset
+        <quote>révision</quote>, abrégé en <quote>rev</quote>.</para>
+
+      <para id="x_26">Bien que le <emphasis>mot</emphasis> que vous utilisez pour 
+        désigner le concept de changeset importe peu, l'<emphasis>identifiant</emphasis> 
+        que vous utilisez pour désigner un <emphasis>changeset</emphasis> spécifique 
+        a une grande importance. Rappelez vous que le champ changeset affiché par la
+        commande <command role="hg-cmd" moreinfo="none">hg log</command> identifie un changeset à
+        la fois avec un numéro de révision et une séquence hexadécimale.</para>
+
+      <itemizedlist>
+        <listitem><para id="x_27">Le numéro de révision est <emphasis>seulement 
+        valable dans ce dépôt</emphasis>,</para></listitem>
+        <listitem><para id="x_28">La séquence hexadécimale est un
+        <emphasis>identifiant permanent, et invariant</emphasis> qui 
+        pourra toujours être associé au changeset exact de <emphasis>chaque</emphasis> 
+        copie de votre dépôt.</para></listitem></itemizedlist>
+
+      <para id="x_29">La distinction est importante. Si vous envoyez un email 
+         à quelqu'un en parlant de la <quote>révision 33</quote>, il est très 
+         probable que sa révision 33 <emphasis>ne sera pas la même</emphasis> 
+         que la votre. La raison de ceci est que le numéro de révision dépend 
+         de l'ordre dans lequel les modifications sont arrivées dans le dépôt, 
+         et il n'y a aucune garantie que les mêmes changements soient arrivés 
+         dans le même ordre dans différents dépôts. Trois modifications
+         <literal moreinfo="none">a,b,c</literal> peuvent aisément apparaitre dans un dépôt 
+         comme <literal moreinfo="none">0,1,2</literal>, et dans un autre comme <literal moreinfo="none">0,2,1
+         </literal>.</para>
+
+      <para id="x_2a">Mercurial utilise les numéros de révision uniquement comme des raccourcis
+        pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un,
+        ou identifer un \textit{changeset} pour une quelconque raison (par exemple,
+        un rapport de \textit{bug}), utilisez la séquence hexadécimale.</para>
+
+    </sect2>
+    <sect2>
+      <title>Afficher une révision spécifique</title>
+
+      <para id="x_2b">Pour réduire la sortie de <command role="hg-cmd" moreinfo="none">hg log
+        </command> à une seule révision, utilisez l'option <option role="hg-opt-log">-r
+        </option> (ou <option role="hg-opt-log">--rev</option>). Vous pouvez utiliser
+        le numéro de révision ou la séquence hexadécimale comme identifiant, et
+        demander autant de révisions que vous le souhaitez.</para>
+
+      <!-- BEGIN tour.log-r -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 3</userinput>
+changeset:   3:0272e0d5a517
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:08:02 2008 +0200
+summary:     Get make to generate the final binary from a .o file.
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 0272e0d5a517</userinput>
+changeset:   3:0272e0d5a517
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:08:02 2008 +0200
+summary:     Get make to generate the final binary from a .o file.
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 1 -r 4</userinput>
+changeset:   1:82e55d328c8c
+user:        mpm@selenic.com
+date:        Fri Aug 26 01:21:28 2005 -0700
+summary:     Create a makefile
+
+changeset:   4:2278160e78d4
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:16:53 2008 +0200
+summary:     Trim comments.
+
+</screen>
+<!-- END tour.log-r -->
+
+
+      <para id="x_2c">Si vous voulez voir l'historique de plusieurs révisions
+        sans avoir à les énumérer, vous pouvez utiliser la <emphasis>intervalle
+        de numérotation</emphasis> qui vous permet d'exprimer l'idée <quote>je
+        veux toutes les révisions entre $a$ et $b$, inclus</quote></para>
+
+      <!-- BEGIN tour.log.range -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 2:4</userinput>
+changeset:   2:fef857204a0c
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:05:04 2008 +0200
+summary:     Introduce a typo into hello.c.
+
+changeset:   3:0272e0d5a517
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:08:02 2008 +0200
+summary:     Get make to generate the final binary from a .o file.
+
+changeset:   4:2278160e78d4
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:16:53 2008 +0200
+summary:     Trim comments.
+
+</screen>
+<!-- END tour.log.range -->
+
+
+      <para id="x_2d">Mercurial respecte aussi l'ordre dans lequel vous spécifiez
+        les révisions, ainsi <command role="hg-cmd" moreinfo="none">hg log -r 2:4</command>
+        affichera <literal moreinfo="none">2,3,4</literal> alors que <command role="hg-cmd" moreinfo="none">hg
+        log -r 4:2</command> affichera <literal moreinfo="none">4,3,2</literal>.</para>
+
+    </sect2>  
+    <sect2>
+      <title>Informations détaillées</title>
+
+      <para id="x_2e">Le résumé affiché par <command role="hg-cmd" moreinfo="none">hg log</command> 
+        est suffisant si vous savez déjà ce que vous cherchez. En 
+        revanche, vous aurez probablement besoin de voir une description 
+        complète du changement, ou une liste des fichiers modifiés si vous 
+        cherchez à déterminer qu'un changeset est bien celui que vous
+        recherchez. L'option \hgopt{-v} de la commande <command role="hg-cmd" moreinfo="none">hg 
+        log</command> (ou <option role="hp-opt-global">--verbose</option>) vous 
+        donne ces informations supplémentaires.</para>
+
+      <!-- BEGIN tour.log-v -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -r 3</userinput>
+changeset:   3:0272e0d5a517
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:08:02 2008 +0200
+files:       Makefile
+description:
+Get make to generate the final binary from a .o file.
+
+
+</screen>
+<!-- END tour.log-v -->
+
+
+      <para id="x_2f">Si vous voulez voir à la fois la description 
+        et le contenu d'une modification, ajouter l'option <option role="hg-opt-log">-p</option> (ou <option role="hg-opt-log">
+        --patch</option>). Ceci affiche le contenu d'une modification 
+        comme un <emphasis>diff unifié</emphasis>
+        <!-- \footnote{NdT: \textit{unified diff}} -->
+        (si vous n'avez jamais vu de diff unifié avant, consultez la 
+        section <xref linkend="sec:mq:patch"/> pour un rapide 
+        survol).</para>
+
+      <!-- BEGIN tour.log-vp -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -p -r 2</userinput>
+changeset:   2:fef857204a0c
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:05:04 2008 +0200
+files:       hello.c
+description:
+Introduce a typo into hello.c.
+
+
+diff -r 82e55d328c8c -r fef857204a0c hello.c
+--- a/hello.c	Fri Aug 26 01:21:28 2005 -0700
++++ b/hello.c	Sat Aug 16 22:05:04 2008 +0200
+@@ -11,6 +11,6 @@
+ 
+ int main(int argc, char **argv)
+ {
+-	printf("hello, world!\n");
++	printf("hello, world!\");
+ 	return 0;
+ }
+
+</screen>
+<!-- END tour.log-vp -->
+
+
+      <para id="x_67e">L'option <option role="hg-opt-log">-p</option> est
+        incroyablement utile, il est donc important dans s'en rappeller.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Tout sur les options de commandes</title>
+    
+    <para id="x_30">Avant d'aller plus loin sur le fonctionnement 
+      des commandes de Mercurial, étudions un moment comment elles 
+      fonctionnent de manière générale. Vous trouverez ça probablement 
+      utile pour la suite de notre parcours.</para>
+
+    <para id="x_31">Mercurial utilise une approche directe et cohérente 
+      pour interpréter les options que vous passez aux commandes. Il suit une
+      convention commune à la plupart des systèmes Unix et Linux modernes.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_32">Chaque option a un nom complet. Par exemple, 
+        comme nous l'avons déjà vu, la commande <command role="hg-cmd" moreinfo="none">hg 
+        log</command> accepte l'option <option role="hg-opt-log">--rev
+        </option>.</para>
+      </listitem>
+      <listitem><para id="x_33">La plupart des options disposent de 
+        noms abrégés. Aussi, au lieu d'utiliser <option role="hg-opt-log">--rev
+        </option>, vous pouvez utiliser <option role="hg-opt-log">-r</option>. 
+        (Les options qui  n'ont pas de noms abrégés sont généralement 
+        rarement utilisées).</para>
+      </listitem>
+      <listitem><para id="x_34">Les noms complets commencent par deux 
+        tirets (i.e. <option role="hg-opt-log">--rev</option>),
+        alors que les options courtes commencent avec un seul (i.e. 
+        <option role="hg-opt-log">-r</option>).</para>
+      </listitem>
+     <listitem><para id="x_35">Les noms des options sont cohérents 
+       entre les commandes. Par exemple, chaque commande qui accepte 
+       un changeset ID ou un numéro de révision accepte aussi <option role="hg-opt-log">-r</option> et <option role="hg-opt-log">--rev
+       </option> comme arguments.</para>
+     </listitem>
+   </itemizedlist>
+
+   <para id="x_36">Dans les exemples de ce livre, j'utilise les noms abrégés 
+     plutôt que les noms complets. Ceci est une préférence personnelle, pas 
+     une recommandation.</para>
+
+   <para id="x_37">La plupart des commandes qui affichent une quelconque sortie 
+     à l'écran, afficheront davantage avec l'option <option role="hg-opt-global">
+     -v</option> (ou <option role="hg-opt-global">--verbose</option>), et
+     moins avec l'option <option role="hg-opt-global">-q</option> (ou 
+     <option role="hg-opt-global">--quiet</option>).</para>
+
+    <note>
+      <title>Option naming consistency</title>
+      
+      <para id="x_680">Presque toujours, les commandes de Mercurial utilisent
+      des noms d'options cohérentes pour référer à des concepts identiques.
+      Par exemple, si une commande concerne les changesets, vous les
+      identifierez toujours avec l'option <option role="hg-opt-log">-r</option>.
+      Cette utilisation cohérente des noms d'options permet de mémoriser plus
+      facilement quelles options accepte une commande.</para>
+   </note>
+
+
+  </sect1>
+  <sect1>
+    <title>Faire et vérifier des modifications</title>
+
+    <para id="x_38">Maintenant que nous avons une bonne idée des 
+      commandes pour consulter l'historique de Mercurial, regardons 
+      comment faire des modifications et les examiner.</para>
+     
+    <para id="x_39">La première chose que nous allons faire c'est isoler notre
+      expérience dans un dépôt à part. Nous allons utiliser la commande <command role="hg-cmd" moreinfo="none">hg clone</command>, mais nous n'avons pas besoin de faire
+      une copie de dépôt distant. Comme nous avons déjà une copie locale, nous
+      pouvons juste faire un clone de celle-ci à la place. C'est beaucoup plus
+      rapide que de faire une copie à travers le réseau, et un dépôt cloné
+      localement prend également moins d'espace disque<footnote>
+      <para id="x_681">L'économie d'espace disque apparait clairement quand les
+        dépôts source et destination sont sur le même système de fichier, où, dans
+        ce cas, Mercurial utilisera des liens physiques pour effectuer des partages
+        copie-lors-des-écritures de ses métadonnées internes. Si cette explication
+        ne signifie rien pour vous, ne vous inquietez pas : tout ceci se passe de
+        manière transparente et automatiquement. Vous n'avez pas du tout besoin de
+        comprendre ceci.</para></footnote>.</para>
+  
+    <!-- BEGIN tour.reclone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-hello</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
+</screen>
+<!-- END tour.reclone -->
+
+
+    <para id="x_3a">On notera au passage qu'il est souvent considéré comme
+      une bonne pratique de conserver une copie <quote>immaculée</quote>
+      du dépôt distant, à partir de laquelle vous pourrez faire des 
+      copies locales temporaires pour créer des <quote>bacs à sable</quote> 
+      pour chaque tâche sur laquelle vous souhaitez travailler. Ceci 
+      vous permet de travailler sur plusieurs choses en parallèle, 
+      chacune isolée les unes des autres en attendant que ces tâches 
+      soient finies et que vous soyez prêt à les réintégrer. Parce 
+      que les copies locales sont peu coûteuses, il est très rapide 
+      de créer ou détruire des dépôts dès que vous n'en avez plus
+      besoin.</para>
+
+    <para id="x_3b">Dans notre dépôt <filename class="directory" moreinfo="none">my-hello</filename>, nous avons un fichier
+      <filename moreinfo="none">hello.c</filename> qui contient le classique <quote>hello,
+        world</quote>.</para>
+   
+    <!-- BEGIN tour.cat1 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
+/*
+ * Placed in the public domain by Bryan O'Sullivan.  This program is
+ * not covered by patents in the United States or other countries.
+ */
+
+#include &lt;stdio.h&gt;
+
+int main(int argc, char **argv)
+{
+	printf("hello, world!\");
+	return 0;
+}
+</screen>
+<!-- END tour.cat1 -->
+
+
+    <para id="x_682">Editons ce fichier pour qu'il affiche une autre ligne
+      sur la sortie standard.</para>
+    
+    <!-- BEGIN tour.cat2 -->
+<screen format="linespecific"># ... edit edit edit ...
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
+/*
+ * Placed in the public domain by Bryan O'Sullivan.  This program is
+ * not covered by patents in the United States or other countries.
+ */
+
+#include &lt;stdio.h&gt;
+
+int main(int argc, char **argv)
+{
+	printf("hello, world!\");
+	printf("hello again!\n");
+	return 0;
+}
+</screen>
+<!-- END tour.cat2 -->
+
+
+    <para id="x_3c">La commande Mercurial <command role="hg-cmd" moreinfo="none">hg
+        status</command> nous dira ce que Mercurial sait des fichiers du
+      dépôts.</para>
+
+    <!-- BEGIN tour.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
+Makefile  hello.c
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+M hello.c
+</screen>
+<!-- END tour.status -->
+
+
+    <para id="x_3d">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
+      n'affichera pas le contenu des fichiers, mais une ligne commençant par
+      <quote><literal moreinfo="none">M</literal></quote> pour <filename moreinfo="none">hello.c</filename>.
+      A moins que vous lui demandiez, la commande <command role="hg-cmd" moreinfo="none">hg
+        status</command> n'affichera aucune information sur les fichiers que
+      vous n'avez pas modifiés.</para>
+ 
+    <para id="x_3e">Le <quote><literal moreinfo="none">M</literal></quote> indique que
+      Mercurial a remarqué que nous avons modifié le fichier
+      <filename moreinfo="none">hello.c</filename>. Nous n'avons pas besoin
+      <emphasis>d'informer</emphasis> Mercurial que nous allons modifier un
+      fichier avant de commencer à le faire, ou que nous avons modifié un
+      fichier après avoir commencé à le faire, il est capable de découvrir ça
+      tout seul. </para>
+
+    <para id="x_3f">C'est déjà pratique de savoir que nous avons modifié le
+      fichier <filename moreinfo="none">hello.c</filename>, mais nous préférerions savoir
+      exactement <emphasis>ce que</emphasis> nous avons changé. Pour ceci, nous
+      utilisons la commande <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
+
+    <!-- BEGIN tour.diff -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+diff -r 2278160e78d4 hello.c
+--- a/hello.c	Sat Aug 16 22:16:53 2008 +0200
++++ b/hello.c	Sun Aug 16 14:05:26 2009 +0000
+@@ -8,5 +8,6 @@
+ int main(int argc, char **argv)
+ {
+ 	printf("hello, world!\");
++	printf("hello again!\n");
+ 	return 0;
+ }
+</screen>
+<!-- END tour.diff -->
+
+
+    <tip>
+      <title>Comprendre les patches</title>
+   
+      <para id="x_683">Penser à jeter un oeil à <xref linkend="sec:mq:patch"/> si vous n'arrivez pas à lire la sortie
+        ci-dessus.</para>
+    </tip>
+  </sect1>
+  <sect1>
+    <title>Enregister vos modifications dans une nouvelle révision</title>
+   
+    <para id="x_40">Nous pouvons modifier des fichiers, compiler et tester
+      nos modifications, et utiliser les commandes <command role="hg-cmd" moreinfo="none">hg
+        status</command> et <command role="hg-cmd" moreinfo="none">hg diff</command> pour
+      voir les modifications effectuées, jusqu'à ce que nous soyons assez
+      satisfaits pour décider d'enregistrer notre travail dans un
+      \textit{changeset}.</para>
+
+    <para id="x_41">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
+      vous laisse créer une nouvelle révision, nous désignerons généralement
+      cette opération par <quote>faire un commit</quote> ou
+      <quote>committer</quote>.</para>
+
+    <sect2>
+    <title>Définir le nom d'utilisateur</title>
+
+      <para id="x_42">Quand vous exécutez la commande <command role="hg-cmd" moreinfo="none">hg commit</command> pour la première fois, il n'est
+        pas garanti qu'elle réussisse du premier coup. En effet, Mercurial
+        enregistre votre nom et votre adresse avec chaque modification que
+        vous effectuez, de manière à ce que vous soyez capable (ou d'autres
+        le soient) de savoir qui a fait quelle modification. Mercurial essaye
+        automatiquement de découvrir un nom d'utilisateur qui ait un minimum
+        de sens pour effectuer l'opération de commit avec. Il va essayer
+        chacune des méthodes suivantes, dans l'ordre :</para>
+
+      <orderedlist inheritnum="ignore" continuation="restarts">
+        <listitem><para id="x_43">Si vous spécifiez l'option <option role="hg-opt-commit">-u</option> avec la commande <command role="hg-cmd" moreinfo="none">hg commit</command>, suivi d'un nom
+            d'utilisateur, ceci aura toujours la priorité sur les autres
+            méthodes ci dessous.</para></listitem>
+        <listitem><para id="x_44">Si vous avez défini une variable
+            d'environnement <envar>HGUSER</envar>, c'est cette valeur qui est
+            alors utilisée.</para></listitem>
+        <listitem><para id="x_45">Si vous créez un fichier nommé <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire
+            \textit{home}, avec une entrée <envar role="rc-item-ui">username</envar>, c'est la valeur associée
+            qui sera utilisée. Pour voir à quoi ressemble le contenu de ce
+            fichier regardez la section <xref linkend="sec:tour-basic:username"/>
+            ci-dessous.</para></listitem>
+        <listitem><para id="x_46">Si vous avez défini une variable
+            d'environnement <envar>EMAIL</envar> celle ci sera utilisée
+            ensuite.</para></listitem>
+        <listitem><para id="x_47">Enfin, Mercurial interrogera votre système
+            pour trouver votre nom d'utilisateur local ainsi que le nom de la
+            machine hôte, et il fabriquera un nom d'utilisateur à partir de
+            ces données. Comme il arrive souvent que ce genre de noms soit
+            totalement inutile, il vous préviendra en affichant un message
+            d'avertissement.</para></listitem>
+      </orderedlist>
+   
+      <para id="x_48">Si tous ces mécanismes échouent, Mercurial n'exécutera
+        pas la commande, affichant un message d'erreur. Dans ce cas, il ne
+        vous laissera pas effectuer de commit tant que vous n'aurez pas
+        défini un nom d'utilisateur.</para>
+   
+      <para id="x_49">Vous devriez penser à utiliser la variable
+        d'environement <envar>HGUSER</envar> et l'option <option role="hg-opt-commit">-u</option> comme moyen pour
+        <emphasis>changer</emphasis> le nom d'utilisateur par défaut. Pour
+        une utilisation normale, la manière la plus simple et robuste
+        d'opérer est de créer un fichier <filename role="special" moreinfo="none">.hgrc</filename>, voir ci-dessous pour  les détails
+        à ce sujet.</para>
+
+      <sect3 id="sec:tour-basic:username">
+        <title>Créer un fichier de configuration pour Mercurial</title>
+
+        <para id="x_4a">Pour définir un nom d'utilisateur, utilisez votre 
+          éditeur de texte favori pour créer un fichier <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire home. 
+          Mercurial va utiliser ce fichier pour retrouver votre 
+          configuration personnelle. Le contenu initial devrait
+          ressembler à ceci :</para>
+   
+        <tip>
+          <title><quote>Home directory</quote> sous Windows</title>
+   
+          <para id="x_716">Quand on parle de répertoire home, sur une version
+            anglaise d'une installation de Windows, il s'agira habituellement
+            d'un répertoire nommée comme votre nom dans <filename moreinfo="none">C:\Documents 
+              and Settings</filename>. Vous pouvez trouver de quelle répertoire
+            il s'agit en lançant une fenêtre d'interpréteur de commande et en
+            exécutant la commande suivante :</para>
+          
+          <screen format="linespecific"><prompt moreinfo="none">C:\</prompt> <userinput moreinfo="none">echo
+              %UserProfile</userinput></screen>
+        </tip>
+   
+        <programlisting format="linespecific"># This is a Mercurial configuration file.
+[ui]
+username = Firstname Lastname &lt;email.address@domain.net&gt;</programlisting>
+
+        <para id="x_4b">La ligne avec <literal moreinfo="none">[ui]</literal> commence une
+          <emphasis>section</emphasis> du fichier de configuration, ainsi la ligne
+          <quote><literal moreinfo="none">username = ...</literal></quote> signifie <quote>
+            définir la valeur de l'élément <literal moreinfo="none">username</literal> dans la
+            section <literal moreinfo="none">ui</literal></quote>. Une section continue jusqu'à ce
+          qu'une nouvelle commence, ou que la fin du fichier soit atteinte.
+          Mercurial ignore les lignes vides et traite tout texte situé à la suite
+          d'un <quote><literal moreinfo="none">#</literal></quote> jusqu'à la fin de la ligne
+          comme un commentaire.</para>
+
+      </sect3>
+      <sect3>
+        <title>Choisir un nom d'utilisateur</title>
+ 
+        <para id="x_4c">Vous pouvez utiliser n'importe quelle valeur 
+          pour votre <literal moreinfo="none">username</literal>, car cette information 
+          est destinée à d'autres personnes et non à être interprétée 
+          par Mercurial. La convention que la plupart des personnes
+          suivent est d'utiliser leurs noms suivies de leurs adresses emails,
+          comme montré ci-dessus :</para>
+        <note>
+          <para id="x_4d">Le mécanisme interne du serveur web intégré à Mercurial,
+            masque les adresses emails, pour rendre plus difficile leurs
+            récupérations par les outils utilisés par les spammmers.
+            Ceci réduit la probabilité que de recevoir encore plus de
+            spam si vous vous publiez un dépôt sur internet.</para>
+        </note>
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Rédiger un message de \textit{commit}</title>
+  
+      <para id="x_4e">Lorsqu'on effectue une opération de commit, Mercurial
+        lance automatiquement un éditeur de texte pour permettre de saisir
+        un message qui décrira les modifications effectuées dans cette
+        révision. Ce message est nommé le <emphasis>message de commit</emphasis>. 
+        Ce sera un enregistrement pour tout lecteur expliquant le pourquoi 
+        et le comment de vos modifications, et il sera affiché par la 
+        commande <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
+ 
+      <!-- BEGIN tour.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit</userinput>
+</screen>
+<!-- END tour.commit -->
+ 
+  
+      <para id="x_4f">L'éditeur que la commande <command role="hg-cmd" moreinfo="none">hg 
+          commit</command> déclenche ne contiendra qu'une ligne vide suivi 
+        d'un certain nombre de lignes commençant par <quote><literal moreinfo="none">HG:
+        </literal></quote>.</para>
+    
+        <programlisting format="linespecific">
+    This is where I type my commit comment.
+    
+    HG: Enter commit message.  Lines beginning with 'HG:' are removed.
+    HG: --
+    HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+    HG: branch 'default'
+    HG: changed hello.c</programlisting>
+
+
+      <para id="x_50">Mercurial ignore les lignes qui commencent 
+        avec <quote><literal moreinfo="none">HG:</literal></quote>, il ne les 
+        utilise que pour nous indiquer quels fichiers modifiés il se
+        prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a
+        aucune conséquence sur l'opération de commit.
+      </para>
+
+    </sect2>
+    <sect2>
+      <title>Rédiger un message \textit{approprié}</title>
+  
+      <para id="x_51">Comme <command role="hg-cmd" moreinfo="none">hg log</command> n'affiche
+        que la première ligne du message de commit par défaut, il est souvent
+        considéré comme une bonne pratique de rédiger des messages de commit
+        qui tiennent sur une seule ligne. Voilà un exemple concret de message 
+        de commit qui <emphasis>ne suit pas</emphasis> cette directive, et
+        qui a donc un résumé peu lisible.</para>
+
+      <programlisting format="linespecific">
+changeset:   73:584af0e231be
+user:        Censored Person &lt;censored.person@example.org&gt;
+date:        Tue Sep 26 21:37:07 2006 -0700
+summary:     include buildmeister/commondefs.   Add an exports and install
+      </programlisting>
+  
+      <para id="x_52">A ce sujet, il faut noter qu'il n'existe pas de règle 
+        absolue dans ce domaine. Mercurial lui-même n'interprète pas les 
+        contenus des messages de commit, ainsi votre projet est libre de 
+        concevoir différentes politiques de mise en page des messages.</para>
+      
+      <para id="x_53">Ma préférence personnelle va au message court, mais 
+        informatif, qui offre des précisions supplémentaires par rapport à ce 
+        que pourrait m'apprendre une commande <command role="hg-cmd" moreinfo="none">hg log 
+          --patch</command>.</para>
+      
+      <para id="x_55">Si vous exécutez la commande <command role="hg-cmd" moreinfo="none">hg
+          commit</command> sans aucun argument, elle enregistre tous les 
+        changements qui ont été fait, et qui sont indiqué par les commandes
+        <command role="hg-cmd" moreinfo="none">hg status</command> et  <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
+      
+      <note>
+        <title>Une surprise pour les utilisateurs habitués à Subversion</title>
+   
+        <para id="x_717">Comme n'importe quel autre commande de Mercurial, si
+          vous soumettez pas de manière explicite les noms des fichiers à
+          committer à la commande <command role="hg-cmd" moreinfo="none">hg commit</command>, elle
+          va travailler sur l'ensemble du répertoire de travail. Soyez conscient
+          de ceci si vous venez du monde Subversion ou CVS, car vous pourriez
+          attendre qu'elle opère uniquement le répertoire courant et ses sous
+          répertoires.</para>
+      </note>
+    </sect2>
+    <sect2>
+      <title>Annuler un \textit{commit}</title>
+
+      <para id="x_54">Si, en rédigeant le message, vous décidez que 
+        finalement vous ne voulez pas effectuer ce commit, il suffit 
+        de quitter simplement l'éditeur sans sauver. Ceci n'aura aucune 
+        conséquence sur le dépôt ou les fichiers du répertoire de 
+        travail.</para>
+    </sect2>
+  
+    <sect2>
+      <title>Admirer votre travail</title>
+  
+      <para id="x_56">Une fois que votre \textit{commit} est terminé, vous
+        pouvez utiliser la commande <command role="hg-cmd" moreinfo="none">hg tip</command>
+        pour afficher le \textit{changeset} que vous venez de créer. Cette
+        commande produit  une sortie à l'écran qui est identique à celle du
+        <command role="hg-cmd" moreinfo="none">hg log</command>, mais qui n'affiche que la
+        dernière révision du dépôt.</para>
+ 
+      <!-- BEGIN tour.tip -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -vp</userinput>
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+files:       hello.c
+description:
+Added an extra line of output
+
+
+diff -r 2278160e78d4 -r c94f208d1dfb hello.c
+--- a/hello.c	Sat Aug 16 22:16:53 2008 +0200
++++ b/hello.c	Sun Aug 16 14:05:26 2009 +0000
+@@ -8,5 +8,6 @@
+ int main(int argc, char **argv)
+ {
+ 	printf("hello, world!\");
++	printf("hello again!\n");
+ 	return 0;
+ }
+
+</screen>
+<!-- END tour.tip -->
+ 
+  
+      <para id="x_57">On fait couramment référence à la dernière révision 
+        du dépôt comme étant la <emphasis>révision tip</emphasis>, ou plus
+        simplement le <emphasis>tip</emphasis>.</para>
+  
+      <para id="x_684">Au passage, la commande <command role="hg-cmd" moreinfo="none">hg
+          tip</command> accepte la plupart des options qu'accepte 
+        <command role="hg-cmd" moreinfo="none">hg log</command>. Ainsi <option role="hg-opt-global">-v</option> ci dessus implique <quote>soit
+          verbeux</quote>, <option role="hg-opt-tip">-p</option>
+        veux dire <quote>affiche le patch</quote>. L'utilisation de l'option
+        <option role="hg-opt-tip">-p</option> pour afficher un patch est un
+        autre exemple de la cohérence des commandes évoquée plus tôt.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Partager ses modifications</title>
+
+    <para id="x_58">Nous avons mentionné plus haut que les dépôts 
+      de Mercurial sont autosuffisants. Ce qui signifie que la nouvelle
+      révision que vous venez de créer existe seulement dans votre 
+      répertoire <filename class="directory" moreinfo="none">my-hello</filename>. Étudions 
+      comment propager cette modification dans d'autres dépôts.</para>
+
+    <sect2 id="sec:tour:pull">
+      <title>Récupérer les modifications d'autres dépôts</title>
+
+      <para id="x_59">Pour commencer, construisons un clone de notre dépôt 
+        <filename class="directory" moreinfo="none">hello</filename> qui ne contiendra pas 
+        le changement que nous venons d'effectuer. Nous l'appellerons notre 
+        dépôt temporaire <filename class="directory" moreinfo="none">hello-pull</filename>.</para>
+ 
+      <!-- BEGIN tour.clone-pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-pull</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END tour.clone-pull -->
+
+ 
+      <para id="x_5a">Nous allons utiliser la commande <command role="hg-cmd" moreinfo="none">hg pull</command> pour envoyer les modifications
+        depuis <filename class="directory" moreinfo="none">my-hello</filename> dans <filename class="directory" moreinfo="none">hello-pull</filename>. Néanmoins, récupérer
+        aveuglement des modifications depuis un dépôt a quelque chose d'un
+        peu effrayant. Mercurial propose donc une commande <command role="hg-cmd" moreinfo="none">hg incoming</command> qui permet de savoir quelles
+        modifications la commande <command role="hg-cmd" moreinfo="none">hg pull</command>
+        <emphasis>pourrait</emphasis> entraîner dans notre dépôt, et ceci
+        sans effectuer réellement de modification dessus.</para>
+
+      <!-- BEGIN tour.incoming -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello-pull</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg incoming ../my-hello</userinput>
+comparing with ../my-hello
+searching for changes
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.incoming -->
+ 
+  
+      <para id="x_5c">Apporter les modifications rapatriées dans un dépôt se
+        résume donc à exécuter la commande <command role="hg-cmd" moreinfo="none">hg
+          pull</command>, et préciser depuis quel dépôt effectuer le <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
+      
+      <!-- BEGIN tour.pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   4:2278160e78d4
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:16:53 2008 +0200
+summary:     Trim comments.
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
+pulling from ../my-hello
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+(run 'hg update' to get a working copy)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.pull -->
+
+  
+      <para id="x_5d">Comme vous le voyez avec une sortie avant et après de la
+        commande <command role="hg-cmd" moreinfo="none">hg tip</command>, nous avons réussi à
+        récupérer aisément les modifications dans notre dépôt. Il reste néanmoins
+        quelque chose à faire avant de placer ces modifications dans l'espace de
+        travail.</para>
+   
+      <tip>
+        <title>Récupérer des changements précis</title>
+   
+        <para id="x_5b">Il est possible à cause du délai entre l'exécution de la
+          commande <command role="hg-cmd" moreinfo="none">hg incoming</command> et l'exécution de
+          la commande <command role="hg-cmd" moreinfo="none">hg pull</command>, que vous ne
+          puissiez pas voir toutes les modifications que vous rapporterez d'un
+          autre dépôt. Supposons que vous récupériez les modifications d'un dépôt
+          situé quelque part sur le réseau. Alors que vous regardez le résultat de
+          la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>, et avant que
+          vous ne décidiez de récupérer ces modifications, quelqu'un peut ajouter
+          de nouvelles révisions dans le dépôt distant. Ce qui signifie que vous
+          récupérez plus de révision que ce que vous aviez regardées en utilisant
+          la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>.</para>
+
+        <para id="x_718">Si vous voulez seulement récupérer ce que vous aviez
+          vérifier à l'aide de la commande <command role="hg-cmd" moreinfo="none">hg
+            incoming</command>, ou que pour d'autres raisons vous souhaitiez ne
+          récupérer qu'un sous ensemble des révisions supplémentaires
+          disponibles, indiquant simplement les modifications que vous souhaitez
+          récupérer par leurs ID de révision, soit <command moreinfo="none">hg pull
+            -r7e95bb</command>. </para>
+      </tip>
+  
+    </sect2>
+    <sect2>
+      <title>Mise à jour de l'espace de travail</title>
+  
+      <para id="x_5e">Nous avons jusqu'à maintenant grossièrement défini la
+        relation entre un dépôt et un espace de travail. La commande <command role="hg-cmd" moreinfo="none">hg pull</command> que nous avons exécutée dans la section 
+        <xref linkend="sec:tour:pull"/> a apporté des modifications, que nous
+        avons vérifiées, dans notre dépôt, mais il n'y a aucune trace de ces
+        modifications dans notre espace de travail. En effet, <command role="hg-cmd" moreinfo="none">hg pull</command> ne touche pas (par défaut) à l'espace
+        de travail. C'est la commande <command role="hg-cmd" moreinfo="none">hg update</command>
+        qui s'en charge.</para>
+ 
+      <!-- BEGIN tour.update -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
+	printf("hello, world!\");
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update tip</userinput>
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
+	printf("hello, world!\");
+	printf("hello again!\n");
+</screen>
+<!-- END tour.update -->
+
+  
+      <para id="x_5f">Il peut sembler un peu étrange que la commande <command role="hg-cmd" moreinfo="none">hg pull</command> ne mette pas à jour l'espace de travail
+        automatiquement. Il y a en fait une très bonne raison à cela : vous
+        pouvez utilisez la commande <command role="hg-cmd" moreinfo="none">hg update</command>
+        pour mettre à jour votre espace de travail à l'état dans lequel il était 
+        à <emphasis>n'importe quelle révision</emphasis> de l'historique du dépôt. 
+        Si vous aviez un espace de travail contenant une ancienne
+        révision—pour chercher l'origine d'un bug, par exemple—et
+        que vous effectuiez un <command role="hg-cmd" moreinfo="none">hg pull</command> qui
+        mettrait à jour automatiquement votre espace de travail, vous ne seriez
+        probablement pas très satisfait.</para>
+  
+      <para id="x_60">Néanmoins, comme les opérations de pull sont très souvent
+        suivies d'un update, Mercurial vous permet de combiner les
+        deux aisément en passant l'option <option role="hg-opt-pull">-u</option> 
+        à la commande <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
+  
+      <para id="x_61">Si vous étudiez de nouveau la sortie de la commande <command role="hg-cmd" moreinfo="none">hg pull</command> dans la section <xref linkend="sec:tour:pull"/> quand nous l'avons exécutée sans l'option
+        <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a
+        affiché un rappel assez utile : vous devez encore effectuer une
+        opération pour mettre à jour votre espace de travail.</para>
+
+      <para id="x_62">Pour découvrir sur quelle révision de l'espace de 
+        travail on se trouve, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
+          parents</command>.</para>
+ 
+      <!-- BEGIN tour.parents -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.parents -->
+
+   
+      <para id="x_63">Si vous regardez de nouveau le dessin <xref linkend="fig:tour-basic:history"/>, vous verrez les flèches reliant
+        entre elles les révisions. Le nœud d'où la flèche
+        <emphasis>part</emphasis> est dans chaque cas un parent,
+        et le nœud où la flèche <emphasis>arrive</emphasis> est un
+        enfant.</para>
+
+      <para id="x_64">Pour mettre à jour l'espace de travail d'une révision
+        particulière, indiquez un numéro de révision ou un \textit{changeset
+        ID} à la commande <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
+  
+      <!-- BEGIN tour.older -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update 2</userinput>
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   2:fef857204a0c
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sat Aug 16 22:05:04 2008 +0200
+summary:     Introduce a typo into hello.c.
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.older -->
+
+   
+      <para id="x_65">Si vous ne précisez pas de manière explicite de numéro 
+        de révision la commande <command role="hg-cmd" moreinfo="none">hg update</command>
+        mettra à jour votre espace de travail avec le contenu de la révison
+        \textit{tip}, comme montré dans l'exemple ci dessus lors du second
+        appel à <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
+    
+    </sect2>
+    <sect2>
+      <title>Transférer les modifications vers un autre dépôt</title>
+  
+      <para id="x_66">Mercurial vous laisse transférer les modifications vers
+        un autre dépôt, depuis votre dépôt actuel. Comme dans l'exemple du
+        <command role="hg-cmd" moreinfo="none">hg pull</command> ci-dessus, nous allons créer
+        un dépôt temporaire vers lequel transférer nos modifications.</para>
+        
+      <!-- BEGIN tour.clone-push -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-push</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END tour.clone-push -->
+
+  
+      <para id="x_67">La commande <command role="hg-cmd" moreinfo="none">hg outgoing</command>
+        nous indique quels changements nous allons transférer vers l'autre
+        serveur.</para>
+ 
+      <!-- BEGIN tour.outgoing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing ../hello-push</userinput>
+comparing with ../hello-push
+searching for changes
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.outgoing -->
+
+  
+      <para id="x_68">Et la commande <command role="hg-cmd" moreinfo="none">hg push</command> 
+        effectue réellement le transfert.</para>
+ 
+      <!-- BEGIN tour.push -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
+pushing to ../hello-push
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+</screen>
+<!-- END tour.push -->
+
+  
+      <para id="x_69">Comme avec <command role="hg-cmd" moreinfo="none">hg pull</command>, la
+        commande <command role="hg-cmd" moreinfo="none">hg push</command> ne met pas à jour
+        le répertoire de travail du dépôt dans lequel il transfère les
+        modifications. À l'inverse de <command role="hg-cmd" moreinfo="none">hg
+          pull</command>, <command role="hg-cmd" moreinfo="none">hg push</command> ne fournit
+        pas d'option <literal moreinfo="none">-u</literal> pour forcer la mise à jour de
+        l'espace de travail cible. Cette asymétrie est délibéré : le dépot
+        vers lequel nous transférons peut très bien être un serveur distant
+        et partagé par plusieurs personnes. Si nous devions mettre à jour son
+        répertoire de travail alors que quelqu'un d'autre travaille dessus,
+        nous risquerions de perturber son travail.</para>
+  
+      <para id="x_6a">Qu'est ce qui se passe lorsque vous essayez de récupérer
+        ou de transférer vos modifications et que le dépôt cible a déjà reçu
+        ces modifications ? Rien de bien excitant.</para>
+ 
+      <!-- BEGIN tour.push.nothing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
+pushing to ../hello-push
+searching for changes
+no changes found
+</screen>
+<!-- END tour.push.nothing -->
+
+  
+    </sect2>
+  
+    <sect2>
+      <title>Emplacements par défaut</title>
+
+      <para id="x_719">Quand nous faisons un clone d'un dépôt, Mercurial
+        enregistre l'emplacement du dépôt d'origine dans le fichier
+        <filename moreinfo="none">.hg/hgrc</filename> de notre nouveau dépôt. Si nous ne
+        fournissons pas d'emplacement à la commande <command moreinfo="none">hg
+          pull</command> ou à la commande <command moreinfo="none">hg push</command>, ces
+        commandes utiliseront alors cet emplacement comme valeur par défaut.
+        Les commandes <command moreinfo="none">hg incoming</command> et <command moreinfo="none">hg
+          outgoing</command> feront de même.</para>
+  
+      <para id="x_71a">Si vous regardez le fichier
+        <filename moreinfo="none">.hg/hgrc</filename>, vous constaterez que son contenu
+        ressemble à ce qui suit.</para>
+  
+      <programlisting format="linespecific">[paths]
+default = http://www.selenic.com/repo/hg</programlisting>
+      
+      <para id="x_71b">Il est possible—et souvent
+        pratique—d'avoir un emplacement par défaut pour les commandes
+        <command moreinfo="none">hg push</command> et <command moreinfo="none">hg outgoing</command>
+        différent de celui des commandes <command moreinfo="none">hg pull</command> et
+        <command moreinfo="none">hg incoming</command>. C'est faisable en ajoutant une entrée
+        <literal moreinfo="none">default-push</literal> à la section
+        <literal moreinfo="none">[paths]</literal> du <filename moreinfo="none">.hg/hgrc</filename>, comme
+        suit.</para>
+   
+      <programlisting format="linespecific">[paths]
+default = http://www.selenic.com/repo/hg
+default-push = http://hg.example.com/hg</programlisting>
+
+    </sect2>
+    <sect2>
+      <title>Partager ses modifications à travers le réseau</title>
+  
+      <para id="x_6b">Les commandes que nous avons étudiées dans les sections
+        précédentes ne sont pas limitées aux dépôts locaux. Chacune fonctionne 
+        de la même manière à travers une connexion réseau, il suffit de lui 
+        passer une URL à la place d'un chemin de fichier local.</para>
+ 
+      <!-- BEGIN tour.outgoing.net -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing http://hg.serpentine.com/tutorial/hello</userinput>
+comparing with http://hg.serpentine.com/tutorial/hello
+searching for changes
+changeset:   5:c94f208d1dfb
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+</screen>
+<!-- END tour.outgoing.net -->
+
+  
+      <para id="x_6c">Dans cet exemple, nous allons voir quels changements 
+        nous pourrions transférer vers le dépôt distant, mais le dépôt est, 
+        de manière tout à fait compréhensible, pas configuré pour accepter 
+        des modifications d'utilisateurs anonymes.</para>
+ 
+      <!-- BEGIN tour.push.net -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push http://hg.serpentine.com/tutorial/hello</userinput>
+pushing to http://hg.serpentine.com/tutorial/hello
+searching for changes
+ssl required
+</screen>
+<!-- END tour.push.net -->
+ 
+    
+    </sect2>
+
+  </sect1>
+
+  <sect1>
+    <title>Commencer un nouveau projet</title>
+
+    <para id="x_71c">Il est tout aussi aisé de commencer un nouveau projet
+      que de travailler sur un qui existe déjà. La commande <command moreinfo="none">hg
+        init</command> crée un nouveau dépôt Mercurial vide.</para>
+
+    <!-- BEGIN ch01/new.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myproject</userinput>
+</screen>
+<!-- END ch01/new.init -->
+
+
+    <para id="x_71d">Ceci crée simplement un répertoire nommé
+      <filename moreinfo="none">myproject</filename> dans le répertoire courant.</para>
+
+    <!-- BEGIN ch01/new.ls -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
+total 12
+-rw-r--r-- 1 rpelisse rpelisse   47 Aug 16 14:04 goodbye.c
+-rw-r--r-- 1 rpelisse rpelisse   45 Aug 16 14:04 hello.c
+drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 myproject
+</screen>
+<!-- END ch01/new.ls -->
+
+
+    <para id="x_71e">Nous pouvons dire que <filename moreinfo="none">myproject</filename> est
+      un dépôt Mercurial car il contient un répertoire
+      <filename moreinfo="none">.hg</filename>.</para>
+
+    <!-- BEGIN ch01/new.ls2 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -al myproject</userinput>
+total 12
+drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .
+drwx------ 3 rpelisse rpelisse 4096 Aug 16 14:04 ..
+drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .hg
+</screen>
+<!-- END ch01/new.ls2 -->
+
+
+    <para id="x_71f">Si vous voulons ajouter quelques fichiers préexistants
+      dans ce dépôt, il suffit de les recopier dans le répertoire de travail,
+      et demander à Mercurial de commencer à les suivre en utilisant la
+      commande <command moreinfo="none">hg add</command>.</para>
+
+    <!-- BEGIN ch01/new.add -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../hello.c .</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../goodbye.c .</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add</userinput>
+adding goodbye.c
+adding hello.c
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+A goodbye.c
+A hello.c
+</screen>
+<!-- END ch01/new.add -->
+
+
+    <para id="x_720">Une fois que nous sommes satisfaits de notre projet,
+      nous pouvons commencer à ajouter nos révisions.</para>
+
+    <!-- BEGIN ch01/new.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Initial commit'</userinput>
+</screen>
+<!-- END ch01/new.commit -->
+
+
+    <para id="x_721">Il ne prend que quelques instants pour commencer à
+      utiliser Mercurial sur un nouveau projet, ce qui fait aussi de ses
+      points forts. Travailler avec une gestion de révision devient très
+      facile, nous pouvons même l'utiliser pour les plus petits projets où
+      nous aurions probablement jamais penser utiliser un outils aussi
+      complexe.</para>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch03 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:tour-merge">
+  <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
+  <title>Un rapide tour de Mercurial: fusionner les travaux</title>
+  
+  <para id="x_338">Nous avons maintenant étudié comment cloner un dépôt, effectuer
+    des changements dedans, et récupérer ou transférer depuis un
+    autre dépôt. La prochaine étape est donc de <emphasis>fusionner</emphasis> les
+    modifications de différents dépôts.</para>
+
+  <sect1>
+    <title>Fusionner différents travaux</title>
+      <para id="x_339">La fusion  est un aspect fondamental lorsqu'on
+      travaille iavec un gestionnaire de source distribué.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para id="x_33a">Alice et Bob ont chacun une copie personnelle du dépôt d'un
+            projet sur lequel ils collaborent. Alice corrige un bug
+            dans son dépôt, et Bob ajoute une nouvelle fonctionnalité dans le
+            sien. Ils veulent un dépôt partagé avec à la fois le correctif du
+            bug et la nouvelle fonctionnalité.</para>
+       </listitem>
+       <listitem>
+         <para id="x_33b">Je travaille régulièrement sur plusieurs tâches différentes sur
+           un seul projet en même temps, chacun isolé dans son propre dépôt.
+           Travailler ainsi signifie que je dois régulièrement fusionner une
+           partie de mon code avec celui des autres.</para>
+       </listitem>
+     </itemizedlist>
+
+     <para id="x_33c">Parce que la fusion est une opération si commune à réaliser,
+       Mercurial la rend facile. Étudions ensemble le déroulement des
+       opérations. Nous commencerons encore par faire un clone d'un autre
+       dépôt (vous voyez que l'on fait ça tout le temps ?) puis nous ferons 
+       quelques modifications dessus.</para>
+       
+       <!-- BEGIN tour.merge.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-new-hello</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-new-hello</userinput>
+# Make some simple edits to hello.c.
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">my-text-editor hello.c</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'A new hello for a new day.'</userinput>
+</screen>
+<!-- END tour.merge.clone -->
+
+       
+     <para id="x_33d">Nous devrions avoir maintenant deux copies de
+       <filename moreinfo="none">hello.c</filename> avec des contenus différents. Les
+       historiques de ces deux dépôts ont aussi divergés, comme illustré dans
+       la figure <xref linkend="fig:tour-merge:sep-repos"/>.</para>
+
+      <!-- BEGIN tour.merge.cat1 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
+/*
+ * Placed in the public domain by Bryan O'Sullivan.  This program is
+ * not covered by patents in the United States or other countries.
+ */
+
+#include &lt;stdio.h&gt;
+
+int main(int argc, char **argv)
+{
+	printf("once more, hello.\n");
+	printf("hello, world!\");
+	printf("hello again!\n");
+	return 0;
+}
+</screen>
+<!-- END tour.merge.cat1 -->
+
+     
+     <para id="x_722">Et ici est notre légèrement différente version du
+       dépôt.</para>
+     
+      <!-- BEGIN tour.merge.cat2 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat ../my-hello/hello.c</userinput>
+/*
+ * Placed in the public domain by Bryan O'Sullivan.  This program is
+ * not covered by patents in the United States or other countries.
+ */
+
+#include &lt;stdio.h&gt;
+
+int main(int argc, char **argv)
+{
+	printf("hello, world!\");
+	printf("hello again!\n");
+	return 0;
+}
+</screen>
+<!-- END tour.merge.cat2 -->
+
+     
+     <figure id="fig:tour-merge:sep-repos" float="0">
+       <title>Historique divergent des dépôts <filename class="directory" moreinfo="none">my-hello</filename> et <filename class="directory" moreinfo="none">my-new-hello</filename>.</title>
+       <mediaobject>
+         <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
+         <textobject><phrase>XXX ajoute un test</phrase></textobject>
+       </mediaobject>
+     </figure>
+
+     <para id="x_33f">Nous savons déjà que récupérer les modifications depuis
+       notre dépôt <filename class="directory" moreinfo="none">my-hello</filename> n'aura
+       aucun effet sur l'espace de travail.</para>
+
+      <!-- BEGIN tour.merge.pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
+pulling from ../my-hello
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+(run 'hg heads' to see heads, 'hg merge' to merge)
+</screen>
+<!-- END tour.merge.pull -->
+
+
+     <para id="x_340">Néanmoins, la commande <command role="hg-cmd" moreinfo="none">hg
+       pull</command> nous indique quelque chose au sujet des 
+       <quote>heads</quote>.</para>
+
+     <sect2>
+       <title>Les révisions 'heads'</title>
+
+       <para id="x_341">Rappellez vous que Mercurial enregistre quelle révision
+         est le parent de chaque révision. Si une révision a un parent, nous
+         l'appelons un enfant(child) ou un descendant de ce parent. Une
+         "head" est une révision qui n'a donc pas d'enfant. La révision tip
+         est donc une "head", car c'est la révision la plus récente du dépôt
+         qui n'a pas d'enfant. Il y a des moments où un dépôt peut contenir
+         plusieurs "head".</para>
+
+       <figure id="fig:tour-merge:pull" float="0">
+         <title>Contenu du dépôt après une récupération ("pull") depuis le
+           dépôt <filename class="directory" moreinfo="none">my-hello</filename> vers le dépôt <filename class="directory" moreinfo="none">my-new-hello</filename></title>
+         <mediaobject>
+           <imageobject>
+             <imagedata fileref="tour-merge-pull"/>
+           </imageobject>
+           <textobject><phrase>XXX ajoute un texte</phrase></textobject>
+         </mediaobject>
+       </figure>
+
+       <para id="x_343">Dans la figure <xref linkend="fig:tour-merge:pull"/>,
+         vous pouvez constater l'effet d'un \textit{pull} depuis le dépôt
+         <filename class="directory" moreinfo="none">my-hello</filename> dans le dépôt
+         <filename class="directory" moreinfo="none">my-new-hello</filename>. L'historique qui
+         était déjà présent dans le dépôt <filename class="directory" moreinfo="none">my-new-hello</filename> reste intact, mais une
+         nouvelle révision a été ajoutée. En vous reportant à la figure <xref linkend="fig:tour-merge:sep-repos"/>, vous pouvez voir que le
+         <emphasis>ID de révision (changeset ID)</emphasis> reste le même dans
+         le nouveau dépôt, mais que le <emphasis>numéro de
+         révision</emphasis> reste le même. (Ceci est un parfait exemple de
+         pourquoi il n'est fiable d'utiliser les numéros de révision lorsque
+         l'on discute d'un \textit{changeset}.) Vous pouvez voir les "heads"
+         présentes dans le dépôt en utilisant la commande <command role="hg-cmd" moreinfo="none">hg heads</command>.</para>
+
+        <!-- BEGIN tour.merge.heads -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
+changeset:   6:c94f208d1dfb
+tag:         tip
+parent:      4:2278160e78d4
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+changeset:   5:5f06f94fbeca
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:31 2009 +0000
+summary:     A new hello for a new day.
+
+</screen>
+<!-- END tour.merge.heads -->
+
+      </sect2>
+
+      <sect2>
+        <title>Effectuer la fusion</title>
+
+        <para id="x_344">Que se passe-t-il quand vous essayez d'utiliser la
+          commande <command role="hg-cmd" moreinfo="none">hg update</command> pour mettre à
+          jour votre espace de travail au nouveau "tip"</para>
+         
+         <!-- BEGIN tour.merge.update -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
+abort: crosses branches (use 'hg merge' or 'hg update -C')
+</screen>
+<!-- END tour.merge.update -->
+
+
+         
+        <para id="x_345">Mercurial nous prévient que la commande <command role="hg-cmd" moreinfo="none">hg update</command> n'effectuera pas
+          la fusion, il ne veut pas mettre à jour l'espace de travail quand il
+          estime que nous pourrions avoir besoin d'une fusion, à moins de lui
+          forcer la main. À la place, il faut utiliser la commande <command role="hg-cmd" moreinfo="none">hg merge</command> pour fusionner les deux
+          "heads".</para>
+
+       <para id="x_723">Pour commencer une fusion (merge) entre deux "heads",
+       nous utilisons la commande <command role="hg-cmd" moreinfo="none">hg merge</command>.</para>
+
+        <!-- BEGIN tour.merge.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+merging hello.c
+0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+</screen>
+<!-- END tour.merge.merge -->
+ 
+      
+       <para id="x_347">Nous résolvons les conflits dans le fichier
+         <filename moreinfo="none">hello.c</filename>. Ceci met à jour le répertoire de travail
+         de sorte qu'il ne contienne les modifications ne provenance des
+         <emphasis>deux</emphasis> "heads", ce qui est indiqué par la
+         la sortie de la commande <command role="hg-cmd" moreinfo="none">hg
+         parents</command> et le contenu du fichier
+         <filename moreinfo="none">hello.c</filename>.</para>
+
+        <!-- BEGIN tour.merge.parents -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   5:5f06f94fbeca
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:31 2009 +0000
+summary:     A new hello for a new day.
+
+changeset:   6:c94f208d1dfb
+tag:         tip
+parent:      4:2278160e78d4
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:26 2009 +0000
+summary:     Added an extra line of output
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
+/*
+ * Placed in the public domain by Bryan O'Sullivan.  This program is
+ * not covered by patents in the United States or other countries.
+ */
+
+#include &lt;stdio.h&gt;
+
+int main(int argc, char **argv)
+{
+	printf("once more, hello.\n");
+	printf("hello, world!\");
+	printf("hello again!\n");
+	return 0;
+}
+</screen>
+<!-- END tour.merge.parents -->
+
+     </sect2>
+
+     <sect2>
+       <title>Effectuer l'ajout (commit) du résultat de la fusion</title>
+
+       <para id="x_348">Dès l'instant où vous avez effectué une fusion
+         (merge), <command role="hg-cmd" moreinfo="none">hg parents</command> vous
+         affichera deux parents, avant que vous n'exécutiez la commande
+         <command role="hg-cmd" moreinfo="none">hg commit</command> sur le résultat de la
+         fusion.</para>
+
+        <!-- BEGIN tour.merge.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merged changes'</userinput>
+</screen>
+<!-- END tour.merge.commit -->
+
+
+      <para id="x_349">Nous avons maintenant un nouveau tip, remarquer qu'il
+        contient <emphasis>à la fois</emphasis> nos anciennes "heads" et leurs
+        parents. Ce sont les mêmes révisions que nous avions affichées avec
+        la commande <command role="hg-cmd" moreinfo="none">hg parents</command>.</para>
+
+       <!-- BEGIN tour.merge.tip -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   7:b8e1e756ef55
+tag:         tip
+parent:      5:5f06f94fbeca
+parent:      6:c94f208d1dfb
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:33 2009 +0000
+summary:     Merged changes
+
+</screen>
+<!-- END tour.merge.tip -->
+
+
+      <para id="x_34a">Dans la figure <xref linkend="fig:tour-merge:merge"/>,
+        vous pouvez voir une représentation de ce qui se passe dans l'espace
+        de travail pendant la fusion, et comment ceci affecte le dépôt lors
+        du "commit". Pendant la fusion, l'espace de travail, qui a deux
+        révisions (changesets) comme parents, voit ces derniers devenir le parent
+        d'une nouvelle révision (changeset).</para>
+
+      <figure id="fig:tour-merge:merge" float="0">
+        <title>Working directory and repository during merge, and
+          following commit</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="figs/tour-merge-merge.png"/>
+          </imageobject>
+          <textobject><phrase>XXX ajoute texte</phrase></textobject>
+        </mediaobject>
+      </figure>
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Fusionner les modifications en conflit</title>
+
+    <para id="x_34b">La plupart des fusions sont assez simple à réaliser, mais 
+      parfois vous vous retrouverez à fusionner des fichiers où la modification 
+      touche la même portion de code, au sein d'un même fichier. À moins 
+      que ces modification ne soient identiques, ceci aboutira à un 
+      <emphasis>conflit</emphasis>, et vous devrez décider comment réconcilier 
+      les différentes modifications dans un tout cohérent.</para>
+
+    <figure id="fig:tour-merge:conflict" float="0">
+      <title>Modifications en conflits dans un document</title>
+      <mediaobject>
+        <imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
+        <textobject><phrase>XXX ajoute texte</phrase></textobject>
+      </mediaobject>
+    </figure>
+
+    <para id="x_34d">La figure <xref linkend="fig:tour-merge:conflict"/>
+      illustre un cas de modifications conflictuelles dans un document. Nous
+      avons commencé avec une version simple de ce fichier, puis nous avons
+      ajouté des modifications, pendant que quelqu'un d'autre modifiait le même
+      texte. Notre tâche dans la résolution du conflit est de décider à quoi le
+      fichier devrait ressembler.</para>
+
+    <para id="x_34e">Mercurial n'a pas de mécanisme interne pour gérer 
+      les conflits. À la place, il exécute un programme externe appelé 
+      <command moreinfo="none">hgmerge</command>. Il s'agit d'un script shell qui est 
+      embarqué par Mercurial, vous pouvez le modifier si vous le voulez. 
+      Ce qu'il fait par défaut est d'essayer de trouver un des différents 
+      outils de fusion qui seront probablement installés sur le système. 
+      Il commence par les outils totalement automatiques, et si ils 
+      échouent (parce que la résolution du conflit nécessite une
+      intervention humaine) ou si ils sont absents, le script tente
+      d'exécuter certains outils graphiques de fusion.</para>
+
+    <para id="x_34f">Il est aussi possible de demander à Mercurial d'exécuter
+      un autre programme ou un autre script en définissant la variable
+      d'environnement <envar>HGMERGE</envar> avec le nom
+      du programme de votre choix.</para>
+
+    <sect2>
+      <title>Utiliser un outil graphique de fusion</title>
+
+      <para id="x_350">Mon outil de fusion préféré est
+      <command moreinfo="none">kdiff3</command>, que j'utilise ici pour illustrer les
+        fonctionnalités classiques des outils graphiques de fusion. Vous pouvez
+        voir une capture d'écran de l'utilisation de <command moreinfo="none">kdiff3</command>
+        dans la figure <xref linkend="fig:tour-merge:kdiff3"/>. Cet outil
+        effectue une <emphasis>fusion \textit{three-way</emphasis>}, car il y a
+        trois différentes versions du fichier qui nous intéresse. Le fichier
+        découpe la partie supérieure de la fenêtre en trois panneaux:</para>
+      <itemizedlist>
+        <listitem><para id="x_351">A gauche on la version de
+          <emphasis>base</emphasis> du fichier, soit la plus récente version
+          des deux versions qu'on souhaite fusionner.</para></listitem>
+        <listitem><para id="x_352">Au centre, il y a <quote>notre</quote>
+          version du fichier, avec le contenu que nous avons modifié.</para></listitem>
+        <listitem><para id="x_353">Sur la droite, on trouve
+        <quote>leur</quote> version du fichier, celui qui contient la
+        révision que nous souhaitons intégré.</para>
+        </listitem></itemizedlist>
+      <para id="x_354">Dans le panneau en dessous, on trouve le
+        <emphasis>résultat</emphasis> actuel de notre fusion. Notre tâche
+        consiste donc à remplacement tous les textes en rouges,
+        qui indiquent des conflits non résolus, avec une fusion manuelle et 
+        pertinente de <quote>notre</quote> version et de la <quote>leur</quote>.
+      </para>
+
+      <para id="x_355">Tous les quatre panneaux sont <emphasis>accrochés ensemble</emphasis>, 
+        si nous déroulons les ascenseurs verticalement ou horizontalement dans chacun 
+        d'entre eux, les autres sont mis à jour avec la section correspondante dans leurs 
+        fichiers respectifs.</para>
+
+      <figure id="fig:tour-merge:kdiff3" float="0">
+        <title>Utiliser <command moreinfo="none">kdiff3</command> pour fusionner les
+          différentes version d'un fichier.</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
+            <textobject>
+              <phrase>XXX ajoute texte</phrase>
+            </textobject>
+          </mediaobject>
+       </figure>
+
+       <para id="x_357">Pour chaque portion de fichier posant problème, nous
+         pouvons choisir de résoudre le conflit en utilisant une combinaison de
+         texte depuis la version de base, la notre, ou la leur. Nous pouvons
+         aussi éditer manuellement les fichiers à tout moment, si c'est nécessaire.</para>
+
+       <para id="x_358">Il y a <emphasis>beaucoup</emphasis> d'outils de
+         fusion disponibles, bien trop pour en parler de tous ici. Leurs
+         disponibilités varient selon les plate formes  ainsi que leurs
+         avantages et inconvénients. La plupart sont optimisé pour
+         la fusion de fichier contenant un texte plat, certains sont spécialisé
+         dans un format de fichier précis (généralement XML).</para>
+    </sect2>
+
+    <sect2>
+      <title>Un exemple concret</title>
+
+      <para id="x_359">Dans cet exemple, nous allons reproduire la
+        modification de l'historique du fichier de la figure <xref linkend="fig:tour-merge:conflict"/> ci dessus. Commençons par créer
+        un dépôt avec une version de base de notre document.</para>
+
+      <!-- BEGIN tour-merge-conflict.wife -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Mariam Abacha, the wife of former</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add letter.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, first draft'</userinput>
+</screen>
+<!-- END tour-merge-conflict.wife -->
+ 
+
+      <para id="x_35a">Créons un clone de ce dépôt et faisons une
+        modification dans le fichier.</para>
+
+      <!-- BEGIN tour-merge-conflict.cousin -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-cousin</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-cousin</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Shehu Musa Abacha, cousin to the former</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with cousin'</userinput>
+</screen>
+<!-- END tour-merge-conflict.cousin -->
+
+      
+      <para id="x_35b">Et un autre clone, pour simuler que quelqu'un d'autre effectue une
+        modification sur le fichier. (Ceci pour suggérer qu'il n'est pas rare
+        de devoir effectuer des fusions (merges) avec vos propres travaux quand
+        vous isolez les tâches dans des dépôts distincts. En effet, vous
+        aurez alors à trouver et résoudre certains conflits).</para>
+
+      <!-- BEGIN tour-merge-conflict.son -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-son</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-son</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Alhaji Abba Abacha, son of the former</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with son'</userinput>
+</screen>
+<!-- END tour-merge-conflict.son -->
+
+
+      <para id="x_35c">Maintenant que ces deux versions différentes du même fichier sont
+        créées, nous allons configurer l'environnement de manière appropriée pour
+        exécuter notre fusion (merge).</para>
+
+      <!-- BEGIN tour-merge-conflict.pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam-cousin scam-merge</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-merge</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../scam-son</userinput>
+pulling from ../scam-son
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+not updating, since new heads added
+(run 'hg heads' to see heads, 'hg merge' to merge)
+</screen>
+<!-- END tour-merge-conflict.pull -->
+
+
+      <para id="x_35d">Dans cette exemple, je n'utiliserais pas la commande Mercurial
+        habituelle <command moreinfo="none">hgmerge</command> pour effectuer le
+        fusion (merge), car il me faudrait abandonner ce joli petit exemple automatisé
+        pour utiliser un outil graphique. À la place, je vais définir la
+        variable d'environnement <envar>HGMERGE</envar> pour indiquer à
+        Mercurial d'utiliser la commande non-interactive <command moreinfo="none">merge</command>.
+        Cette dernière est embarquée par de nombreux systèmes <quote>à la Unix</quote>.
+        Si vous exécutez cet exemple depuis votre ordinateur, ne vous
+        occupez pas de définir <envar>HGMERGE</envar>.</para>
+
+     <!-- BEGIN tour-merge-conflict.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=merge</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+merging letter.txt
+merge: warning: conflicts during merge
+merging letter.txt failed!
+0 files updated, 0 files merged, 0 files removed, 1 files unresolved
+use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat letter.txt</userinput>
+Greetings!
+&lt;&lt;&lt;&lt;&lt;&lt;&lt; /tmp/tour-merge-conflictk3twLJ/scam-merge/letter.txt
+I am Shehu Musa Abacha, cousin to the former
+=======
+I am Alhaji Abba Abacha, son of the former
+&gt;&gt;&gt;&gt;&gt;&gt;&gt; /tmp/letter.txt~other.4O623C
+Nigerian dictator Sani Abacha.
+</screen>
+<!-- END tour-merge-conflict.merge -->
+ 
+
+
+     <para id="x_35f">Parce que <command moreinfo="none">merge</command> ne peut pas résoudre
+       les modifications conflictuelles, il laisse des <emphasis>marqueurs de
+       différences</emphasis> à l'intérieur du fichier qui a des conflits,
+       indiquant clairement quelles lignes sont en conflits, et si elles
+       viennent de notre fichier ou du fichier externe.
+     </para>
+
+     <para id="x_360">Mercurial peut distinguer, à la manière dont la
+       commande <command moreinfo="none">merge</command> se termine, qu'elle n'a pas été
+       capable d'effectuer la fusion (merge), alors il nous indique que nous
+       devons effectuer de nouveau cette opération. Ceci peut être très utile
+       si, par exemple, nous exécutons un outil graphique de fusion et que
+       nous le quittons sans nous rendre compte qu'il reste des conflits ou 
+       simplement par erreur.</para>
+
+     <para id="x_361">Si la fusion (merge) automatique ou manuelle échoue, 
+       il n'y a rien pour nous empêcher de <quote>corriger le tir</quote> en
+       modifiant nous même les fichiers, et enfin effectuer le "commit" du 
+       fichier:</para>
+
+     <!-- BEGIN tour-merge-conflict.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Bryan O'Sullivan, no relation of the former</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -m letter.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Send me your money'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   3:0954bda76c6b
+tag:         tip
+parent:      1:1ac156b6e708
+parent:      2:7ee20631b33b
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:34 2009 +0000
+summary:     Send me your money
+
+</screen>
+<!-- END tour-merge-conflict.commit -->
+
+
+     <note>
+       <title>Où est la <command moreinfo="none">hg resolve</command> ?</title>
+       
+       <para id="x_724">La commande <command moreinfo="none">hg resolve</command> a été
+         introduit dans la version 1.1 de Mercurial, qui a été publié en
+         décembre 2008. Si vous utilisez une version plus anciennne de
+         Mercurial (exécutez la command <command moreinfo="none">hg version</command> pour en
+         avoir le coeur net), cette commande ne sera pas disponible. Si votre
+         version de Mercurial est plus ancienne que la 1.1, vous devriez très
+         fortement considérer une mise à jour à une version plus récente avant
+         d'essayer de régler des fusions complexes.</para>
+       </note>
+     </sect2>
+   </sect1>
+
+   <sect1 id="sec:tour-merge:fetch">
+     <title>Simplification de la séquence pull-merge-commit</title>
+
+     <para id="x_362">La procédure pour effectuer la fusion indiquée
+       ci-dessus est simple, mais requiert le lancement de trois commandes à la
+       suite.</para>
+
+     <programlisting format="linespecific">hg pull -u
+hg merge
+hg commit -m 'Merged remote changes'</programlisting>
+
+     <para id="x_363">Lors du "commit" final, vous devez également saisir un
+       message, qui aura vraisemblablement assez peu d'intérêt.</para>
+
+     <para id="x_364">Il serait assez sympathique de pouvoir réduire le
+       nombre d'opérations nécessaire, si possible. De fait Mercurial est
+       fourni avec une extension appelé <literal role="hg-ext" moreinfo="none">fetch</literal>
+       qui fait justement cela.</para>
+
+     <para id="x_365">Mercurial fourni un mécanisme d'extension flexible qui permet à chacun
+       d'étendre ces fonctionnalités, tout en conservant le cœur de Mercurial
+       léger et facile à utiliser. Certains extensions ajoutent de nouvelles
+       commandes que vous pouvez utiliser en ligne de commande, alors que
+       d'autres travaillent <quote>en coulisse,</quote> par exemple en ajoutant des
+       possibilités au serveur.</para>
+
+     <para id="x_366">L'extension <literal role="hg-ext" moreinfo="none">fetch</literal>
+       ajoute une nouvelle commande nommée, sans surprise, <command role="hg-cmd" moreinfo="none">hg fetch</command>. Cette extension résulte en une
+       combinaison de <command role="hg-cmd" moreinfo="none">hg pull</command>, <command role="hg-cmd" moreinfo="none">hg update</command> and <command role="hg-cmd" moreinfo="none">hg
+       merge</command>. Elle commence par récupérer les modifications d'un
+       autre dépôt dans le dépôt courant. Si elle trouve que les
+       modifications ajoutent une nouvelle "head", elle effectue un "merge",
+       et ensuite "commit" le résultat du "merge" avec un message généré
+       automatiquement. Si aucune "head" n'ont été ajouté, elle met à jour le
+       répertoire de travail au niveau de la nouvelle révision tip.</para>
+     
+     <para id="x_367">Activer l'extension <literal role="hg-ext" moreinfo="none">fetch</literal> est facile. Modifiez votre <filename role="special" moreinfo="none">.hgrc</filename>, et soit allez à la section <literal role="rc-extensions" moreinfo="none">extensions</literal> soit créer une section
+       <literal role="rc-extensions" moreinfo="none">extensions</literal>. Ensuite ajoutez
+       une ligne qui consiste simplement en <quote>\Verb+fetch =</quote>.</para>
+
+     <programlisting format="linespecific">[extensions]
+fetch =</programlisting>
+
+    <para id="x_368">(Normalement, sur la partie droite de
+      <quote><literal moreinfo="none">=</literal></quote> devrait apparaître le chemin de
+      l'extension, mais étant donné que l'extension <literal role="hg-ext" moreinfo="none">fetch</literal> fait partie de la distribution standard,
+      Mercurial sait où la trouver.) </para>
+
+  </sect1>
+  
+  <sect1>
+    <title>Renommer, copier, et fusionner (merge)</title>
+
+    <para id="x_729">En cours de la vie d'un projet, nous allons souvent 
+      vouloir changer la disposition de ses fichiers et de ses répertoires. 
+      Ceci peut être aussi simple que de changer le nom d'un seul fichier, 
+      et aussi compliqué que de restructurer une hiérarchie entiere de fichier
+      au sein du projet.</para>
+
+    <para id="x_72a">Mercurial permet de faire ce genre de modification de
+      manière fluide, à condition de l'informer de ce que nous faisons. Si 
+      vous voulez renommenr un ficher, vous devriez utiliser les commande
+      <command moreinfo="none">hg rename</command><footnote>
+        <para id="x_72b">Si vous un utilisateur de Unix, vous serez content
+          de savoir que la commande  <command moreinfo="none">hg rename</command> command 
+          peut être abrégée en <command moreinfo="none">hg mv</command>.</para>
+      </footnote> pour changer son nom, ainsi Mercurial peut ensuite prendre
+      la bonne décision, plus tard, en cas de fusionv (merge).</para>
+
+    <para id="x_72c">Nous étudierojns en détail l'utilisation de ces commandes, 
+      en détail, dans le chapitre <xref linkend="chap:daily.copy"/>.</para>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch04 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:concepts">
+  <?dbhtml filename="behind-the-scenes.html"?>
+  <title>Derrière le décor</title>
+  
+  <para id="x_2e8">À la différence de beaucoup d'outils de gestion de versions,
+    les concepts sur lesquels se base Mercurial sont assez simples pour
+    qu'il soit facile de comprendre comment le logiciel fonctionne.
+    Bien que leur connaissance ne soit pas nécéssaire, je trouve utile
+    d'avoir un <quote>modèle mental</quote> de ce qui se passe.</para>
+
+  <para id="x_2e9">En effet, cette compréhension m'apporte la confiance que
+    Mercurial a été développé avec soin pour être à la fois
+    <emphasis>sûr</emphasis> et <emphasis>efficace</emphasis>. De surcroît,
+    si il m'est facile de garder en tête ce que le logiciel fait lorsque
+    j'accompli des tâches de révision, j'aurai moins de risques d'être
+    surpris par son comportement.</para>
+
+  <para id="x_2ea">Dans ce chapitre, nous décrirons tout d'abord les concepts
+    essentiels de l'architecture de Mercurial, pour ensuite discuter quelques
+    uns des détails intéressants de son implémentation.</para>
+
+  <sect1>
+    <title>Conservation de l'historique sous Mercurial</title>
+    <sect2>
+      <title>Suivi de l'historique pour un seul fichier</title>
+      
+      <para id="x_2eb">Lorsque Mercurial effectue un suivi des modifications
+        faites à un fichier, il conserve l'historique pour ce fichier dans un
+        <emphasis>filelog</emphasis> sous forme de métadonnées. Chaque entrée
+        dans le filelog contient assez d'informations pour reconstituer une
+        révision du fichier correspondant. Les filelogs sont des fichiers
+        stockés dans le répertoire  <filename role="special" class="directory" moreinfo="none">.hg/store/data</filename>. Un filelog contient
+        des informations de deux types: les données de révision, et un index
+        pour permettre à Mercurial une recherche efficace d'une révision
+        donnée.</para>
+
+      <para id="x_2ec">Lorsqu'un fichier devient trop gros ou a un long
+        historique, son filelog se voit stocker dans un fichier de données
+        (avec un suffixe <quote><literal moreinfo="none">.d</literal></quote>) et un fichier
+        index (avec un suffixe<quote><literal moreinfo="none">.i</literal></quote>)
+        distincts. La relation entre un fichier dans le répertoire de travail
+        et le  filelog couvrant le suivi de son historique dans le dépôt est
+        illustré à la figure <xref linkend="fig:concepts:filelog"/>.</para>
+
+      <figure id="fig:concepts:filelog" float="0">
+        <title>Relations entre les fichiers dans le répertoire de travail et
+        leurs filelogs dans le dépôt</title> 
+        <mediaobject> <imageobject><imagedata fileref="figs/filelog.png"/></imageobject>
+          <textobject><phrase>XXX add text</phrase></textobject>
+        </mediaobject> </figure>
+
+    </sect2>
+    <sect2>
+      <title>Gestion des fichiers suivis</title>
+      
+      <para id="x_2ee">Mercurial a recours à une structure nommée
+        <emphasis>manifest</emphasis> pour rassembler les informations sur
+        les fichiers dont il gère le suivi. Chaque entrée dans ce manifest
+        contient des informations sur les fichiers présents dans une révision
+        donnée. Une entrée store la liste des fichiers faisant partie de la
+        révision, la version de chaque fichier, et quelques autres
+        métadonnées sur ces fichiers.</para>
+
+    </sect2>
+    <sect2>
+      <title>Recording changeset information</title>
+
+      <para id="x_2ef">The <emphasis>changelog</emphasis> contains
+        information about each changeset.  Each revision records who
+        committed a change, the changeset comment, other pieces of
+        changeset-related information, and the revision of the manifest to
+        use.</para>
+
+    </sect2>
+    <sect2>
+      <title>Relationships between revisions</title>
+
+      <para id="x_2f0">Within a changelog, a manifest, or a filelog, each
+	revision stores a pointer to its immediate parent (or to its
+	two parents, if it's a merge revision).  As I mentioned above,
+	there are also relationships between revisions
+	<emphasis>across</emphasis> these structures, and they are
+	hierarchical in nature.</para>
+
+      <para id="x_2f1">For every changeset in a repository, there is exactly one
+	revision stored in the changelog.  Each revision of the
+	changelog contains a pointer to a single revision of the
+	manifest.  A revision of the manifest stores a pointer to a
+	single revision of each filelog tracked when that changeset
+	was created.  These relationships are illustrated in
+	<xref linkend="fig:concepts:metadata"/>.</para>
+
+      <figure id="fig:concepts:metadata" float="0">
+	<title>Metadata relationships</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/metadata.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_2f3">As the illustration shows, there is
+	<emphasis>not</emphasis> a <quote>one to one</quote>
+	relationship between revisions in the changelog, manifest, or
+	filelog. If a file that
+	Mercurial tracks hasn't changed between two changesets, the
+	entry for that file in the two revisions of the manifest will
+	point to the same revision of its filelog<footnote>
+	  <para id="x_725">It is possible (though unusual) for the manifest to
+	    remain the same between two changesets, in which case the
+	    changelog entries for those changesets will point to the
+	    same revision of the manifest.</para>
+	</footnote>.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Safe, efficient storage</title>
+
+    <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are
+      provided by a single structure called the
+      <emphasis>revlog</emphasis>.</para>
+
+    <sect2>
+      <title>Efficient storage</title>
+
+      <para id="x_2f5">The revlog provides efficient storage of revisions using a
+	<emphasis>delta</emphasis> mechanism.  Instead of storing a
+	complete copy of a file for each revision, it stores the
+	changes needed to transform an older revision into the new
+	revision.  For many kinds of file data, these deltas are
+	typically a fraction of a percent of the size of a full copy
+	of a file.</para>
+
+      <para id="x_2f6">Some obsolete revision control systems can only work with
+	deltas of text files.  They must either store binary files as
+	complete snapshots or encoded into a text representation, both
+	of which are wasteful approaches.  Mercurial can efficiently
+	handle deltas of files with arbitrary binary contents; it
+	doesn't need to treat text as special.</para>
+
+    </sect2>
+    <sect2 id="sec:concepts:txn">
+      <title>Safe operation</title>
+
+      <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to
+	the end of a revlog file. It never modifies a section of a
+	file after it has written it.  This is both more robust and
+	efficient than schemes that need to modify or rewrite
+	data.</para>
+
+      <para id="x_2f8">In addition, Mercurial treats every write as part of a
+	<emphasis>transaction</emphasis> that can span a number of
+	files.  A transaction is <emphasis>atomic</emphasis>: either
+	the entire transaction succeeds and its effects are all
+	visible to readers in one go, or the whole thing is undone.
+	This guarantee of atomicity means that if you're running two
+	copies of Mercurial, where one is reading data and one is
+	writing it, the reader will never see a partially written
+	result that might confuse it.</para>
+
+      <para id="x_2f9">The fact that Mercurial only appends to files makes it
+	easier to provide this transactional guarantee.  The easier it
+	is to do stuff like this, the more confident you should be
+	that it's done correctly.</para>
+
+    </sect2>
+    <sect2>
+      <title>Fast retrieval</title>
+
+      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to
+	all earlier revision control systems: the problem of
+	<emphasis>inefficient retrieval</emphasis>. Most revision
+	control systems store the contents of a revision as an
+	incremental series of modifications against a
+	<quote>snapshot</quote>.  (Some base the snapshot on the
+	oldest revision, others on the newest.)  To reconstruct a
+	specific revision, you must first read the snapshot, and then
+	every one of the revisions between the snapshot and your
+	target revision.  The more history that a file accumulates,
+	the more revisions you must read, hence the longer it takes to
+	reconstruct a particular revision.</para>
+
+      <figure id="fig:concepts:snapshot" float="0">
+	<title>Snapshot of a revlog, with incremental deltas</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_2fc">The innovation that Mercurial applies to this problem is
+	simple but effective.  Once the cumulative amount of delta
+	information stored since the last snapshot exceeds a fixed
+	threshold, it stores a new snapshot (compressed, of course),
+	instead of another delta.  This makes it possible to
+	reconstruct <emphasis>any</emphasis> revision of a file
+	quickly.  This approach works so well that it has since been
+	copied by several other revision control systems.</para>
+
+      <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates
+	the idea.  In an entry in a revlog's index file, Mercurial
+	stores the range of entries from the data file that it must
+	read to reconstruct a particular revision.</para>
+
+      <sect3>
+	<title>Aside: the influence of video compression</title>
+
+	<para id="x_2fe">If you're familiar with video compression or
+	  have ever watched a TV feed through a digital cable or
+	  satellite service, you may know that most video compression
+	  schemes store each frame of video as a delta against its
+	  predecessor frame.</para>
+
+	<para id="x_2ff">Mercurial borrows this idea to make it
+	  possible to reconstruct a revision from a snapshot and a
+	  small number of deltas.</para>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Identification and strong integrity</title>
+
+      <para id="x_300">Along with delta or snapshot information, a revlog entry
+	contains a cryptographic hash of the data that it represents.
+	This makes it difficult to forge the contents of a revision,
+	and easy to detect accidental corruption.</para>
+
+      <para id="x_301">Hashes provide more than a mere check against corruption;
+	they are used as the identifiers for revisions.  The changeset
+	identification hashes that you see as an end user are from
+	revisions of the changelog.  Although filelogs and the
+	manifest also use hashes, Mercurial only uses these behind the
+	scenes.</para>
+
+      <para id="x_302">Mercurial verifies that hashes are correct when it
+	retrieves file revisions and when it pulls changes from
+	another repository.  If it encounters an integrity problem, it
+	will complain and stop whatever it's doing.</para>
+
+      <para id="x_303">In addition to the effect it has on retrieval efficiency,
+	Mercurial's use of periodic snapshots makes it more robust
+	against partial data corruption.  If a revlog becomes partly
+	corrupted due to a hardware error or system bug, it's often
+	possible to reconstruct some or most revisions from the
+	uncorrupted sections of the revlog, both before and after the
+	corrupted section.  This would not be possible with a
+	delta-only storage model.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Revision history, branching, and merging</title>
+
+    <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
+      immediate ancestor revision, usually referred to as its
+      <emphasis>parent</emphasis>.  In fact, a revision contains room
+      for not one parent, but two.  Mercurial uses a special hash,
+      called the <quote>null ID</quote>, to represent the idea
+      <quote>there is no parent here</quote>.  This hash is simply a
+      string of zeroes.</para>
+
+    <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see
+      an example of the conceptual structure of a revlog.  Filelogs,
+      manifests, and changelogs all have this same structure; they
+      differ only in the kind of data stored in each delta or
+      snapshot.</para>
+
+    <para id="x_306">The first revision in a revlog (at the bottom of the image)
+      has the null ID in both of its parent slots.  For a
+      <quote>normal</quote> revision, its first parent slot contains
+      the ID of its parent revision, and its second contains the null
+      ID, indicating that the revision has only one real parent.  Any
+      two revisions that have the same parent ID are branches.  A
+      revision that represents a merge between branches has two normal
+      revision IDs in its parent slots.</para>
+
+    <figure id="fig:concepts:revlog" float="0">
+      <title>The conceptual structure of a revlog</title>
+      <mediaobject>
+	<imageobject><imagedata fileref="figs/revlog.png"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
+      </mediaobject>
+    </figure>
+
+  </sect1>
+  <sect1>
+    <title>The working directory</title>
+
+    <para id="x_307">In the working directory, Mercurial stores a snapshot of the
+      files from the repository as of a particular changeset.</para>
+
+    <para id="x_308">The working directory <quote>knows</quote> which changeset
+      it contains.  When you update the working directory to contain a
+      particular changeset, Mercurial looks up the appropriate
+      revision of the manifest to find out which files it was tracking
+      at the time that changeset was committed, and which revision of
+      each file was then current.  It then recreates a copy of each of
+      those files, with the same contents it had when the changeset
+      was committed.</para>
+
+    <para id="x_309">The <emphasis>dirstate</emphasis> is a special
+      structure that contains Mercurial's knowledge of the working
+      directory.  It is maintained as a file named
+      <filename moreinfo="none">.hg/dirstate</filename> inside a repository.  The
+      dirstate details which changeset the working directory is
+      updated to, and all of the files that Mercurial is tracking in
+      the working directory. It also lets Mercurial quickly notice
+      changed files, by recording their checkout times and
+      sizes.</para>
+
+    <para id="x_30a">Just as a revision of a revlog has room for two parents, so
+      that it can represent either a normal revision (with one parent)
+      or a merge of two earlier revisions, the dirstate has slots for
+      two parents.  When you use the <command role="hg-cmd" moreinfo="none">hg
+	update</command> command, the changeset that you update to is
+      stored in the <quote>first parent</quote> slot, and the null ID
+      in the second. When you <command role="hg-cmd" moreinfo="none">hg
+	merge</command> with another changeset, the first parent
+      remains unchanged, and the second parent is filled in with the
+      changeset you're merging with.  The <command role="hg-cmd" moreinfo="none">hg
+	parents</command> command tells you what the parents of the
+      dirstate are.</para>
+
+    <sect2>
+      <title>What happens when you commit</title>
+
+      <para id="x_30b">The dirstate stores parent information for more than just
+	book-keeping purposes.  Mercurial uses the parents of the
+	dirstate as <emphasis>the parents of a new
+	  changeset</emphasis> when you perform a commit.</para>
+
+      <figure id="fig:concepts:wdir" float="0">
+	<title>The working directory can have two parents</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/wdir.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the
+	normal state of the working directory, where it has a single
+	changeset as parent.  That changeset is the
+	<emphasis>tip</emphasis>, the newest changeset in the
+	repository that has no children.</para>
+
+      <figure id="fig:concepts:wdir-after-commit" float="0">
+	<title>The working directory gains new parents after a
+	  commit</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_30f">It's useful to think of the working directory as
+	<quote>the changeset I'm about to commit</quote>.  Any files
+	that you tell Mercurial that you've added, removed, renamed,
+	or copied will be reflected in that changeset, as will
+	modifications to any files that Mercurial is already tracking;
+	the new changeset will have the parents of the working
+	directory as its parents.</para>
+
+      <para id="x_310">After a commit, Mercurial will update the
+	parents of the working directory, so that the first parent is
+	the ID of the new changeset, and the second is the null ID.
+	This is shown in <xref linkend="fig:concepts:wdir-after-commit"/>. Mercurial
+	doesn't touch any of the files in the working directory when
+	you commit; it just modifies the dirstate to note its new
+	parents.</para>
+
+    </sect2>
+    <sect2>
+      <title>Creating a new head</title>
+
+      <para id="x_311">It's perfectly normal to update the working directory to a
+	changeset other than the current tip.  For example, you might
+	want to know what your project looked like last Tuesday, or
+	you could be looking through changesets to see which one
+	introduced a bug.  In cases like this, the natural thing to do
+	is update the working directory to the changeset you're
+	interested in, and then examine the files in the working
+	directory directly to see their contents as they were when you
+	committed that changeset.  The effect of this is shown in
+	<xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
+
+      <figure id="fig:concepts:wdir-pre-branch" float="0">
+	<title>The working directory, updated to an older
+	  changeset</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_313">Having updated the working directory to an
+	older changeset, what happens if you make some changes, and
+	then commit?  Mercurial behaves in the same way as I outlined
+	above.  The parents of the working directory become the
+	parents of the new changeset.  This new changeset has no
+	children, so it becomes the new tip.  And the repository now
+	contains two changesets that have no children; we call these
+	<emphasis>heads</emphasis>.  You can see the structure that
+	this creates in <xref linkend="fig:concepts:wdir-branch"/>.</para>
+
+      <figure id="fig:concepts:wdir-branch" float="0">
+	<title>After a commit made while synced to an older
+	  changeset</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <note>
+	<para id="x_315">If you're new to Mercurial, you should keep
+	  in mind a common <quote>error</quote>, which is to use the
+	  <command role="hg-cmd" moreinfo="none">hg pull</command> command without any
+	  options.  By default, the <command role="hg-cmd" moreinfo="none">hg
+	    pull</command> command <emphasis>does not</emphasis>
+	  update the working directory, so you'll bring new changesets
+	  into your repository, but the working directory will stay
+	  synced at the same changeset as before the pull.  If you
+	  make some changes and commit afterwards, you'll thus create
+	  a new head, because your working directory isn't synced to
+	  whatever the current tip is.  To combine the operation of a
+	  pull, followed by an update, run <command moreinfo="none">hg pull
+	    -u</command>.</para>
+
+	<para id="x_316">I put the word <quote>error</quote> in quotes
+	  because all that you need to do to rectify the situation
+	  where you created a new head by accident is
+	  <command role="hg-cmd" moreinfo="none">hg merge</command>, then <command role="hg-cmd" moreinfo="none">hg commit</command>.  In other words, this
+	  almost never has negative consequences; it's just something
+	  of a surprise for newcomers.  I'll discuss other ways to
+	  avoid this behavior, and why Mercurial behaves in this
+	  initially surprising way, later on.</para>
+      </note>
+
+    </sect2>
+    <sect2>
+      <title>Merging changes</title>
+
+      <para id="x_317">When you run the <command role="hg-cmd" moreinfo="none">hg
+	  merge</command> command, Mercurial leaves the first parent
+	of the working directory unchanged, and sets the second parent
+	to the changeset you're merging with, as shown in <xref linkend="fig:concepts:wdir-merge"/>.</para>
+
+      <figure id="fig:concepts:wdir-merge" float="0">
+	<title>Merging two heads</title>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figs/wdir-merge.png"/>
+	  </imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_319">Mercurial also has to modify the working directory, to
+	merge the files managed in the two changesets.  Simplified a
+	little, the merging process goes like this, for every file in
+	the manifests of both changesets.</para>
+      <itemizedlist>
+	<listitem><para id="x_31a">If neither changeset has modified a file, do
+	    nothing with that file.</para>
+	</listitem>
+	<listitem><para id="x_31b">If one changeset has modified a file, and the
+	    other hasn't, create the modified copy of the file in the
+	    working directory.</para>
+	</listitem>
+	<listitem><para id="x_31c">If one changeset has removed a file, and the
+	    other hasn't (or has also deleted it), delete the file
+	    from the working directory.</para>
+	</listitem>
+	<listitem><para id="x_31d">If one changeset has removed a file, but the
+	    other has modified the file, ask the user what to do: keep
+	    the modified file, or remove it?</para>
+	</listitem>
+	<listitem><para id="x_31e">If both changesets have modified a file,
+	    invoke an external merge program to choose the new
+	    contents for the merged file.  This may require input from
+	    the user.</para>
+	</listitem>
+	<listitem><para id="x_31f">If one changeset has modified a file, and the
+	    other has renamed or copied the file, make sure that the
+	    changes follow the new name of the file.</para>
+	</listitem></itemizedlist>
+      <para id="x_320">There are more details—merging has plenty of corner
+	cases—but these are the most common choices that are
+	involved in a merge.  As you can see, most cases are
+	completely automatic, and indeed most merges finish
+	automatically, without requiring your input to resolve any
+	conflicts.</para>
+
+      <para id="x_321">When you're thinking about what happens when you commit
+	after a merge, once again the working directory is <quote>the
+	  changeset I'm about to commit</quote>.  After the <command role="hg-cmd" moreinfo="none">hg merge</command> command completes, the
+	working directory has two parents; these will become the
+	parents of the new changeset.</para>
+
+      <para id="x_322">Mercurial lets you perform multiple merges, but
+	you must commit the results of each individual merge as you
+	go.  This is necessary because Mercurial only tracks two
+	parents for both revisions and the working directory.  While
+	it would be technically feasible to merge multiple changesets
+	at once, Mercurial avoids this for simplicity.  With multi-way
+	merges, the risks of user confusion, nasty conflict
+	resolution, and making a terrible mess of a merge would grow
+	intolerable.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Merging and renames</title>
+
+      <para id="x_69a">A surprising number of revision control systems pay little
+	or no attention to a file's <emphasis>name</emphasis> over
+	time.  For instance, it used to be common that if a file got
+	renamed on one side of a merge, the changes from the other
+	side would be silently dropped.</para>
+
+      <para id="x_69b">Mercurial records metadata when you tell it to perform a
+	rename or copy. It uses this metadata during a merge to do the
+	right thing in the case of a merge.  For instance, if I rename
+	a file, and you edit it without renaming it, when we merge our
+	work the file will be renamed and have your edits
+	applied.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Other interesting design features</title>
+
+    <para id="x_323">In the sections above, I've tried to highlight some of the
+      most important aspects of Mercurial's design, to illustrate that
+      it pays careful attention to reliability and performance.
+      However, the attention to detail doesn't stop there.  There are
+      a number of other aspects of Mercurial's construction that I
+      personally find interesting.  I'll detail a few of them here,
+      separate from the <quote>big ticket</quote> items above, so that
+      if you're interested, you can gain a better idea of the amount
+      of thinking that goes into a well-designed system.</para>
+
+    <sect2>
+      <title>Clever compression</title>
+
+      <para id="x_324">When appropriate, Mercurial will store both snapshots and
+	deltas in compressed form.  It does this by always
+	<emphasis>trying to</emphasis> compress a snapshot or delta,
+	but only storing the compressed version if it's smaller than
+	the uncompressed version.</para>
+
+      <para id="x_325">This means that Mercurial does <quote>the right
+	  thing</quote> when storing a file whose native form is
+	compressed, such as a <literal moreinfo="none">zip</literal> archive or a JPEG
+	image.  When these types of files are compressed a second
+	time, the resulting file is usually bigger than the
+	once-compressed form, and so Mercurial will store the plain
+	<literal moreinfo="none">zip</literal> or JPEG.</para>
+
+      <para id="x_326">Deltas between revisions of a compressed file are usually
+	larger than snapshots of the file, and Mercurial again does
+	<quote>the right thing</quote> in these cases.  It finds that
+	such a delta exceeds the threshold at which it should store a
+	complete snapshot of the file, so it stores the snapshot,
+	again saving space compared to a naive delta-only
+	approach.</para>
+
+      <sect3>
+	<title>Network recompression</title>
+
+	<para id="x_327">When storing revisions on disk, Mercurial uses the
+	  <quote>deflate</quote> compression algorithm (the same one
+	  used by the popular <literal moreinfo="none">zip</literal> archive format),
+	  which balances good speed with a respectable compression
+	  ratio.  However, when transmitting revision data over a
+	  network connection, Mercurial uncompresses the compressed
+	  revision data.</para>
+
+	<para id="x_328">If the connection is over HTTP, Mercurial recompresses
+	  the entire stream of data using a compression algorithm that
+	  gives a better compression ratio (the Burrows-Wheeler
+	  algorithm from the widely used <literal moreinfo="none">bzip2</literal>
+	  compression package).  This combination of algorithm and
+	  compression of the entire stream (instead of a revision at a
+	  time) substantially reduces the number of bytes to be
+	  transferred, yielding better network performance over most
+	  kinds of network.</para>
+
+	<para id="x_329">If the connection is over
+	  <command moreinfo="none">ssh</command>, Mercurial
+	  <emphasis>doesn't</emphasis> recompress the stream, because
+	  <command moreinfo="none">ssh</command> can already do this itself.  You can
+	  tell Mercurial to always use <command moreinfo="none">ssh</command>'s
+	  compression feature by editing the
+	  <filename moreinfo="none">.hgrc</filename> file in your home directory as
+	  follows.</para>
+
+	<programlisting format="linespecific">[ui]
+ssh = ssh -C</programlisting>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Read/write ordering and atomicity</title>
+
+      <para id="x_32a">Appending to files isn't the whole story when
+	it comes to guaranteeing that a reader won't see a partial
+	write.  If you recall <xref linkend="fig:concepts:metadata"/>,
+	revisions in the changelog point to revisions in the manifest,
+	and revisions in the manifest point to revisions in filelogs.
+	This hierarchy is deliberate.</para>
+
+      <para id="x_32b">A writer starts a transaction by writing filelog and
+	manifest data, and doesn't write any changelog data until
+	those are finished.  A reader starts by reading changelog
+	data, then manifest data, followed by filelog data.</para>
+
+      <para id="x_32c">Since the writer has always finished writing filelog and
+	manifest data before it writes to the changelog, a reader will
+	never read a pointer to a partially written manifest revision
+	from the changelog, and it will never read a pointer to a
+	partially written filelog revision from the manifest.</para>
+
+    </sect2>
+    <sect2>
+      <title>Concurrent access</title>
+
+      <para id="x_32d">The read/write ordering and atomicity guarantees mean that
+	Mercurial never needs to <emphasis>lock</emphasis> a
+	repository when it's reading data, even if the repository is
+	being written to while the read is occurring. This has a big
+	effect on scalability; you can have an arbitrary number of
+	Mercurial processes safely reading data from a repository
+	all at once, no matter whether it's being written to or
+	not.</para>
+
+      <para id="x_32e">The lockless nature of reading means that if you're
+	sharing a repository on a multi-user system, you don't need to
+	grant other local users permission to
+	<emphasis>write</emphasis> to your repository in order for
+	them to be able to clone it or pull changes from it; they only
+	need <emphasis>read</emphasis> permission.  (This is
+	<emphasis>not</emphasis> a common feature among revision
+	control systems, so don't take it for granted!  Most require
+	readers to be able to lock a repository to access it safely,
+	and this requires write permission on at least one directory,
+	which of course makes for all kinds of nasty and annoying
+	security and administrative problems.)</para>
+
+      <para id="x_32f">Mercurial uses locks to ensure that only one process can
+	write to a repository at a time (the locking mechanism is safe
+	even over filesystems that are notoriously hostile to locking,
+	such as NFS).  If a repository is locked, a writer will wait
+	for a while to retry if the repository becomes unlocked, but
+	if the repository remains locked for too long, the process
+	attempting to write will time out after a while. This means
+	that your daily automated scripts won't get stuck forever and
+	pile up if a system crashes unnoticed, for example.  (Yes, the
+	timeout is configurable, from zero to infinity.)</para>
+
+      <sect3>
+	<title>Safe dirstate access</title>
+
+	<para id="x_330">As with revision data, Mercurial doesn't take a lock to
+	  read the dirstate file; it does acquire a lock to write it.
+	  To avoid the possibility of reading a partially written copy
+	  of the dirstate file, Mercurial writes to a file with a
+	  unique name in the same directory as the dirstate file, then
+	  renames the temporary file atomically to
+	  <filename moreinfo="none">dirstate</filename>.  The file named
+	  <filename moreinfo="none">dirstate</filename> is thus guaranteed to be
+	  complete, not partially written.</para>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Avoiding seeks</title>
+
+      <para id="x_331">Critical to Mercurial's performance is the avoidance of
+	seeks of the disk head, since any seek is far more expensive
+	than even a comparatively large read operation.</para>
+
+      <para id="x_332">This is why, for example, the dirstate is stored in a
+	single file.  If there were a dirstate file per directory that
+	Mercurial tracked, the disk would seek once per directory.
+	Instead, Mercurial reads the entire single dirstate file in
+	one step.</para>
+
+      <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme
+	when cloning a repository on local storage.  Instead of
+	copying every revlog file from the old repository into the new
+	repository, it makes a <quote>hard link</quote>, which is a
+	shorthand way to say <quote>these two names point to the same
+	  file</quote>.  When Mercurial is about to write to one of a
+	revlog's files, it checks to see if the number of names
+	pointing at the file is greater than one.  If it is, more than
+	one repository is using the file, so Mercurial makes a new
+	copy of the file that is private to this repository.</para>
+
+      <para id="x_334">A few revision control developers have pointed out that
+	this idea of making a complete private copy of a file is not
+	very efficient in its use of storage.  While this is true,
+	storage is cheap, and this method gives the highest
+	performance while deferring most book-keeping to the operating
+	system.  An alternative scheme would most likely reduce
+	performance and increase the complexity of the software, but
+	speed and simplicity are key to the <quote>feel</quote> of
+	day-to-day use.</para>
+
+    </sect2>
+    <sect2>
+      <title>Other contents of the dirstate</title>
+
+      <para id="x_335">Because Mercurial doesn't force you to tell it when you're
+	modifying a file, it uses the dirstate to store some extra
+	information so it can determine efficiently whether you have
+	modified a file.  For each file in the working directory, it
+	stores the time that it last modified the file itself, and the
+	size of the file at that time.</para>
+
+      <para id="x_336">When you explicitly <command role="hg-cmd" moreinfo="none">hg
+	  add</command>, <command role="hg-cmd" moreinfo="none">hg remove</command>,
+	<command role="hg-cmd" moreinfo="none">hg rename</command> or <command role="hg-cmd" moreinfo="none">hg copy</command> files, Mercurial updates the
+	dirstate so that it knows what to do with those files when you
+	commit.</para>
+
+      <para id="x_337">The dirstate helps Mercurial to efficiently
+	  check the status of files in a repository.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_726">When Mercurial checks the state of a file in the
+	    working directory, it first checks a file's modification
+	    time against the time in the dirstate that records when
+	    Mercurial last wrote the file. If the last modified time
+	    is the same as the time when Mercurial wrote the file, the
+	    file must not have been modified, so Mercurial does not
+	    need to check any further.</para>
+	</listitem>
+	<listitem>
+	  <para id="x_727">If the file's size has changed, the file must have
+	    been modified.  If the modification time has changed, but
+	    the size has not, only then does Mercurial need to
+	    actually read the contents of the file to see if it has
+	    changed.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para id="x_728">Storing the modification time and size dramatically
+	reduces the number of read operations that Mercurial needs to
+	perform when we run commands like <command moreinfo="none">hg status</command>.
+	This results in large performance improvements.</para>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch05 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:daily">
+  <?dbhtml filename="mercurial-in-daily-use.html"?>
+  <title>Mercurial pour une utilisation de tous les jours</title>
+
+  <sect1>
+    <title>Informer Mercurial des fichier à suivre</title>
+
+    <para id="x_1a3">Mercurial ne suit pas les fichiers de votre dépôt tant
+      que vous ne lui avez pas dit de les gérer. La commande <command role="hg-cmd" moreinfo="none">hg status</command> vous dira quels fichiers sont
+      inconnus de Mercurial. Il utilise un
+      <quote><literal moreinfo="none">?</literal></quote> pour montrer ces fichiers.</para>
+
+    <para id="x_1a4">Pour informer Mercurial de suivre un fichier, utilisez
+      la commande <command role="hg-cmd" moreinfo="none">hg add</command>. Une fois que vous
+      avez ajouté un fichier, la ligne correspondante à ce fichier dans la
+      sortie de <command role="hg-cmd" moreinfo="none">hg status</command> change de
+      <quote><literal moreinfo="none">?</literal></quote> à
+      <quote><literal moreinfo="none">A</literal></quote>.</para>
+
+    <!-- BEGIN daily.files.add -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init add-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd add-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; myfile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+? myfile.txt
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+A myfile.txt
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added one file'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+</screen>
+<!-- END daily.files.add -->
+
+
+    <para id="x_1a5">Après avoir exécuté un <command role="hg-cmd" moreinfo="none">hg
+        commit</command>, les fichiers que vous avez ajoutés avant le commit
+      ne seront plus listés dans la sortie de <command role="hg-cmd" moreinfo="none">hg
+        status</command>. La raison de ceci est que, par défaut, <command role="hg-cmd" moreinfo="none">hg status</command> ne vous montre que les fichiers
+      <quote>intéressants</quote> —ceux que vous avez (par exemple)
+      modifiés, supprimés ou renommés. Si vous aviez un dépôt qui contient un
+      millier de fichiers, vous ne voudriez certainement que rarement entendre
+      parler des fichiers que Mercurial suit, mais qui n'ont pas changés.
+      (Vous pouvez quand même avoir cette information, nous y reviendrons
+      plus tard.)</para>
+
+    <para id="x_1a6">Une fois que vous ajoutez un fichier, Mercurial ne fait
+      rien du tout avec celui-ci immédiatement. Au lieu de ça, il va prendre
+      un "snapshot" de l'état du fichier la prochaine fois que vous
+      exécuterez un commit. Il continuera ensuite à suivre les changements
+      que vous avez fait au fichier chaque fois que vous committerez, et ce,
+      jusqu'à ce que vous supprimiez le fichier.</para>
+
+    <sect2>
+      <title>Nommage des fichiers explicite versus implicite</title>
+
+      <para id="x_1a7">Un comportement utile que Mercurial possède est que si
+        vous passez le nom d'un répertoire à une commande, toute commande
+        Mercurial la traitera comme : <quote>Je veux opérer sur chaque fichier
+          dans ce répertoire et ses sous-répertoires</quote>.</para>
+
+      <!-- BEGIN daily.files.add-dir -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/somefile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c &gt; b/source.cpp</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b/d</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo d &gt; b/d/test.h</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
+adding b/d/test.h
+adding b/somefile.txt
+adding b/source.cpp
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added all files in subdirectory'</userinput>
+</screen>
+<!-- END daily.files.add-dir -->
+
+
+      <para id="x_1a8">Remarquez que dans cet exemple, Mercurial affiche le
+        nom des fichiers qu'il a ajouté, alors qu'il ne l'a pas fait lorsque
+        nous avons ajouté le fichier nommé <filename moreinfo="none">myfile.txt</filename>
+        dans l'exemple précédent.</para>
+
+      <para id="x_1a9">Ce qu'il se passe est que dans le premier cas, nous
+        avons nommé explicitement le fichier à ajouter sur la ligne de
+        commande. Ce que Mercurial suppose dans ce cas est que nous savons ce
+        que nous faisons, il n'affiche donc rien en sortie.</para>
+
+      <para id="x_1aa">Cependant, lorsque nous avons
+        <emphasis>implicitement</emphasis> donné les fichiers à l'aide du nom
+        d'un répertoire, Mercurial prend l'initiative d'afficher le nom de
+        chaque fichier avec lequel il fait quelque chose. Ceci clarifie ce
+        qu'il se passe et réduit la probabilité d'une mauvaise surprise
+        restée silencieuse. Ce comportement est commun à la plupart des
+        commandes Mercurial.</para>
+    </sect2>
+    <sect2>
+      <title>Mercurial suit les fichiers, pas les répertoires</title>
+
+      <para id="x_1ab">Mercurial ne suit pas les informations sur les
+        répertoires. En contrepartie, il suit le chemin vers un fichier. Avant
+        de créer un fichier, il crée au préalable les répertoires manquants
+        dans le chemin. Après avoir supprimé un fichier, il supprime chaque
+        répertoire vide qui apparaît dans le chemin du fichier. Ceci apparaît
+        comme une distinction triviale, cependant, cela a une conséquence
+        pratique mineure : il n'est pas possible de représenter un répertoire
+        totalement vide dans Mercurial.</para>
+
+      <para id="x_1ac">Les répertoires vides sont rarement utiles. Il existe
+        cependant des solutions alternatives et non intrusives que vous
+        pouvez utiliser pour obtenir l'effet approprié. Les développeurs de
+        Mercurial ont ainsi pensé que la complexité requise pour gérer les
+        répertoires n'était pas aussi importante que le bénéfice que cette
+        fonctionnalité apporterait.</para>
+
+      <para id="x_1ad">Si vous avez besoin d'un répertoire vide dans votre
+        dépôt, il existe quelques façons d'y arriver. L'une d'elles est de
+        créer un répertoire et ensuite, de faire un <command role="hg-cmd" moreinfo="none">hg
+          add</command> sur un fichier <quote>caché</quote> dans ce
+        répertoire. Sur les systèmes de type Unix, tout fichier dont le nom
+        commence avec un point (<quote><literal moreinfo="none">.</literal></quote>) est
+        considéré comme caché par la plupart des commandes et outils
+        graphiques. Cette approche est illustrée ci-après.</para>
+      
+      <!-- BEGIN daily.files.hidden -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hidden-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hidden-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir empty</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">touch empty/.hidden</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add empty/.hidden</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Manage an empty-looking directory'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls empty</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hidden-example tmp</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp</userinput>
+empty
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp/empty</userinput>
+</screen>
+<!-- END daily.files.hidden -->
+
+
+      <para id="x_1ae">Une autre façon de s'attaquer au besoin d'un
+        répertoire vide est de simplement d'en créer un dans vos scripts
+        de construction avant qu'ils n'en aient le besoin.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Comment arrêter de suivre un fichier</title>
+
+    <para id="x_1af">Une fois que vous décidez qu'un fichier n'appartient
+      plus à votre dépôt, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
+        remove</command>. Ceci supprime le fichier et informe Mercurial
+      d'arrêter de le suivre (ce qui prendra effet lors du prochain commit).
+      Un fichier supprimé est représenté dans la sortie de la commande
+      <command role="hg-cmd" moreinfo="none">hg status</command> par un
+      <quote><literal moreinfo="none">R</literal></quote>.</para>
+
+    <!-- BEGIN daily.files.remove -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init remove-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd remove-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a b</userinput>
+adding b/b
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Small example for file removal'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+R a
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove b</userinput>
+removing b/b
+</screen>
+<!-- END daily.files.remove -->
+
+
+    <para id="x_1b0">Après avoir fait un <command role="hg-cmd" moreinfo="none">hg
+        remove</command> sur un fichier, Mercurial ne suivra plus aucun
+      changement sur ce fichier, même si vous recréez un fichier avec le même
+      nom dans votre répertoire de travail. Si vous recréez un fichier avec le
+      même nom et que vous désirez que Mercurial suive ce dernier, faite
+      simplement un <command role="hg-cmd" moreinfo="none">hg add</command> sur celui-ci.
+      Mercurial saura alors que le nouveau fichier ne fait pas référence à
+      l'ancien fichier qui portait le même nom.</para>
+
+    <sect2>
+      <title>Supprimer un fichier n'affecte pas son historique</title>
+
+      <para id="x_1b1">Il est important de comprendre que supprimer un fichier
+        n'a que deux effets.</para>
+
+      <itemizedlist>
+        <listitem><para id="x_1b2">Il supprime la version actuelle de ce
+            fichier du répertoire de travail.</para>
+        </listitem>
+        <listitem><para id="x_1b3">Il arrête, à partir du prochain commit, le
+            suivi de Mercurial sur les changements qui ont lieu sur ce
+            fichier.</para>
+        </listitem></itemizedlist>
+        
+      <para id="x_1b4">Supprimer un fichier <emphasis>n'</emphasis>affecte en
+        <emphasis>aucun</emphasis> cas l'<emphasis>historique</emphasis> du
+        fichier.</para>
+
+      <para id="x_1b5">Si vous mettez à jour le répertoire de travail à un
+        changeset qui a été committé alors que le fichier que vous venez de
+        supprimer était encore suivi, ce fichier réapparaîtra dans le
+        répertoire de travail, avec le contenu qu'il avait lorsque vous aviez
+        committé ce changeset. Si vous mettez à jour (update) le répertoire de
+        travail à un changeset ultérieur dans lequel le fichier a été
+        supprimé, Mercurial supprimera une nouvelle fois le fichier du
+        répertoire de travail.</para>
+    </sect2>
+
+    <sect2>
+      <title>Fichiers manquants</title>
+
+      <para id="x_1b6">Mercurial considère qu'un fichier que vous avez
+        supprimé sans utiliser<command role="hg-cmd" moreinfo="none">hg remove</command>
+        comme étant <emphasis>manquant</emphasis>.  Un fichier manquant est
+        représenté avec un <quote><literal moreinfo="none">!</literal></quote> en sortie de
+        <command role="hg-cmd" moreinfo="none">hg status</command>.
+        Les commandes Mercurial ne feront rien avec les fichiers
+        manquants.</para>
+
+      <!-- BEGIN daily.files.missing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init missing-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd missing-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'File about to be missing'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+! a
+</screen>
+<!-- END daily.files.missing -->
+
+
+      <para id="x_1b7">Si votre dépôt contient un fichier que <command role="hg-cmd" moreinfo="none">hg status</command> reporte comme manquant, et que
+        vous voulez que ce fichier reste supprimé, vous pouvez exécuter
+        <command role="hg-cmd" moreinfo="none">hg remove <option role="hg-opt-remove">--after</option></command> à tout moment
+        pour dire à Mercurial que vous aviez bien voulu supprimer ce
+        fichier.</para>
+
+      <!-- BEGIN daily.files.remove-after -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove --after a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+R a
+</screen>
+<!-- END daily.files.remove-after -->
+
+
+      <para id="x_1b8">D'un autre coté, si vous avez supprimé le fichier
+        manquant par accident, donnez à la commande <command role="hg-cmd" moreinfo="none">hg
+          revert</command> le nom du fichier à retrouver. Il réapparaitra dans
+        sa forme non modifiée.</para>
+
+      <!-- BEGIN daily.files.recover-missing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat a</userinput>
+a
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+</screen>
+<!-- END daily.files.recover-missing -->
+
+    
+    </sect2>
+
+    <sect2>
+      <title>Entre nous : Pourquoi dire explicitement à Mercurial de supprimer un
+      fichier ?</title>
+
+      <para id="x_1b9">Vous pourriez vous demander pourquoi il est nécessaire
+        de dire explicitement à Mercurial que vous souhaitez supprimer un
+        fichier. Au début du développement de Mercurial, celui ci vous
+        laissait pourtant supprimer un fichier sans soucis ; Mercurial vous
+        aurait automatiquement informé de l'absence du fichier lorsque vous
+        auriez lancé un <command role="hg-cmd" moreinfo="none">hg commit</command> et arrêté
+        de le suivre. En pratique, ceci a montré qu'il était trop facile de
+        supprimer accidentellement un fichier sans le remarquer.</para>
+    </sect2>
+
+    <sect2>
+      <title>Raccourci utile—ajouter et supprimer des fichiers en une
+      seule étape.</title>
+
+      <para id="x_1ba">Mercurial offre une commande combinée, <command role="hg-cmd" moreinfo="none">hg addremove</command>, qui ajoute les fichiers non
+        suivis et marque les fichiers manquants comme supprimés.</para>
+
+      <!-- BEGIN daily.files.addremove -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init addremove-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd addremove-example</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg addremove</userinput>
+adding a
+adding b
+</screen>
+<!-- END daily.files.addremove -->
+
+
+      <para id="x_1bb">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
+        fournit aussi une option <option role="hg-opt-commit">-A</option> qui
+        exécute le même ajouter-et-supprimer, immédiatement suivi d'un
+        commit.</para>
+
+      <!-- BEGIN daily.files.commit-addremove -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c &gt; c</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Commit with addremove'</userinput>
+adding c
+</screen>
+<!-- END daily.files.commit-addremove -->
+
+    
+    </sect2>
+  </sect1>
+
+  <sect1 id="chap:daily.copy">
+    <title>Copier des fichiers</title>
+
+    <para id="x_1bc">Mercurial fournit une commande <command role="hg-cmd" moreinfo="none">hg
+        copy</command> qui vous permet de faire une nouvelle copie d'un
+      fichier. Lorsque vous copiez un fichier en utilisant cette commande,
+      Mercurial crée un enregistrement du fait que ce nouveau fichier est une
+      copie du fichier originel. Il traite ces fichiers copiés spécialement
+      lorsque vous fusionnez (merge) votre travail avec quelqu'un
+      d'autre.</para>
+
+    <sect2>
+      <title>Les résultats d'une copie durant une fusion (merge)</title>
+
+      <para id="x_1bd">Ce qu'il se passe durant une fusion (merge) est que
+        les changements <quote>suivent</quote> une copie. Pour illustrer ce
+        que cela veut dire de la meilleure façon, créons un exemple. Nous
+        allons commencer avec le mini dépôt usuel qui contient un simple
+        fichier.</para>
+
+      <!-- BEGIN daily.copy.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init my-copy</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo line &gt; file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added a file'</userinput>
+</screen>
+<!-- END daily.copy.init -->
+
+
+      <para id="x_1be">Nous devons faire du travail en parallèle, ainsi,
+        nous aurons quelque chose à fusionner (merge). Donc clonons notre
+        dépôt.</para>
+
+      <!-- BEGIN daily.copy.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone my-copy your-copy</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END daily.copy.clone -->
+
+
+      <para id="x_1bf">De retour dans notre dépôt initial, utilisons la
+        commande <command role="hg-cmd" moreinfo="none">hg copy</command> pour faire une
+        copie du premier fichier que nous avons créé.</para>
+
+      <!-- BEGIN daily.copy.copy -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
+</screen>
+<!-- END daily.copy.copy -->
+
+
+      <para id="x_1c0">Si nous regardons ensuite à la sortie de la commande
+        <command role="hg-cmd" moreinfo="none">hg status</command>, les fichiers copiés
+        ont l'air de fichiers normalement ajoutés.</para>
+
+      <!-- BEGIN daily.copy.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+A new-file
+</screen>
+<!-- END daily.copy.status -->
+
+
+      <para id="x_1c1">Mais si nous passons l'option <option role="hg-opt-status">-C</option> à <command role="hg-cmd" moreinfo="none">hg
+          status</command>, il affiche une autre ligne de sortie : il s'agit
+        du fichier <emphasis>source</emphasis> pour notre copie.</para>
+
+      <!-- BEGIN daily.copy.status-copy -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
+A new-file
+  file
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Copied file'</userinput>
+</screen>
+<!-- END daily.copy.status-copy -->
+
+
+      <para id="x_1c2">Maintenant, de retour dans le dépôt que nous avons
+        cloné, créons un changement en parallèle. Nous allons ajouter une
+        ligne de contenu au fichier original qui a été créé.</para>
+
+      <!-- BEGIN daily.copy.other -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../your-copy</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'new contents' &gt;&gt; file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Changed file'</userinput>
+</screen>
+<!-- END daily.copy.other -->
+
+
+      <para id="x_1c3">Nous avons alors un fichier <filename moreinfo="none">file</filename>
+        modifié dans ce dépôt. Lorsque nous récupérons (pull) les changements
+        depuis le premier répertoire et fusionnons (merge) les deux "heads",
+        Mercurial propagera les changements que nous avons faits localement
+        au fichier <filename moreinfo="none">file</filename> dans sa copie
+        <filename moreinfo="none">new-file</filename>.</para>
+
+      <!-- BEGIN daily.copy.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-copy</userinput>
+pulling from ../my-copy
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+(run 'hg heads' to see heads, 'hg merge' to merge)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+merging file and new-file to new-file
+0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat new-file</userinput>
+line
+new contents
+</screen>
+<!-- END daily.copy.merge -->
+
+    
+    </sect2>
+    <sect2 id="sec:daily:why-copy">
+      <title>Pourquoi est-ce que les changements devraient suivre les copies
+        ?</title>
+
+      <para id="x_1c4">Ce comportement—des changements d'un fichiers
+        qui se propagent aux copies de ce fichier—peut sembler
+        ésotérique, mais, dans la plupart des cas, c'est hautement
+        désirable.</para>
+
+      <para id="x_1c5">Pour commencer, souvenez vous que cette propagation
+        a lieue <emphasis>seulement</emphasis> lors des fusions (merge).
+        Donc, si vous faites un	<command role="hg-cmd" moreinfo="none">hg copy</command> sur
+        un fichier, et par la suite modifiez le fichier original durant le
+        cours normal de votre travail, rien n'a lieu.</para>
+
+      <para id="x_1c6">La deuxième chose à savoir c'est que les modifications
+        ne se propageront à travers une copie que si le changeset à partir
+        duquel vous faites une fusion (merge) <emphasis>n'a pas encore
+          vu</emphasis> la copie.</para>
+          
+      <para id="x_1c7">La raison pour laquelle Mercurial fait ainsi est une
+        règle. Imaginons que je corrige un important bug dans un fichier source
+        et que je commit mes changements. Pendant ce temps, vous avez décidé de
+        faire un <command role="hg-cmd" moreinfo="none">hg copy</command> du fichier dans
+        votre dépôt, sans rien savoir au sujet du bug ou à propos de la
+        correction. Vous avez alors commencé à "hacker" sur votre copie du
+        fichier.</para>
+
+      <para id="x_1c8">Si vous aviez récupéré (pull) et fusionné (merge) mes
+        changements, et que Mercurial <emphasis>n'avait pas</emphasis>
+        propagé les changements à travers les copies, votre nouveau fichier
+        source contiendrait maintenant le bug, et à moins que vous ne sachiez
+        qu'il faille propager la correction du bug à la main, le bug aurait
+        <emphasis>subsisté</emphasis> dans votre copie du fichier.</para>
+
+      <para id="x_1c9">En propageant automatiquement les changements qui
+        fixent les bugs à partir du fichier original vers les copies,
+        Mercurial prévient ce type de problèmes. A ma connaissance, Mercurial
+        est le <emphasis>seul</emphasis> système de gestion de révisions qui
+        propage les changements à travers les copies comme ceci.</para>
+
+      <para id="x_1ca">Une fois que votre historique des changements a un
+        enregistrement concernant une copie et qu'une fusion postérieure a
+        eu lieue, il n'y a d'habitude pas d'autre besoin de propager les
+        changements du fichier originel vers le fichier copié. C'est pourquoi
+        Mercurial ne propage les changements à travers les copies qu'à la
+        première fusion, et pas d'avantage.</para>
+    </sect2>
+
+    <sect2>
+      <title>Comment faire des changements qui <emphasis>ne</emphasis>
+      suivent <emphasis>pas</emphasis> une copie</title>
+
+      <para id="x_1cb">Si pour une raison ou une autre, vous décidez que
+        cette fonctionnalité de propager automatiquement les changements à
+        travers les copies n'est pas pour vous, utilisez simplement la
+        commande normale de copie de votre système (sur les systèmes de type
+        Unix, il s'agit de <command moreinfo="none">cp</command>) pour faire une copie d'un
+        fichier. Utilisez ensuite <command role="hg-cmd" moreinfo="none">hg add</command>
+        pour ajouter les nouveaux fichiers à la main. Cependant, avant d'en
+        faire ainsi, relisez <xref linkend="sec:daily:why-copy"/>, et faites
+        un choix en connaissance de cause comme quoi cette fonctionnalité
+        n'est pas appropriée à votre cas spécifique.</para>
+
+    </sect2>
+    <sect2>
+      <title>Comportement de la commande <command role="hg-cmd" moreinfo="none">hg copy</command></title>
+
+      <para id="x_1cc">Lorsque vous utilisez la commande <command role="hg-cmd" moreinfo="none">hg copy</command>, Mercurial crée une copie de chaque
+        fichier source tel qu'il est actuellement dans le répertoire de
+        travail. Cela signifie que si vous effectuez des modifications sur un
+        fichier, puis faites un <command role="hg-cmd" moreinfo="none">hg copy</command> sur
+        celui-ci sans avoir au préalable committé ces changements, la nouvelle
+        copie contiendra aussi les modifications que vous avez fait jusqu'à
+        ce point.	(Je trouve ce comportement quelque peu contre intuitif,
+        c'est pourquoi j'en fais mention ici.)</para>
+      <!-- Vérifier que je n'ai pas fait de contre sens en relisant la
+      version anglaise, ce que je comprend ici me paraît un peu bizarre -->
+
+      <para id="x_1cd">La commande <command role="hg-cmd" moreinfo="none">hg copy</command>
+        agit comme la commande Unix <command moreinfo="none">cp</command> (vous pouvez
+        utilisez l'alias <command role="hg-cmd" moreinfo="none">hg cp</command> si vous
+        préférez).  Nous devons lui donner deux ou plus arguments où le
+        dernier est considéré comme la <emphasis>destination</emphasis>, et
+        les autres comme les <emphasis>sources</emphasis>.</para>
+
+      <para id="x_685">Si vous passez à <command role="hg-cmd" moreinfo="none">hg
+          copy</command> un seul fichier source, et que la destination
+        n'existe pas, ceci créera un nouveau fichier avec ce nom.</para>
+
+      <!-- BEGIN daily.copy.simple -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir k</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a k</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls k</userinput>
+a
+</screen>
+<!-- END daily.copy.simple -->
+
+
+      <para id="x_1ce">Si la destination est un répertoire, Mercurial copie
+        les sources dans ce répertoire.</para>
+
+      <!-- BEGIN daily.copy.dir-dest -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir d</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a b d</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls d</userinput>
+a  b
+</screen>
+<!-- END daily.copy.dir-dest -->
+
+
+      <para id="x_1cf">La copie de répertoire est récursive et préserve la
+        structure du répertoire source.</para>
+
+      <!-- BEGIN daily.copy.dir-src -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z e</userinput>
+copying z/a/c to e/a/c
+</screen>
+<!-- END daily.copy.dir-src -->
+
+
+      <para id="x_1d0">Si la source et la destination sont tous deux des
+        répertoires, l'arborescence de la source est recréée dans le
+        répertoire destination.</para>
+    
+      <!-- BEGIN daily.copy.dir-src-dest -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z d</userinput>
+copying z/a/c to d/z/a/c
+</screen>
+<!-- END daily.copy.dir-src-dest -->
+
+
+      <para id="x_1d1">Comme avec la commande <command role="hg-cmd" moreinfo="none">hg
+          remove</command>, si vous copiez un fichier manuellement et voulez
+        que Mercurial sache qu'il s'agit d'une copie, utilisez simplement
+        l'option <option role="hg-opt-copy">--after</option> avec <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
+
+      <!-- BEGIN daily.copy.after -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp a n</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy --after a n</userinput>
+</screen>
+<!-- END daily.copy.after -->
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Renommer les fichiers</title>
+
+    <para id="x_1d2">Il est plus commun d'avoir besoin de renommer un
+      fichier que d'en faire une copie. La raison pour laquelle j'ai discuté
+      de la commande <command role="hg-cmd" moreinfo="none">hg copy</command> avant de parler
+      de renommage des fichiers est que Mercurial traite les renommages
+      essentiellement comme une copie. Ainsi, savoir comment Mercurial traite
+      les copies de fichiers vous informe sur ce que vous êtes en droit
+      d'attendre lorsque vous renommez un fichier.</para>
+
+    <para id="x_1d3">Lorsque vous utilisez la commande <command role="hg-cmd" moreinfo="none">hg rename</command>, Mercurial crée une copie de tous
+      les fichiers sources, les supprime et marque ces fichiers comme étant
+      supprimés.</para>
+
+    <!-- BEGIN daily.rename.rename -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
+</screen>
+<!-- END daily.rename.rename -->
+
+
+    <para id="x_1d4">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
+      montre les nouveaux fichiers comme ajoutés et les fichiers originaux
+      comme supprimés.</para>
+
+    <!-- BEGIN daily.rename.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+A b
+R a
+</screen>
+<!-- END daily.rename.status -->
+
+
+    <para id="x_1d5">A cause du <command role="hg-cmd" moreinfo="none">hg	copy</command>,
+      nous devons utiliser l'option <option role="hg-opt-status">-C</option>
+      pour la commande <command role="hg-cmd" moreinfo="none">hg status</command> afin
+      d'observer que le fichier ajouté est bien suivi par Mercurial comme
+      étant une copie de l'original maintenant supprimé.</para>
+
+    <!-- BEGIN daily.rename.status-copy -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
+A b
+  a
+R a
+</screen>
+<!-- END daily.rename.status-copy -->
+
+
+    <para id="x_1d6">Comme avec <command role="hg-cmd" moreinfo="none">hg remove</command> et
+      <command role="hg-cmd" moreinfo="none">hg copy</command>, vous pouvez informer
+      Mercurial au sujet d'un renommage après coup en utilisant l'option
+      <option role="hg-opt-rename">--after</option>. Dans le plus grand
+      respect, le comportement de la commande <command role="hg-cmd" moreinfo="none">hg
+        rename</command>, et les options qu'il accepte sont similaires à la
+      commande <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
+
+    <para id="x_686">Si vous êtes familier avec la ligne de commande Unix,
+      vous serez heureux d'apprendre que la commande <command role="hg-cmd" moreinfo="none">hg rename</command> peut être invoquée par <command role="hg-cmd" moreinfo="none">hg mv</command>.</para>
+
+    <sect2>
+      <title>Renommer les fichiers et fusionner (merge) les changements</title>
+
+      <para id="x_1d7">Puise que le "rename" de Mercurial est implanté comme un
+        "copy-and-remove", la même propagation des changements a lieue après
+        un "rename" qu'après un "copy" lorsque vous fusionnez (merge).</para>
+
+      <para id="x_1d8">Si je modifie un fichier et que vous le renommez, si
+        ensuite nous fusionnons nos changements respectifs, mes modifications
+        sur le fichier sous son nom originel seront propagés vers le même
+        fichier sous son nouveau nom. (C'est quelque chose que vous pourriez
+        espérer voir <quote>fonctionner simplement</quote>, mais tous les
+        systèmes de gestion de version ne le font pas.)</para>
+
+      <para id="x_1d9">Tandis qu'avoir des changements qui suivent une copie
+        est une fonctionnalité où vous hocheriez sûrement la tête en disant
+        <quote>oui, cela pourrait être utile</quote>, il est clair que les
+        voir suivre un renommage est définitivement important. Sans cette
+        aptitude, il serait vraiment trop facile d'avoir des changements
+        qui deviennent orphelins lorsque des fichiers sont renommés.</para>
+    </sect2>
+
+    <sect2>
+      <title>Renommages divergeants et fusion (merge)</title>
+
+      <para id="x_1da">Le cas de noms divergeants a lieu lorsque deux
+        développeurs commencent avec un fichier—appelons le
+        <filename moreinfo="none">foo</filename>—dans leurs dépôts respectifs.</para>
+
+      <!-- BEGIN rename.divergent.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig anne</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig bob</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END rename.divergent.clone -->
+
+
+      <para id="x_1db">Anne renomme le fichier en
+        <filename moreinfo="none">bar</filename>.</para>
+
+      <!-- BEGIN rename.divergent.rename.anne -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd anne</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename foo bar</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to bar'</userinput>
+</screen>
+<!-- END rename.divergent.rename.anne -->
+
+
+      <para id="x_1dc">Pendant ce temps, Bob le renomme en
+        <filename moreinfo="none">quux</filename>. (Souvenez vous que <command role="hg-cmd" moreinfo="none">hg mv</command> est un alias pour <command role="hg-cmd" moreinfo="none">hg rename</command>.)</para>
+    
+      <!-- BEGIN rename.divergent.rename.bob -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../bob</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg mv foo quux</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to quux'</userinput>
+</screen>
+<!-- END rename.divergent.rename.bob -->
+
+
+      <para id="x_1dd">J'aime à penser qu'il s'agit d'un conflit puisque
+        chaque développeur a exprimé différentes intentions au sujet de ce
+        que le nom de ce fichier aurait du être.</para>
+
+      <para id="x_1de">Que pensez vous qu'il devrait se produire lorsqu'ils
+        fusionnent (merge) leurs travaux ? Le comportement actuel de
+        Mercurial est qu'il préserve toujours les <emphasis>deux</emphasis>
+        noms lorsqu'il fusionne (merge) des changesets qui contiennent des
+        renommages divergeants.</para>
+
+      <!-- BEGIN rename.divergent.merge -->
+<screen format="linespecific"># See http://www.selenic.com/mercurial/bts/issue455
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../orig</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../anne</userinput>
+pulling from ../anne
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+1 files updated, 0 files merged, 1 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../bob</userinput>
+pulling from ../bob
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+(run 'hg heads' to see heads, 'hg merge' to merge)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+warning: detected divergent renames of foo to:
+ bar
+ quux
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
+bar  quux
+</screen>
+<!-- END rename.divergent.merge -->
+
+
+      <para id="x_1df">Remarquez que bien que Mercurial vous avertisse au
+        sujet de la divergeance des renommages, il vous laisse faire quelque
+        chose au sujet de la divergeance après la fusion (merge).</para>
+    </sect2>
+
+    <sect2>
+      <title>Renommages et fusion convergeants</title>
+
+      <para id="x_1e0">Un autre type de conflit de renommage intervient
+        lorsque deux personne choisissent de renommer différents fichiers
+        <emphasis>source</emphasis> vers la même
+        <emphasis>destination</emphasis>. Dans ce cas, Mercurial exécute la
+        machinerie normale de fusion (merge) et vous guide vers une
+        solution convenable.</para>
+    </sect2>
+
+    <sect2>
+      <title>Autres cas anguleux relatifs aux noms</title>
+
+      <para id="x_1e1">Mercurial possède un bug de longue date dans lequel il
+        échoue à traiter une fusion (merge) où un coté a un fichier avec un
+        nom donné, alors que l'autre coté possède un répertoire avec le même nom.
+        Ceci est documenté dans l'<ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue
+          29</ulink>.</para>
+
+      <!-- BEGIN issue29.go -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init issue29</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd issue29</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Ama</userinput>
+adding a
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amb</userinput>
+adding b
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg up 0</userinput>
+0 files updated, 0 files merged, 1 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amc</userinput>
+adding b/b
+created new head
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+abort: Is a directory: /tmp/issue29vhrzWD/issue29/b
+</screen>
+<!-- END issue29.go -->
+
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Récupération d'erreurs</title>
+
+    <para id="x_1e2">Mercurial possède certaines commandes utiles qui vont
+      vous aider à récupérer de certaines erreurs communes.</para>
+
+    <para id="x_1e3">La commande <command role="hg-cmd" moreinfo="none">hg revert</command>
+      vous permet d'annuler les changements que vous avez faits dans votre
+      répertoire de travail. Par exemple, si vous faites un <command role="hg-cmd" moreinfo="none">hg add</command> sur un fichier par accident, exécutez
+      juste <command role="hg-cmd" moreinfo="none">hg	revert</command> avec le nom du fichier
+      que vous avez ajouté et tandis que le fichier ne sera touché d'une
+      quelconque manière, il ne sera plus suivi comme ajouté par Mercurial.
+      Vous pouvez aussi utiliser la commande <command role="hg-cmd" moreinfo="none">hg
+        revert</command> pour vous débarrasser de modifications erronés
+      apportées à un fichier.</para>
+
+    <para id="x_1e4">Il est utile de se souvenir que la commande <command role="hg-cmd" moreinfo="none">hg revert</command> est utile pour les modifications
+      qui n'ont pas encore été committées. Une fois que vous avez committé un
+      changement, si vous décidez qu'il s'agissait d'une erreur, vous pouvez
+      toujours faire quelque chose à ce sujet, bien que vos options soient
+      un peu plus limitées.</para>
+
+    <para id="x_1e5">Pour plus d'informations au sujet de la commande
+      <command role="hg-cmd" moreinfo="none">hg revert</command>, et des détails sur comment
+      traiter les modifications que vous avez déjà committées, référez vous à
+      <xref linkend="chap:undo"/>.</para>
+  </sect1>
+
+  <sect1>
+    <title>Traiter avec les fusions (merge) malicieuses</title>
+
+    <para id="x_687">Dans des projets compliqués ou conséquents, il n'est pas
+      rare qu'une fusion (merge) de deux changesets finisse par une migraine.
+      Supposez qu'il y ait un gros fichier source qui ait été largement édité de
+      chaque coté de la fusion (merge) : ceci va inévitablement résulter en
+      conflits, dont certains peuvent prendre plusieurs essais pour s'en
+      sortir.</para>
+
+    <para id="x_688">Développons en un cas simple pour voir comment le gérer.
+      Nous allons commencer avec un dépôt contenant un fichier, et le
+      cloner deux fois.</para>
+
+    <!-- BEGIN ch04/resolve.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init conflict</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd conflict</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first &gt; myfile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -A -m first</userinput>
+adding myfile.txt
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict left</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict right</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END ch04/resolve.init -->
+
+
+    <para id="x_689">Dans un des clones, nous allons modifier le fichier
+      d'une façon.</para>
+
+    <!-- BEGIN ch04/resolve.left -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd left</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo left &gt;&gt; myfile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m left</userinput>
+</screen>
+<!-- END ch04/resolve.left -->
+
+
+    <para id="x_68a">Dans un autre, nous allons modifier le fichier
+      différemment.</para>
+
+    <!-- BEGIN ch04/resolve.right -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../right</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo right &gt;&gt; myfile.txt</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m right</userinput>
+</screen>
+<!-- END ch04/resolve.right -->
+
+
+    <para id="x_68b">Ensuite, nous allons récupérer (pull) chaque ensemble de
+      changement dans notre dépôt original.</para>
+
+    <!-- BEGIN ch04/resolve.pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../conflict</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../left</userinput>
+pulling from ../left
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../right</userinput>
+pulling from ../right
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+not updating, since new heads added
+(run 'hg heads' to see heads, 'hg merge' to merge)
+</screen>
+<!-- END ch04/resolve.pull -->
+
+
+    <para id="x_68c">Nous nous attendons à ce que notre dépôt contienne deux
+      "heads".</para>
+
+    <!-- BEGIN ch04/resolve.heads -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
+changeset:   2:85f1afc84c33
+tag:         tip
+parent:      0:14a820f81f48
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:51 2009 +0000
+summary:     right
+
+changeset:   1:085ebbf44348
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:51 2009 +0000
+summary:     left
+
+</screen>
+<!-- END ch04/resolve.heads -->
+
+
+    <para id="x_68d">Normalement, si nous lançons <command role="hg-cmd" moreinfo="none">hg
+        merge</command> à ce point, il nous renverra vers une interface
+      utilisateur qui nous permettra de résoudre manuellement les éditions
+      conflictuelles sur le fichier <filename moreinfo="none">myfile.txt</filename>.
+      Cependant, pour simplifier ici les choses dans la présentation, nous
+      aimerions plutôt que la fusion (merge) échoue immédiatement. Voici une
+      façon de le faire.</para>
+
+    <!-- BEGIN ch04/resolve.export -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=false</userinput>
+</screen>
+<!-- END ch04/resolve.export -->
+
+
+    <para id="x_68e">Nous avons dit au processus de fusion de Mercurial
+      d'exécuter la commande <command moreinfo="none">false</command> (qui échoue
+      immédiatement, à la demande) s'il détecte une fusion (merge) qu'il ne
+      peut pas arranger automatiquement.</para>
+
+    <para id="x_68f">Si nous appelons maintenant <command role="hg-cmd" moreinfo="none">hg
+        merge</command>, il devrait échouer et reporter une erreur.</para>
+
+    <!-- BEGIN ch04/resolve.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+merging myfile.txt
+merging myfile.txt failed!
+0 files updated, 0 files merged, 0 files removed, 1 files unresolved
+use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
+</screen>
+<!-- END ch04/resolve.merge -->
+
+
+    <para id="x_690">Même si nous ne remarquons pas qu'une fusion (merge) a
+      échoué, Mercurial nous empêchera de committer le résultat d'une fusion
+      ratée.</para>
+
+    <!-- BEGIN ch04/resolve.cifail -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Attempt to commit a failed merge'</userinput>
+abort: unresolved merge conflicts (see hg resolve)
+</screen>
+<!-- END ch04/resolve.cifail -->
+
+
+    <para id="x_691">Lorsque <command role="hg-cmd" moreinfo="none">hg commit</command>
+      échoue dans ce cas, il suggère que nous utilisons la commande peu
+      connue <command role="hg-cmd" moreinfo="none">hg resolve</command>.  Comme d'habitude,
+      <command role="hg-cmd" moreinfo="none">hg help resolve</command> affichera une aide
+      sommaire.</para>
+
+    <sect2>
+      <title>États de résolution des fichiers</title>
+      <!-- TODO Vérifier traduction : File resolution states -->
+
+      <para id="x_692">Lorsqu'une fusion intervient, la plupart des fichiers
+        vont, la plupart du temps, rester sans modification. Pour chaque
+        fichier sur lequel Mercurial doit faire quelque chose, il suit l'état
+        de celui-ci.</para>
+
+      <itemizedlist>
+        <listitem><para id="x_693">Un fichier
+            <quote><emphasis>resolved</emphasis></quote> a été fusionné
+            (merge) avec succès, que ce soit automatiquement par Mercurial ou
+            manuellement par une intervention humaine.</para></listitem>
+        <listitem><para id="x_694">Un fichier
+            <quote><emphasis>unresolved</emphasis></quote> n'a pas été
+            fusionné (merge) correctement et a besoin de plus
+            d'attention.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para id="x_695">Si Mercurial voit un fichier
+        <emphasis>quelconque</emphasis> dans un état
+        <quote>unresolved</quote> après une fusion (merge), il considère que
+        la fusion (merge) a échoué. Heureusement, nous n'avons pas à
+        recommencer la procédure à partir du début.</para>
+
+      <para id="x_696">L'option <option role="hg-opt-resolve">--list</option>
+        ou <option role="hg-opt-resolve">-l</option> passée à <command role="hg-cmd" moreinfo="none">hg resolve</command> liste l'état de chaque fichier
+        fusionné (merge).</para>
+
+      <!-- BEGIN ch04/resolve.list -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -l</userinput>
+U myfile.txt
+</screen>
+<!-- END ch04/resolve.list -->
+
+
+      <para id="x_697">En sortie de <command role="hg-cmd" moreinfo="none">hg
+          resolve</command>, un fichier "resolved" est marqué avec un
+        <literal moreinfo="none">R</literal>, alors qu'un fichier "unresolved" est marqué
+        d'un <literal moreinfo="none">U</literal>.  S'il existe un fichier listé avec un
+        <literal moreinfo="none">U</literal>, nous savons qu'essayer de committer le résultat
+        de la fusion (merge) échouera.</para>
+    </sect2>
+
+    <sect2>
+      <title>Résoudre une fusion de fichier</title>
+
+      <para id="x_698">Nous avons plusieurs options pour changer l'état d'un
+        fichier de "unresolved" à "resolved". Le plus commun est de relancer
+        <command role="hg-cmd" moreinfo="none">hg resolve</command>. Si nous passons les noms
+        des fichiers individuels ou des répertoires, ceci retentera la fusion
+        de tous les fichiers présents à cet endroit. Nous pouvons aussi
+        passer l'option <option role="hg-opt-resolve">--all</option> ou
+        <option role="hg-opt-resolve">-a</option> qui tentera de fusionner
+        <emphasis>tous</emphasis> les fichiers "unresolved".</para>
+
+      <para id="x_699">Mercurial nous laisse aussi modifier la résolution
+        d'un fichier directement. Nous pouvons marquer un fichier "resolved"
+        en utilisant l'option <option role="hg-opt-resolve">--mark</option>,
+        ou "unresolved" en utilisant l'option <option role="hg-opt-resolve">--unmark</option>. Ceci nous autorise à
+        nettoyer une fusion particulièrement compliquée à la main, et de
+        garder un suivi de nos progrès avec chaque fichier pendant que nous
+        procédons.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Des "diffs" plus utiles</title>
+
+    <para id="x_6c7">La sortie par défaut de la commande <command role="hg-cmd" moreinfo="none">hg diff</command> est compatible rétrospectivement avec
+      la commande régulière <command moreinfo="none">diff</command>, mais ceci a quelques
+      inconvénients.</para>
+
+    <para id="x_6c8">Considérez le cas où nous utilisons <command role="hg-cmd" moreinfo="none">hg
+        rename</command> pour renommer un fichier.</para>
+
+    <!-- BEGIN ch04/diff.rename.basic -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+diff -r f5deb7868663 a
+--- a/a	Sun Aug 16 14:04:49 2009 +0000
++++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
+@@ -1,1 +0,0 @@
+-a
+diff -r f5deb7868663 b
+--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
++++ b/b	Sun Aug 16 14:04:49 2009 +0000
+@@ -0,0 +1,1 @@
++a
+</screen>
+<!-- END ch04/diff.rename.basic -->
+
+
+    <para id="x_6c9">La sortie de <command role="hg-cmd" moreinfo="none">hg diff</command>
+      ci-dessus cache le fait que nous avons simplement renommé un fichier.
+      La commande <command role="hg-cmd" moreinfo="none">hg diff</command> accepte l'option
+      <option>--git</option> ou <option>-g</option> pour utiliser un nouveau
+      format de diff qui montre ces informations sous une forme plus
+      expressive.</para>
+
+    <!-- BEGIN ch04/diff.rename.git -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
+diff --git a/a b/b
+rename from a
+rename to b
+</screen>
+<!-- END ch04/diff.rename.git -->
+
+
+    <para id="x_6ca">Cette option peut aussi aider avec le cas autrement
+      confus : un fichier qui apparaît comme étant modifié en accord avec
+      <command role="hg-cmd" moreinfo="none">hg status</command>, mais où <command role="hg-cmd" moreinfo="none">hg diff</command> n'affiche rien. Cette situation peut
+      survenir si nous changeons les permissions d'exécution du
+      fichier.</para>
+
+    <!-- BEGIN ch04/diff.chmod -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg st</userinput>
+M a
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+</screen>
+<!-- END ch04/diff.chmod -->
+
+
+    <para id="x_6cb">La commande normale <command moreinfo="none">diff</command> ne fait pas
+      attention aux permissions des fichiers, ce qui explique pourquoi
+      <command role="hg-cmd" moreinfo="none">hg diff</command> n'affiche rien du tout par
+      défaut. Si nous lui passons l'option <option>-g</option>, ceci nous
+      informe de ce qu'il s'est vraiment passé.</para>
+
+    <!-- BEGIN ch04/diff.chmod.git -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
+diff --git a/a b/a
+old mode 100644
+new mode 100755
+</screen>
+<!-- END ch04/diff.chmod.git -->
+
+  </sect1>
+
+  <sect1>
+    <title>Quels fichiers suivre et lesquels éviter</title>
+
+    <para id="x_6cc">Les systèmes de gestion de révisions sont en général
+      meilleurs pour gérer les fichiers textes qui sont écrits par les
+      humains, comme le code source, où les fichiers ne changent pas
+      énormément d'une révision à l'autre. Certains systèmes de gestion de
+      révisions centralisés peuvent aussi traiter très convenablement les
+      fichiers binaires, tels que les images bitmap.</para>
+
+    <para id="x_6cd">Par exemple, une équipe de développement de jeux va
+      probablement gérer les deux types : ses codes source et tous ses binaires
+      (ex. données géométriques, textures, schémas de cartes) dans un système
+      de contrôle de révisions.</para>
+    <!-- Vérifier la traduction de map layouts que j'ai traduit par schémas
+    de cartes -->
+
+    <para id="x_6ce">Puisqu'il est d'habitude impossible de fusionner (merge)
+      deux modifications conflictuelles sur un fichier binaire, les systèmes
+      de version centralisés offrent souvent un mécanisme de verrou (lock) qui
+      permet à un utilisateur de dire <quote>Je suis la seule personne qui
+        peut éditer ce fichier</quote>.</para>
+
+    <para id="x_6cf">En comparaison avec un système centralisé, un système
+      décentralisé de gestion de révision change certains facteurs qui
+      guident les décisions sur quels fichiers gérer et comment.</para>
+
+    <para id="x_6d0">Par exemple, un système distribué de gestion de révisions
+      ne peut pas, par sa nature, offrir un système de véroux (lock) sur les
+      fichiers. Il n'y a donc pas de mécanisme inclus pour empêcher deux
+      personnes de faire des modifications conflictuelles sur un fichier
+      binaire. Si vous avez une équipe où plusieurs personnes peuvent souvent
+      éditer un fichier binaire, cela ne serait pas une très bonne idée
+      d'utiliser Mercurial —ou tout autre système distribué de gestion
+      de révisions—pour gérer ces fichiers.</para>
+
+    <para id="x_6d1">Lorsque vous sauvegardez les modifications sur un
+      fichier, Mercurial ne sauvegarde d'habitude que les différences entre
+      la version précédente et la version actuelle d'un fichier. Pour la
+      plupart des fichiers texte, ceci est très efficace. Cependant, certains
+      fichiers (en particulier les fichiers binaires) sont construits d'une
+      façon que même un petit changement sur un contenu logique résulte sur
+      un changement de la plupart des octets du fichier. Par exemple, les
+      fichiers compressés sont particulièrement sujets à ce comportement. Si
+      les différences entre deux versions successives d'un fichier sont
+      toujours très grandes, Mercurial ne sera pas capable de sauvegarder
+      l'historique des révisions sur le fichier très efficacement. Ceci peut
+      affecter aussi bien les besoins pour la sauvegarde locale que le temps
+      nécessaire à cloner le dépôt.</para>
+
+    <para id="x_6d2">Pour avoir une idée de comment ceci pourrait vous
+      affecter en pratique, supposez que nous voulions que Mercurial gère des
+      documents OpenOffice. OpenOffice sauvegarde les documents sur le disque
+      comme des fichiers compressés zip. Même le fait d'éditer ces fichiers
+      d'une seule lettre, changera les bits de la quasi totalité du fichier
+      lorsque vous le sauvegarderez. Maintenant, supposez que ce fichier
+      fasse une taille de 2Mo. Puisque la plupart du fichier change à chaque
+      fois que vous sauvegardez, Mercurial aura à sauvegarder tous les 2Mo du
+      fichier à chaque commit, alors que de votre point de vue, il n'y a
+      que peu de mots qui changent à chaque fois. Un seul fichier
+      souvent édité qui n'est pas bien traité par les hypothèses que Mercurial
+      fait sur les sauvegardes peut facilement avoir un effet colossal sur la
+      taille du dépôt.</para>
+
+    <para id="x_6d3">Même pire, si vous et quelqu'un d'autre éditez le même
+      document OpenOffice sur lequel vous travaillez, il n'y a pas de façon
+      utile pour fusionner votre travail. En fait, il n'y a pas de moyen
+      utile de montrer que les différences sont faites à partir de votre
+      vision des modifications.</para>
+
+    <para id="x_6d4">Il y a ainsi quelques recommandations claires sur les
+      types de fichiers spécifiques avec lesquels faire très
+      attention.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_6d5">Les fichier qui sont très gros et
+          incompressibles, comme les images ISO de CD-ROM, sont, par
+          construction très gros et les cloner à travers un réseau sera très
+          long.</para></listitem>
+     <!-- TODO : Trouver une meilleure traduction pour : ISO CD-ROM images, will by
+     virtue of sheer size make clones over a network very slow. -->
+      <listitem><para id="x_6d6">Les fichiers qui changent beaucoup d'une
+          révision à l'autre peuvent être très chers à sauvegarder si vous
+          les éditez fréquemment, de même que les conflits entre deux éditions
+          concurrentes peuvent être difficiles à résoudre.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Sauvegardes et miroirs</title>
+
+    <para id="x_6d7">Puisque Mercurial maintient une copie complète de
+      l'historique de chaque clone, toute personne qui utilise Mercurial pour
+      collaborer à un projet peut potentiellement agir comme une source de
+      sauvegarde si une catastrophe survenait. Si un dépôt central devient
+      indisponible, vous pouvez construire un remplaçant en clonant une copie
+      du dépôt à partir d'un des contributeurs en récupérant (pull) tous les
+      changements qui n'auraient pas été vus par les autres.</para>
+
+    <para id="x_6d8">Il est simple d'utiliser Mercurial pour construire des
+      serveurs hors site de sauvegarde et des miroirs distants. Initiez une
+      tâche périodique (ex. via la commande <command moreinfo="none">cron</command>) sur un
+      serveur distant pour récupérer (pull) les changements de votre dépôt
+      distant chaque heure. Ceci sera difficile seulement dans le cas
+      improbable où le nombre des dépôts maîtres que vous maintenez change
+      souvent, auquel cas vous aurez besoin de faire un peu de scripting pour
+      rafraichir la liste des dépôt à sauvegarder.</para>
+
+    <para id="x_6d9">Si vous exécutez des sauvegardes traditionnelles de
+      votre dépôt maître sur bande ou disque, et que vous voulez sauvegarder
+      un dépôt nommé <filename moreinfo="none">myrepo</filename>, utilisez la commande
+      <command moreinfo="none">hg clone -U myrepo myrepo.bak</command> pour créer un clone de
+      <filename moreinfo="none">myrepo</filename> avant de commencer vos backups.
+      L'option <option>-U</option> ne crée pas de répertoire de travail après
+      que le clone soit accompli, puisque ceci serait superflu et ferait que
+      la sauvegarde prenne plus de temps.</para>
+
+    <para id="x_6da">Si vous voulez ensuite sauvegarder
+      <filename moreinfo="none">myrepo.bak</filename> au lieu de <filename moreinfo="none">myrepo</filename>,
+      vous aurez la garantie d'avoir une image (snapshot) consistante de
+      votre dépôt sur lequel un développeur insomniaque n'enverra (push) pas de
+      changements en milieu de sauvegarde.</para>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch06 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="cha:collab">
+  <?dbhtml filename="collaborating-with-other-people.html"?>
+  <title>Collaborating with other people</title>
+
+  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
+    any policy on how people ought to work with each other.  However,
+    if you're new to distributed revision control, it helps to have
+    some tools and examples in mind when you're thinking about
+    possible workflow models.</para>
+
+  <sect1>
+    <title>Mercurial's web interface</title>
+
+    <para id="x_44b">Mercurial has a powerful web interface that provides several
+      useful capabilities.</para>
+
+    <para id="x_44c">For interactive use, the web interface lets you browse a
+      single repository or a collection of repositories.  You can view
+      the history of a repository, examine each change (comments and
+      diffs), and view the contents of each directory and file.  You
+      can even get a view of history that gives a graphical view of
+      the relationships between individual changes and merges.</para>
+
+    <para id="x_44d">Also for human consumption, the web interface provides
+      Atom and RSS feeds of the changes in a repository.  This lets you
+      <quote>subscribe</quote> to a repository using your favorite
+      feed reader, and be automatically notified of activity in that
+      repository as soon as it happens.  I find this capability much
+      more convenient than the model of subscribing to a mailing list
+      to which notifications are sent, as it requires no additional
+      configuration on the part of whoever is serving the
+      repository.</para>
+
+    <para id="x_44e">The web interface also lets remote users clone a repository,
+      pull changes from it, and (when the server is configured to
+      permit it) push changes back to it.  Mercurial's HTTP tunneling
+      protocol aggressively compresses data, so that it works
+      efficiently even over low-bandwidth network connections.</para>
+
+    <para id="x_44f">The easiest way to get started with the web interface is to
+      use your web browser to visit an existing repository, such as
+      the master Mercurial repository at <ulink url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
+
+    <para id="x_450">If you're interested in providing a web interface
+      to your own repositories, there are several good ways to do
+      this.</para>
+
+    <para id="x_69d">The easiest and fastest way to get started in an informal
+      environment is to use the <command role="hg-cmd" moreinfo="none">hg
+	serve</command> command, which is best suited to short-term
+      <quote>lightweight</quote> serving.  See <xref linkend="sec:collab:serve"/> below for details of how to use
+      this command.</para>
+
+    <para id="x_69e">For longer-lived repositories that you'd like to
+      have permanently available, there are several public hosting
+      services available.  Some are free to open source projects,
+      while others offer paid commercial hosting.  An up-to-date list
+      is available at <ulink url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
+
+    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
+      has built-in support for several popular hosting technologies,
+      most notably CGI (Common Gateway Interface), and WSGI (Web
+      Services Gateway Interface).  See <xref linkend="sec:collab:cgi"/> for details of CGI and WSGI
+      configuration.</para>
+  </sect1>
+
+  <sect1>
+    <title>Collaboration models</title>
+
+    <para id="x_451">With a suitably flexible tool, making decisions about
+      workflow is much more of a social engineering challenge than a
+      technical one. Mercurial imposes few limitations on how you can
+      structure the flow of work in a project, so it's up to you and
+      your group to set up and live with a model that matches your own
+      particular needs.</para>
+
+    <sect2>
+      <title>Factors to keep in mind</title>
+
+      <para id="x_452">The most important aspect of any model that you must keep
+	in mind is how well it matches the needs and capabilities of
+	the people who will be using it.  This might seem
+	self-evident; even so, you still can't afford to forget it for
+	a moment.</para>
+
+      <para id="x_453">I once put together a workflow model that seemed to make
+	perfect sense to me, but that caused a considerable amount of
+	consternation and strife within my development team.  In spite
+	of my attempts to explain why we needed a complex set of
+	branches, and how changes ought to flow between them, a few
+	team members revolted.  Even though they were smart people,
+	they didn't want to pay attention to the constraints we were
+	operating under, or face the consequences of those constraints
+	in the details of the model that I was advocating.</para>
+
+      <para id="x_454">Don't sweep foreseeable social or technical problems under
+	the rug. Whatever scheme you put into effect, you should plan
+	for mistakes and problem scenarios.  Consider adding automated
+	machinery to prevent, or quickly recover from, trouble that
+	you can anticipate.  As an example, if you intend to have a
+	branch with not-for-release changes in it, you'd do well to
+	think early about the possibility that someone might
+	accidentally merge those changes into a release branch.  You
+	could avoid this particular problem by writing a hook that
+	prevents changes from being merged from an inappropriate
+	branch.</para>
+    </sect2>
+
+    <sect2>
+      <title>Informal anarchy</title>
+
+      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
+	approach as something sustainable, but it's a model that's
+	easy to grasp, and it works perfectly well in a few unusual
+	situations.</para>
+
+      <para id="x_456">As one example, many projects have a loose-knit group of
+	collaborators who rarely physically meet each other.  Some
+	groups like to overcome the isolation of working at a distance
+	by organizing occasional <quote>sprints</quote>.  In a sprint,
+	a number of people get together in a single location (a
+	company's conference room, a hotel meeting room, that kind of
+	place) and spend several days more or less locked in there,
+	hacking intensely on a handful of projects.</para>
+
+      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
+	<command role="hg-cmd" moreinfo="none">hg serve</command> command, since
+	<command role="hg-cmd" moreinfo="none">hg serve</command> does not require any
+	fancy server infrastructure.  You can get started with
+	<command role="hg-cmd" moreinfo="none">hg serve</command> in moments, by
+	reading <xref linkend="sec:collab:serve"/> below.  Then simply
+	tell the person next to you that you're running a server, send
+	the URL to them in an instant message, and you immediately
+	have a quick-turnaround way to work together.  They can type
+	your URL into their web browser and quickly review your
+	changes; or they can pull a bugfix from you and verify it; or
+	they can clone a branch containing a new feature and try it
+	out.</para>
+
+      <para id="x_458">The charm, and the problem, with doing things
+	in an ad hoc fashion like this is that only people who know
+	about your changes, and where they are, can see them.  Such an
+	informal approach simply doesn't scale beyond a handful
+	people, because each individual needs to know about
+	<emphasis>n</emphasis> different repositories to pull
+	from.</para>
+    </sect2>
+
+    <sect2>
+      <title>A single central repository</title>
+
+      <para id="x_459">For smaller projects migrating from a centralised revision
+	control tool, perhaps the easiest way to get started is to
+	have changes flow through a single shared central repository.
+	This is also the most common <quote>building block</quote> for
+	more ambitious workflow schemes.</para>
+
+      <para id="x_45a">Contributors start by cloning a copy of this repository.
+	They can pull changes from it whenever they need to, and some
+	(perhaps all) developers have permission to push a change back
+	when they're ready for other people to see it.</para>
+
+      <para id="x_45b">Under this model, it can still often make sense for people
+	to pull changes directly from each other, without going
+	through the central repository.  Consider a case in which I
+	have a tentative bug fix, but I am worried that if I were to
+	publish it to the central repository, it might subsequently
+	break everyone else's trees as they pull it.  To reduce the
+	potential for damage, I can ask you to clone my repository
+	into a temporary repository of your own and test it.  This
+	lets us put off publishing the potentially unsafe change until
+	it has had a little testing.</para>
+
+      <para id="x_45c">If a team is hosting its own repository in this
+	kind of scenario, people will usually use the
+	<command moreinfo="none">ssh</command> protocol to securely push changes to
+	the central repository, as documented in <xref linkend="sec:collab:ssh"/>.  It's also usual to publish a
+	read-only copy of the repository over HTTP, as in
+	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
+	satisfies the needs of people who don't have push access, and
+	those who want to use web browsers to browse the repository's
+	history.</para>
+    </sect2>
+
+    <sect2>
+      <title>A hosted central repository</title>
+
+      <para id="x_6a1">A wonderful thing about public hosting services like
+	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
+	not only do they handle the fiddly server configuration
+	details, such as user accounts, authentication, and secure
+	wire protocols, they provide additional infrastructure to make
+	this model work well.</para>
+
+      <para id="x_6a2">For instance, a well-engineered hosting service will let
+	people clone their own copies of a repository with a single
+	click.  This lets people work in separate spaces and share
+	their changes when they're ready.</para>
+
+      <para id="x_6a3">In addition, a good hosting service will let people
+	communicate with each other, for instance to say <quote>there
+	  are changes ready for you to review in this
+	  tree</quote>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Working with multiple branches</title>
+
+      <para id="x_45d">Projects of any significant size naturally tend to make
+	progress on several fronts simultaneously.  In the case of
+	software, it's common for a project to go through periodic
+	official releases.  A release might then go into
+	<quote>maintenance mode</quote> for a while after its first
+	publication; maintenance releases tend to contain only bug
+	fixes, not new features.  In parallel with these maintenance
+	releases, one or more future releases may be under
+	development.  People normally use the word
+	<quote>branch</quote> to refer to one of these many slightly
+	different directions in which development is
+	proceeding.</para>
+
+      <para id="x_45e">Mercurial is particularly well suited to managing a number
+	of simultaneous, but not identical, branches.  Each
+	<quote>development direction</quote> can live in its own
+	central repository, and you can merge changes from one to
+	another as the need arises.  Because repositories are
+	independent of each other, unstable changes in a development
+	branch will never affect a stable branch unless someone
+	explicitly merges those changes into the stable branch.</para>
+
+      <para id="x_45f">Here's an example of how this can work in practice.  Let's
+	say you have one <quote>main branch</quote> on a central
+	server.</para>
+
+      <!-- BEGIN branching.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init main</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a boring feature.' &gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'We have reached an important milestone!'</userinput>
+adding myfile
+</screen>
+<!-- END branching.init -->
+
+
+      <para id="x_460">People clone it, make changes locally, test them, and push
+	them back.</para>
+
+      <para id="x_461">Once the main branch reaches a release milestone, you can
+	use the <command role="hg-cmd" moreinfo="none">hg tag</command> command to
+	give a permanent name to the milestone revision.</para>
+
+	<!-- BEGIN branching.tag -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   1:5e447fdaf941
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:47 2009 +0000
+summary:     Added tag v1.0 for changeset 6412b791fd06
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
+tip                                1:5e447fdaf941
+v1.0                               0:6412b791fd06
+</screen>
+<!-- END branching.tag -->
+
+
+      <para id="x_462">Let's say some ongoing
+	development occurs on the main branch.</para>
+
+      <!-- BEGIN branching.main -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is exciting and new!' &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add a new feature'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+This is a boring feature.
+This is exciting and new!
+</screen>
+<!-- END branching.main -->
+
+
+      <para id="x_463">Using the tag that was recorded at the milestone, people
+	who clone that repository at any time in the future can use
+	<command role="hg-cmd" moreinfo="none">hg update</command> to get a copy of
+	the working directory exactly as it was when that tagged
+	revision was committed.</para>
+
+      <!-- BEGIN branching.update -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -U main main-old</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main-old</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update v1.0</userinput>
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+This is a boring feature.
+</screen>
+<!-- END branching.update -->
+
+
+      <para id="x_464">In addition, immediately after the main branch is tagged,
+	we can then clone the main branch on the server to a new
+	<quote>stable</quote> branch, also on the server.</para>
+
+      <!-- BEGIN branching.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -rv1.0 main stable</userinput>
+requesting all changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END branching.clone -->
+
+
+      <para id="x_465">If we need to make a change to the stable
+	branch, we can then clone <emphasis>that</emphasis>
+	repository, make our changes, commit, and push our changes
+	back there.</para>
+
+      <!-- BEGIN branching.stable -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone stable stable-fix</userinput>
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd stable-fix</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a fix to a boring feature.' &gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Fix a bug'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
+pushing to /tmp/branchingPsTziR/stable
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+</screen>
+<!-- END branching.stable -->
+
+
+      <para id="x_466">Because Mercurial repositories are independent, and
+	Mercurial doesn't move changes around automatically, the
+	stable and main branches are <emphasis>isolated</emphasis>
+	from each other.  The changes that we made on the main branch
+	don't <quote>leak</quote> to the stable branch, and vice
+	versa.</para>
+
+      <para id="x_467">We'll often want all of our bugfixes on the stable
+	branch to show up on the main branch, too.  Rather than
+	rewrite a bugfix on the main branch, we can simply pull and
+	merge changes from the stable to the main branch, and
+	Mercurial will bring those bugfixes in for us.</para>
+
+      <!-- BEGIN branching.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../stable</userinput>
+pulling from ../stable
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+(run 'hg heads' to see heads, 'hg merge' to merge)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+merging myfile
+0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Bring in bugfix from stable branch'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+This is a fix to a boring feature.
+This is exciting and new!
+</screen>
+<!-- END branching.merge -->
+
+
+      <para id="x_468">The main branch will still contain changes that
+	are not on the stable branch, but it will also contain all of
+	the bugfixes from the stable branch.  The stable branch
+	remains unaffected by these changes, since changes are only
+	flowing from the stable to the main branch, and not the other
+	way.</para>
+    </sect2>
+
+    <sect2>
+      <title>Feature branches</title>
+
+      <para id="x_469">For larger projects, an effective way to manage change is
+	to break up a team into smaller groups.  Each group has a
+	shared branch of its own, cloned from a single
+	<quote>master</quote> branch used by the entire project.
+	People working on an individual branch are typically quite
+	isolated from developments on other branches.</para>
+
+      <figure id="fig:collab:feature-branches" float="0">
+	<title>Feature branches</title>
+	<mediaobject>
+	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_46b">When a particular feature is deemed to be in suitable
+	shape, someone on that feature team pulls and merges from the
+	master branch into the feature branch, then pushes back up to
+	the master branch.</para>
+    </sect2>
+
+    <sect2>
+      <title>The release train</title>
+
+      <para id="x_46c">Some projects are organized on a <quote>train</quote>
+	basis: a release is scheduled to happen every few months, and
+	whatever features are ready when the <quote>train</quote> is
+	ready to leave are allowed in.</para>
+
+      <para id="x_46d">This model resembles working with feature branches.  The
+	difference is that when a feature branch misses a train,
+	someone on the feature team pulls and merges the changes that
+	went out on that train release into the feature branch, and
+	the team continues its work on top of that release so that
+	their feature can make the next release.</para>
+    </sect2>
+
+    <sect2>
+      <title>The Linux kernel model</title>
+
+      <para id="x_46e">The development of the Linux kernel has a shallow
+	hierarchical structure, surrounded by a cloud of apparent
+	chaos.  Because most Linux developers use
+	<command moreinfo="none">git</command>, a distributed revision control tool
+	with capabilities similar to Mercurial, it's useful to
+	describe the way work flows in that environment; if you like
+	the ideas, the approach translates well across tools.</para>
+
+      <para id="x_46f">At the center of the community sits Linus Torvalds, the
+	creator of Linux.  He publishes a single source repository
+	that is considered the <quote>authoritative</quote> current
+	tree by the entire developer community. Anyone can clone
+	Linus's tree, but he is very choosy about whose trees he pulls
+	from.</para>
+
+      <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
+	As a general rule, he pulls whatever changes they publish, in
+	most cases without even reviewing those changes.  Some of
+	those lieutenants are generally agreed to be
+	<quote>maintainers</quote>, responsible for specific
+	subsystems within the kernel.  If a random kernel hacker wants
+	to make a change to a subsystem that they want to end up in
+	Linus's tree, they must find out who the subsystem's
+	maintainer is, and ask that maintainer to take their change.
+	If the maintainer reviews their changes and agrees to take
+	them, they'll pass them along to Linus in due course.</para>
+
+      <para id="x_471">Individual lieutenants have their own approaches to
+	reviewing, accepting, and publishing changes; and for deciding
+	when to feed them to Linus.  In addition, there are several
+	well known branches that people use for different purposes.
+	For example, a few people maintain <quote>stable</quote>
+	repositories of older versions of the kernel, to which they
+	apply critical fixes as needed.  Some maintainers publish
+	multiple trees: one for experimental changes; one for changes
+	that they are about to feed upstream; and so on.  Others just
+	publish a single tree.</para>
+
+      <para id="x_472">This model has two notable features.  The first is that
+	it's <quote>pull only</quote>.  You have to ask, convince, or
+	beg another developer to take a change from you, because there
+	are almost no trees to which more than one person can push,
+	and there's no way to push changes into a tree that someone
+	else controls.</para>
+
+      <para id="x_473">The second is that it's based on reputation and acclaim.
+	If you're an unknown, Linus will probably ignore changes from
+	you without even responding.  But a subsystem maintainer will
+	probably review them, and will likely take them if they pass
+	their criteria for suitability. The more <quote>good</quote>
+	changes you contribute to a maintainer, the more likely they
+	are to trust your judgment and accept your changes.  If you're
+	well-known and maintain a long-lived branch for something
+	Linus hasn't yet accepted, people with similar interests may
+	pull your changes regularly to keep up with your work.</para>
+
+      <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
+	or <quote>people</quote> boundaries.  If you're a respected
+	but specialised storage hacker, and you try to fix a
+	networking bug, that change will receive a level of scrutiny
+	from a network maintainer comparable to a change from a
+	complete stranger.</para>
+
+      <para id="x_475">To people who come from more orderly project backgrounds,
+	the comparatively chaotic Linux kernel development process
+	often seems completely insane.  It's subject to the whims of
+	individuals; people make sweeping changes whenever they deem
+	it appropriate; and the pace of development is astounding.
+	And yet Linux is a highly successful, well-regarded piece of
+	software.</para>
+    </sect2>
+
+    <sect2>
+      <title>Pull-only versus shared-push collaboration</title>
+
+      <para id="x_476">A perpetual source of heat in the open source community is
+	whether a development model in which people only ever pull
+	changes from others is <quote>better than</quote> one in which
+	multiple people can push changes to a shared
+	repository.</para>
+
+      <para id="x_477">Typically, the backers of the shared-push model use tools
+	that actively enforce this approach.  If you're using a
+	centralised revision control tool such as Subversion, there's
+	no way to make a choice over which model you'll use: the tool
+	gives you shared-push, and if you want to do anything else,
+	you'll have to roll your own approach on top (such as applying
+	a patch by hand).</para>
+
+      <para id="x_478">A good distributed revision control tool will
+	support both models.  You and your collaborators can then
+	structure how you work together based on your own needs and
+	preferences, not on what contortions your tools force you
+	into.</para>
+    </sect2>
+    <sect2>
+      <title>Where collaboration meets branch management</title>
+
+      <para id="x_479">Once you and your team set up some shared
+	repositories and start propagating changes back and forth
+	between local and shared repos, you begin to face a related,
+	but slightly different challenge: that of managing the
+	multiple directions in which your team may be moving at once.
+	Even though this subject is intimately related to how your
+	team collaborates, it's dense enough to merit treatment of its
+	own, in <xref linkend="chap:branch"/>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>The technical side of sharing</title>
+
+    <para id="x_47a">The remainder of this chapter is devoted to the question of
+      sharing changes with your collaborators.</para>
+  </sect1>
+
+  <sect1 id="sec:collab:serve">
+    <title>Informal sharing with <command role="hg-cmd" moreinfo="none">hg
+	serve</command></title>
+
+    <para id="x_47b">Mercurial's <command role="hg-cmd" moreinfo="none">hg serve</command>
+      command is wonderfully suited to small, tight-knit, and
+      fast-paced group environments.  It also provides a great way to
+      get a feel for using Mercurial commands over a network.</para>
+
+    <para id="x_47c">Run <command role="hg-cmd" moreinfo="none">hg serve</command> inside a
+      repository, and in under a second it will bring up a specialised
+      HTTP server; this will accept connections from any client, and
+      serve up data for that repository until you terminate it.
+      Anyone who knows the URL of the server you just started, and can
+      talk to your computer over the network, can then use a web
+      browser or Mercurial to read data from that repository.  A URL
+      for a <command role="hg-cmd" moreinfo="none">hg serve</command> instance running
+      on a laptop is likely to look something like
+      <literal moreinfo="none">http://my-laptop.local:8000/</literal>.</para>
+
+    <para id="x_47d">The <command role="hg-cmd" moreinfo="none">hg serve</command> command is
+      <emphasis>not</emphasis> a general-purpose web server. It can do
+      only two things:</para>
+    <itemizedlist>
+      <listitem><para id="x_47e">Allow people to browse the history of the
+	  repository it's serving, from their normal web
+	  browsers.</para>
+      </listitem>
+      <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
+	  can <command role="hg-cmd" moreinfo="none">hg clone</command> or <command role="hg-cmd" moreinfo="none">hg pull</command> changes from that
+	  repository.</para>
+      </listitem></itemizedlist>
+    <para id="x_480">In particular, <command role="hg-cmd" moreinfo="none">hg serve</command>
+      won't allow remote users to <emphasis>modify</emphasis> your
+      repository.  It's intended for read-only use.</para>
+
+    <para id="x_481">If you're getting started with Mercurial, there's nothing to
+      prevent you from using <command role="hg-cmd" moreinfo="none">hg serve</command>
+      to serve up a repository on your own computer, then use commands
+      like <command role="hg-cmd" moreinfo="none">hg clone</command>, <command role="hg-cmd" moreinfo="none">hg incoming</command>, and so on to talk to that
+      server as if the repository was hosted remotely. This can help
+      you to quickly get acquainted with using commands on
+      network-hosted repositories.</para>
+
+    <sect2>
+      <title>A few things to keep in mind</title>
+
+      <para id="x_482">Because it provides unauthenticated read access to all
+	clients, you should only use <command role="hg-cmd" moreinfo="none">hg
+	  serve</command> in an environment where you either don't
+	care, or have complete control over, who can access your
+	network and pull data from your repository.</para>
+
+      <para id="x_483">The <command role="hg-cmd" moreinfo="none">hg serve</command> command
+	knows nothing about any firewall software you might have
+	installed on your system or network.  It cannot detect or
+	control your firewall software.  If other people are unable to
+	talk to a running <command role="hg-cmd" moreinfo="none">hg serve</command>
+	instance, the second thing you should do
+	(<emphasis>after</emphasis> you make sure that they're using
+	the correct URL) is check your firewall configuration.</para>
+
+      <para id="x_484">By default, <command role="hg-cmd" moreinfo="none">hg serve</command>
+	listens for incoming connections on port 8000.  If another
+	process is already listening on the port you want to use, you
+	can specify a different port to listen on using the <option role="hg-opt-serve">-p</option> option.</para>
+
+      <para id="x_485">Normally, when <command role="hg-cmd" moreinfo="none">hg serve</command>
+	starts, it prints no output, which can be a bit unnerving.  If
+	you'd like to confirm that it is indeed running correctly, and
+	find out what URL you should send to your collaborators, start
+	it with the <option role="hg-opt-global">-v</option>
+	option.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:collab:ssh">
+    <title>Using the Secure Shell (ssh) protocol</title>
+
+    <para id="x_486">You can pull and push changes securely over a network
+      connection using the Secure Shell (<literal moreinfo="none">ssh</literal>)
+      protocol.  To use this successfully, you may have to do a little
+      bit of configuration on the client or server sides.</para>
+
+    <para id="x_487">If you're not familiar with ssh, it's the name of
+      both a command and a network protocol that let you securely
+      communicate with another computer.  To use it with Mercurial,
+      you'll be setting up one or more user accounts on a server so
+      that remote users can log in and execute commands.</para>
+
+    <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
+      probably find some of the material that follows to be elementary
+      in nature.)</para>
+
+    <sect2>
+      <title>How to read and write ssh URLs</title>
+
+      <para id="x_489">An ssh URL tends to look like this:</para>
+      <programlisting format="linespecific">ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
+      <orderedlist inheritnum="ignore" continuation="restarts">
+	<listitem><para id="x_48a">The <quote><literal moreinfo="none">ssh://</literal></quote>
+	    part tells Mercurial to use the ssh protocol.</para>
+	</listitem>
+	<listitem><para id="x_48b">The <quote><literal moreinfo="none">bos@</literal></quote>
+	    component indicates what username to log into the server
+	    as.  You can leave this out if the remote username is the
+	    same as your local username.</para>
+	</listitem>
+	<listitem><para id="x_48c">The
+	    <quote><literal moreinfo="none">hg.serpentine.com</literal></quote> gives
+	    the hostname of the server to log into.</para>
+	</listitem>
+	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
+	    number to connect to the server on.  The default port is
+	    22, so you only need to specify a colon and port number if
+	    you're <emphasis>not</emphasis> using port 22.</para>
+	</listitem>
+	<listitem><para id="x_48e">The remainder of the URL is the local path to
+	    the repository on the server.</para>
+	</listitem></orderedlist>
+
+      <para id="x_48f">There's plenty of scope for confusion with the path
+	component of ssh URLs, as there is no standard way for tools
+	to interpret it.  Some programs behave differently than others
+	when dealing with these paths. This isn't an ideal situation,
+	but it's unlikely to change.  Please read the following
+	paragraphs carefully.</para>
+
+      <para id="x_490">Mercurial treats the path to a repository on the server as
+	relative to the remote user's home directory.  For example, if
+	user <literal moreinfo="none">foo</literal> on the server has a home directory
+	of <filename class="directory" moreinfo="none">/home/foo</filename>, then an
+	ssh URL that contains a path component of <filename class="directory" moreinfo="none">bar</filename> <emphasis>really</emphasis>
+	refers to the directory <filename class="directory" moreinfo="none">/home/foo/bar</filename>.</para>
+
+      <para id="x_491">If you want to specify a path relative to another user's
+	home directory, you can use a path that starts with a tilde
+	character followed by the user's name (let's call them
+	<literal moreinfo="none">otheruser</literal>), like this.</para>
+      <programlisting format="linespecific">ssh://server/~otheruser/hg/repo</programlisting>
+
+      <para id="x_492">And if you really want to specify an
+	<emphasis>absolute</emphasis> path on the server, begin the
+	path component with two slashes, as in this example.</para>
+      <programlisting format="linespecific">ssh://server//absolute/path</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Finding an ssh client for your system</title>
+
+      <para id="x_493">Almost every Unix-like system comes with OpenSSH
+	preinstalled.  If you're using such a system, run
+	<literal moreinfo="none">which ssh</literal> to find out if the
+	<command moreinfo="none">ssh</command> command is installed (it's usually in
+	<filename class="directory" moreinfo="none">/usr/bin</filename>).  In the
+	unlikely event that it isn't present, take a look at your
+	system documentation to figure out how to install it.</para>
+
+      <para id="x_494">On Windows, the TortoiseHg package is bundled
+	with a version of Simon Tatham's excellent
+	<command moreinfo="none">plink</command> command, and you should not need to
+	do any further configuration.</para>
+    </sect2>
+
+    <sect2>
+      <title>Generating a key pair</title>
+
+      <para id="x_499">To avoid the need to repetitively type a
+	password every time you need to use your ssh client, I
+	recommend generating a key pair.</para>
+
+      <tip>
+	<title>Key pairs are not mandatory</title>
+
+	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
+	  pairs.  You can, if you like, safely ignore this section and
+	  the one that follows until you grow tired of repeatedly
+	  typing ssh passwords.</para>
+      </tip>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_6a5">On a Unix-like system, the
+	    <command moreinfo="none">ssh-keygen</command> command will do the
+	    trick.</para>
+	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
+	    to download a command named <command moreinfo="none">puttygen</command>
+	    from <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
+	      PuTTY web site</ulink> to generate a key pair.  See
+	    <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
+	      <command moreinfo="none">puttygen</command> documentation</ulink> for
+	    details of how use the command.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para id="x_49a">When you generate a key pair, it's usually
+	<emphasis>highly</emphasis> advisable to protect it with a
+	passphrase.  (The only time that you might not want to do this
+	is when you're using the ssh protocol for automated tasks on a
+	secure network.)</para>
+
+      <para id="x_49b">Simply generating a key pair isn't enough, however.
+	You'll need to add the public key to the set of authorised
+	keys for whatever user you're logging in remotely as.  For
+	servers using OpenSSH (the vast majority), this will mean
+	adding the public key to a list in a file called <filename role="special" moreinfo="none">authorized_keys</filename> in their <filename role="special" class="directory" moreinfo="none">.ssh</filename>
+	directory.</para>
+
+      <para id="x_49c">On a Unix-like system, your public key will have a
+	<filename moreinfo="none">.pub</filename> extension.  If you're using
+	<command moreinfo="none">puttygen</command> on Windows, you can save the
+	public key to a file of your choosing, or paste it from the
+	window it's displayed in straight into the <filename role="special" moreinfo="none">authorized_keys</filename> file.</para>
+    </sect2>
+    <sect2>
+      <title>Using an authentication agent</title>
+
+      <para id="x_49d">An authentication agent is a daemon that stores
+	passphrases in memory (so it will forget passphrases if you
+	log out and log back in again). An ssh client will notice if
+	it's running, and query it for a passphrase.  If there's no
+	authentication agent running, or the agent doesn't store the
+	necessary passphrase, you'll have to type your passphrase
+	every time Mercurial tries to communicate with a server on
+	your behalf (e.g. whenever you pull or push changes).</para>
+
+      <para id="x_49e">The downside of storing passphrases in an agent is that
+	it's possible for a well-prepared attacker to recover the
+	plain text of your passphrases, in some cases even if your
+	system has been power-cycled. You should make your own
+	judgment as to whether this is an acceptable risk.  It
+	certainly saves a lot of repeated typing.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para id="x_49f">On Unix-like systems, the agent is called
+	    <command moreinfo="none">ssh-agent</command>, and it's often run
+	    automatically for you when you log in.  You'll need to use
+	    the <command moreinfo="none">ssh-add</command> command to add passphrases
+	    to the agent's store.</para>
+	</listitem>
+	<listitem>
+	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
+	    <command moreinfo="none">pageant</command> command acts as the agent.  As
+	    with <command moreinfo="none">puttygen</command>, you'll need to <ulink url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
+	      <command moreinfo="none">pageant</command></ulink> from the PuTTY web
+	    site and read <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
+	      documentation</ulink>.  The <command moreinfo="none">pageant</command>
+	    command adds an icon to your system tray that will let you
+	    manage stored passphrases.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Configuring the server side properly</title>
+
+      <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
+	a variety of things can go wrong.  Add Mercurial
+	on top, and there's plenty more scope for head-scratching.
+	Most of these potential problems occur on the server side, not
+	the client side.  The good news is that once you've gotten a
+	configuration working, it will usually continue to work
+	indefinitely.</para>
+
+      <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
+	it's best to make sure that you can use the normal
+	<command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command> command to
+	talk to the server first.  If you run into problems with using
+	these commands directly, Mercurial surely won't work.  Worse,
+	it will obscure the underlying problem.  Any time you want to
+	debug ssh-related Mercurial problems, you should drop back to
+	making sure that plain ssh client commands work first,
+	<emphasis>before</emphasis> you worry about whether there's a
+	problem with Mercurial.</para>
+
+      <para id="x_4a2">The first thing to be sure of on the server side is that
+	you can actually log in from another machine at all.  If you
+	can't use <command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command>
+	to log in, the error message you get may give you a few hints
+	as to what's wrong.  The most common problems are as
+	follows.</para>
+      <itemizedlist>
+	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
+	    error, either there isn't an SSH daemon running on the
+	    server at all, or it's inaccessible due to firewall
+	    configuration.</para>
+	</listitem>
+	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
+	    error, you either have an incorrect address for the server
+	    or a seriously locked down firewall that won't admit its
+	    existence at all.</para>
+	</listitem>
+	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
+	    error, you may have mistyped the username on the server,
+	    or you could have mistyped your key's passphrase or the
+	    remote user's password.</para>
+	</listitem></itemizedlist>
+      <para id="x_4a6">In summary, if you're having trouble talking to the
+	server's ssh daemon, first make sure that one is running at
+	all.  On many systems it will be installed, but disabled, by
+	default.  Once you're done with this step, you should then
+	check that the server's firewall is configured to allow
+	incoming connections on the port the ssh daemon is listening
+	on (usually 22).  Don't worry about more exotic possibilities
+	for misconfiguration until you've checked these two
+	first.</para>
+
+      <para id="x_4a7">If you're using an authentication agent on the client side
+	to store passphrases for your keys, you ought to be able to
+	log into the server without being prompted for a passphrase or
+	a password.  If you're prompted for a passphrase, there are a
+	few possible culprits.</para>
+      <itemizedlist>
+	<listitem><para id="x_4a8">You might have forgotten to use
+	    <command moreinfo="none">ssh-add</command> or <command moreinfo="none">pageant</command>
+	    to store the passphrase.</para>
+	</listitem>
+	<listitem><para id="x_4a9">You might have stored the passphrase for the
+	    wrong key.</para>
+	</listitem></itemizedlist>
+      <para id="x_4aa">If you're being prompted for the remote user's password,
+	there are another few possible problems to check.</para>
+      <itemizedlist>
+	<listitem><para id="x_4ab">Either the user's home directory or their
+	    <filename role="special" class="directory" moreinfo="none">.ssh</filename>
+	    directory might have excessively liberal permissions.  As
+	    a result, the ssh daemon will not trust or read their
+	    <filename role="special" moreinfo="none">authorized_keys</filename> file.
+	    For example, a group-writable home or <filename role="special" class="directory" moreinfo="none">.ssh</filename>
+	    directory will often cause this symptom.</para>
+	</listitem>
+	<listitem><para id="x_4ac">The user's <filename role="special" moreinfo="none">authorized_keys</filename> file may have
+	    a problem. If anyone other than the user owns or can write
+	    to that file, the ssh daemon will not trust or read
+	    it.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_4ad">In the ideal world, you should be able to run the
+	following command successfully, and it should print exactly
+	one line of output, the current date and time.</para>
+      <programlisting format="linespecific">ssh myserver date</programlisting>
+
+      <para id="x_4ae">If, on your server, you have login scripts that print
+	banners or other junk even when running non-interactive
+	commands like this, you should fix them before you continue,
+	so that they only print output if they're run interactively.
+	Otherwise these banners will at least clutter up Mercurial's
+	output.  Worse, they could potentially cause problems with
+	running Mercurial commands remotely.  Mercurial tries to
+	detect and ignore banners in non-interactive
+	<command moreinfo="none">ssh</command> sessions, but it is not foolproof.  (If
+	you're editing your login scripts on your server, the usual
+	way to see if a login script is running in an interactive
+	shell is to check the return code from the command
+	<literal moreinfo="none">tty -s</literal>.)</para>
+
+      <para id="x_4af">Once you've verified that plain old ssh is working with
+	your server, the next step is to ensure that Mercurial runs on
+	the server.  The following command should run
+	successfully:</para>
+
+      <programlisting format="linespecific">ssh myserver hg version</programlisting>
+
+      <para id="x_4b0">If you see an error message instead of normal <command role="hg-cmd" moreinfo="none">hg version</command> output, this is usually
+	because you haven't installed Mercurial to <filename class="directory" moreinfo="none">/usr/bin</filename>.  Don't worry if this
+	is the case; you don't need to do that.  But you should check
+	for a few possible problems.</para>
+      <itemizedlist>
+	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
+	    all?  I know this sounds trivial, but it's worth
+	    checking!</para>
+	</listitem>
+	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
+	    via the <envar>PATH</envar> environment variable) is
+	    simply misconfigured.</para>
+	</listitem>
+	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
+	    variable is only being set to point to the location of the
+	    <command moreinfo="none">hg</command> executable if the login session is
+	    interactive.  This can happen if you're setting the path
+	    in the wrong shell login script.  See your shell's
+	    documentation for details.</para>
+	</listitem>
+	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
+	    variable may need to contain the path to the Mercurial
+	    Python modules.  It might not be set at all; it could be
+	    incorrect; or it may be set only if the login is
+	    interactive.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_4b5">If you can run <command role="hg-cmd" moreinfo="none">hg version</command>
+	over an ssh connection, well done! You've got the server and
+	client sorted out.  You should now be able to use Mercurial to
+	access repositories hosted by that username on that server.
+	If you run into problems with Mercurial and ssh at this point,
+	try using the <option role="hg-opt-global">--debug</option>
+	option to get a clearer picture of what's going on.</para>
+    </sect2>
+    <sect2>
+      <title>Using compression with ssh</title>
+
+      <para id="x_4b6">Mercurial does not compress data when it uses the ssh
+	protocol, because the ssh protocol can transparently compress
+	data.  However, the default behavior of ssh clients is
+	<emphasis>not</emphasis> to request compression.</para>
+
+      <para id="x_4b7">Over any network other than a fast LAN (even a wireless
+	network), using compression is likely to significantly speed
+	up Mercurial's network operations.  For example, over a WAN,
+	someone measured compression as reducing the amount of time
+	required to clone a particularly large repository from 51
+	minutes to 17 minutes.</para>
+
+      <para id="x_4b8">Both <command moreinfo="none">ssh</command> and <command moreinfo="none">plink</command>
+	accept a <option role="cmd-opt-ssh">-C</option> option which
+	turns on compression.  You can easily edit your <filename role="special" moreinfo="none">~/.hgrc</filename> to enable compression for
+	all of Mercurial's uses of the ssh protocol.  Here is how to
+	do so for regular <command moreinfo="none">ssh</command> on Unix-like systems,
+	for example.</para>
+      <programlisting format="linespecific">[ui]
+ssh = ssh -C</programlisting>
+
+      <para id="x_4b9">If you use <command moreinfo="none">ssh</command> on a
+	Unix-like system, you can configure it to always use
+	compression when talking to your server.  To do this, edit
+	your <filename role="special" moreinfo="none">.ssh/config</filename> file
+	(which may not yet exist), as follows.</para>
+
+      <programlisting format="linespecific">Host hg
+  Compression yes
+  HostName hg.example.com</programlisting>
+
+      <para id="x_4ba">This defines a hostname alias,
+	<literal moreinfo="none">hg</literal>.  When you use that hostname on the
+	<command moreinfo="none">ssh</command> command line or in a Mercurial
+	<literal moreinfo="none">ssh</literal>-protocol URL, it will cause
+	<command moreinfo="none">ssh</command> to connect to
+	<literal moreinfo="none">hg.example.com</literal> and use compression.  This
+	gives you both a shorter name to type and compression, each of
+	which is a good thing in its own right.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:collab:cgi">
+    <title>Serving over HTTP using CGI</title>
+
+    <para id="x_6a8">The simplest way to host one or more repositories in a
+      permanent way is to use a web server and Mercurial's CGI
+      support.</para>
+
+    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
+      CGI interface can take anything from a few moments to several
+      hours.</para>
+
+    <para id="x_4bc">We'll begin with the simplest of examples, and work our way
+      towards a more complex configuration.  Even for the most basic
+      case, you're almost certainly going to need to read and modify
+      your web server's configuration.</para>
+
+    <note>
+      <title>High pain tolerance required</title>
+
+      <para id="x_4bd">Configuring a web server is a complex, fiddly,
+	and highly system-dependent activity.  I can't possibly give
+	you instructions that will cover anything like all of the
+	cases you will encounter. Please use your discretion and
+	judgment in following the sections below.  Be prepared to make
+	plenty of mistakes, and to spend a lot of time reading your
+	server's error logs.</para>
+
+      <para id="x_6a9">If you don't have a strong stomach for tweaking
+	configurations over and over, or a compelling need to host
+	your own services, you might want to try one of the public
+	hosting services that I mentioned earlier.</para>
+    </note>
+
+    <sect2>
+      <title>Web server configuration checklist</title>
+
+      <para id="x_4be">Before you continue, do take a few moments to check a few
+	aspects of your system's setup.</para>
+
+      <orderedlist inheritnum="ignore" continuation="restarts">
+	<listitem><para id="x_4bf">Do you have a web server installed
+	    at all? Mac OS X and some Linux distributions ship with
+	    Apache, but many other systems may not have a web server
+	    installed.</para>
+	</listitem>
+	<listitem><para id="x_4c0">If you have a web server installed, is it
+	    actually running?  On most systems, even if one is
+	    present, it will be disabled by default.</para>
+	</listitem>
+	<listitem><para id="x_4c1">Is your server configured to allow you to run
+	    CGI programs in the directory where you plan to do so?
+	    Most servers default to explicitly disabling the ability
+	    to run CGI programs.</para>
+	</listitem></orderedlist>
+
+      <para id="x_4c2">If you don't have a web server installed, and don't have
+	substantial experience configuring Apache, you should consider
+	using the <literal moreinfo="none">lighttpd</literal> web server instead of
+	Apache.  Apache has a well-deserved reputation for baroque and
+	confusing configuration. While <literal moreinfo="none">lighttpd</literal> is
+	less capable in some ways than Apache, most of these
+	capabilities are not relevant to serving Mercurial
+	repositories.  And <literal moreinfo="none">lighttpd</literal> is undeniably
+	<emphasis>much</emphasis> easier to get started with than
+	Apache.</para>
+    </sect2>
+
+    <sect2>
+      <title>Basic CGI configuration</title>
+
+      <para id="x_4c3">On Unix-like systems, it's common for users to have a
+	subdirectory named something like <filename class="directory" moreinfo="none">public_html</filename> in their home
+	directory, from which they can serve up web pages.  A file
+	named <filename moreinfo="none">foo</filename> in this directory will be
+	accessible at a URL of the form
+	<literal moreinfo="none">http://www.example.com/username/foo</literal>.</para>
+
+      <para id="x_4c4">To get started, find the <filename role="special" moreinfo="none">hgweb.cgi</filename> script that should be
+	present in your Mercurial installation.  If you can't quickly
+	find a local copy on your system, simply download one from the
+	master Mercurial repository at <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>.</para>
+
+      <para id="x_4c5">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
+	ensure that it's executable.</para>
+      <programlisting format="linespecific">cp .../hgweb.cgi ~/public_html
+chmod 755 ~/public_html/hgweb.cgi</programlisting>
+      <para id="x_4c6">The <literal moreinfo="none">755</literal> argument to
+	<command moreinfo="none">chmod</command> is a little more general than just
+	making the script executable: it ensures that the script is
+	executable by anyone, and that <quote>group</quote> and
+	<quote>other</quote> write permissions are
+	<emphasis>not</emphasis> set.  If you were to leave those
+	write permissions enabled, Apache's <literal moreinfo="none">suexec</literal>
+	subsystem would likely refuse to execute the script.  In fact,
+	<literal moreinfo="none">suexec</literal> also insists that the
+	<emphasis>directory</emphasis> in which the script resides
+	must not be writable by others.</para>
+      <programlisting format="linespecific">chmod 755 ~/public_html</programlisting>
+
+      <sect3 id="sec:collab:wtf">
+	<title>What could <emphasis>possibly</emphasis> go
+	  wrong?</title>
+
+	<para id="x_4c7">Once you've copied the CGI script into place,
+	  go into a web browser, and try to open the URL
+	  <literal moreinfo="none">http://myhostname/~myuser/hgweb.cgi</literal>,
+	  <emphasis>but</emphasis> brace yourself for instant failure.
+	  There's a high probability that trying to visit this URL
+	  will fail, and there are many possible reasons for this.  In
+	  fact, you're likely to stumble over almost every one of the
+	  possible errors below, so please read carefully.  The
+	  following are all of the problems I ran into on a system
+	  running Fedora 7, with a fresh installation of Apache, and a
+	  user account that I created specially to perform this
+	  exercise.</para>
+
+	<para id="x_4c8">Your web server may have per-user directories disabled.
+	  If you're using Apache, search your config file for a
+	  <literal moreinfo="none">UserDir</literal> directive.  If there's none
+	  present, per-user directories will be disabled.  If one
+	  exists, but its value is <literal moreinfo="none">disabled</literal>, then
+	  per-user directories will be disabled.  Otherwise, the
+	  string after <literal moreinfo="none">UserDir</literal> gives the name of
+	  the subdirectory that Apache will look in under your home
+	  directory, for example <filename class="directory" moreinfo="none">public_html</filename>.</para>
+
+	<para id="x_4c9">Your file access permissions may be too restrictive.
+	  The web server must be able to traverse your home directory
+	  and directories under your <filename class="directory" moreinfo="none">public_html</filename> directory, and
+	  read files under the latter too.  Here's a quick recipe to
+	  help you to make your permissions more appropriate.</para>
+	<programlisting format="linespecific">chmod 755 ~
+find ~/public_html -type d -print0 | xargs -0r chmod 755
+find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
+
+	<para id="x_4ca">The other possibility with permissions is that you might
+	  get a completely empty window when you try to load the
+	  script.  In this case, it's likely that your access
+	  permissions are <emphasis>too permissive</emphasis>.  Apache's
+	  <literal moreinfo="none">suexec</literal> subsystem won't execute a script
+	  that's group- or world-writable, for example.</para>
+
+	<para id="x_4cb">Your web server may be configured to disallow execution
+	  of CGI programs in your per-user web directory.  Here's
+	  Apache's default per-user configuration from my Fedora
+	  system.</para>
+
+	<!-- BEGIN ch06/apache-config.lst -->
+<programlisting format="linespecific">&lt;Directory /home/*/public_html&gt;
+  AllowOverride FileInfo AuthConfig Limit
+  Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
+  &lt;Limit GET POST OPTIONS&gt;
+    Order allow,deny
+    Allow from all
+  &lt;/Limit&gt;
+  &lt;LimitExcept GET POST OPTIONS&gt;
+    Order deny,allow Deny from all
+  &lt;/LimitExcept&gt;
+&lt;/Directory&gt;</programlisting>
+<!-- END ch06/apache-config.lst -->
+
+
+	<para id="x_4cc">If you find a similar-looking
+	  <literal moreinfo="none">Directory</literal> group in your Apache
+	  configuration, the directive to look at inside it is
+	  <literal moreinfo="none">Options</literal>. Add <literal moreinfo="none">ExecCGI</literal>
+	  to the end of this list if it's missing, and restart the web
+	  server.</para>
+
+	<para id="x_4cd">If you find that Apache serves you the text of the CGI
+	  script instead of executing it, you may need to either
+	  uncomment (if already present) or add a directive like
+	  this.</para>
+	<programlisting format="linespecific">AddHandler cgi-script .cgi</programlisting>
+
+	<para id="x_4ce">The next possibility is that you might be served with a
+	  colourful Python backtrace claiming that it can't import a
+	  <literal moreinfo="none">mercurial</literal>-related module.  This is
+	  actually progress!  The server is now capable of executing
+	  your CGI script.  This error is only likely to occur if
+	  you're running a private installation of Mercurial, instead
+	  of a system-wide version.  Remember that the web server runs
+	  the CGI program without any of the environment variables
+	  that you take for granted in an interactive session.  If
+	  this error happens to you, edit your copy of <filename role="special" moreinfo="none">hgweb.cgi</filename> and follow the
+	  directions inside it to correctly set your
+	  <envar>PYTHONPATH</envar> environment variable.</para>
+
+	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
+	  served with another colourful Python backtrace: this one
+	  will complain that it can't find <filename class="directory" moreinfo="none">/path/to/repository</filename>.  Edit
+	  your <filename role="special" moreinfo="none">hgweb.cgi</filename> script
+	  and replace the <filename class="directory" moreinfo="none">/path/to/repository</filename> string
+	  with the complete path to the repository you want to serve
+	  up.</para>
+
+	<para id="x_4d0">At this point, when you try to reload the page, you
+	  should be presented with a nice HTML view of your
+	  repository's history.  Whew!</para>
+      </sect3>
+
+      <sect3>
+	<title>Configuring lighttpd</title>
+
+	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
+	  the increasingly popular <literal moreinfo="none">lighttpd</literal> web
+	  server to serve the same repository as I described with
+	  Apache above.  I had already overcome all of the problems I
+	  outlined with Apache, many of which are not server-specific.
+	  As a result, I was fairly sure that my file and directory
+	  permissions were good, and that my <filename role="special" moreinfo="none">hgweb.cgi</filename> script was properly
+	  edited.</para>
+
+	<para id="x_4d2">Once I had Apache running, getting
+	  <literal moreinfo="none">lighttpd</literal> to serve the repository was a
+	  snap (in other words, even if you're trying to use
+	  <literal moreinfo="none">lighttpd</literal>, you should read the Apache
+	  section).  I first had to edit the
+	  <literal moreinfo="none">mod_access</literal> section of its config file to
+	  enable <literal moreinfo="none">mod_cgi</literal> and
+	  <literal moreinfo="none">mod_userdir</literal>, both of which were disabled
+	  by default on my system.  I then added a few lines to the
+	  end of the config file, to configure these modules.</para>
+	<programlisting format="linespecific">userdir.path = "public_html"
+cgi.assign = (".cgi" =&gt; "" )</programlisting>
+	<para id="x_4d3">With this done, <literal moreinfo="none">lighttpd</literal> ran
+	  immediately for me.  If I had configured
+	  <literal moreinfo="none">lighttpd</literal> before Apache, I'd almost
+	  certainly have run into many of the same system-level
+	  configuration problems as I did with Apache.  However, I
+	  found <literal moreinfo="none">lighttpd</literal> to be noticeably easier to
+	  configure than Apache, even though I've used Apache for over
+	  a decade, and this was my first exposure to
+	  <literal moreinfo="none">lighttpd</literal>.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Sharing multiple repositories with one CGI script</title>
+
+      <para id="x_4d4">The <filename role="special" moreinfo="none">hgweb.cgi</filename> script
+	only lets you publish a single repository, which is an
+	annoying restriction.  If you want to publish more than one
+	without wracking yourself with multiple copies of the same
+	script, each with different names, a better choice is to use
+	the <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
+	script.</para>
+
+      <para id="x_4d5">The procedure to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is only a little more
+	involved than for <filename role="special" moreinfo="none">hgweb.cgi</filename>.  First, you must obtain
+	a copy of the script.  If you don't have one handy, you can
+	download a copy from the master Mercurial repository at <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>.</para>
+
+      <para id="x_4d6">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
+	ensure that it's executable.</para>
+
+      <programlisting format="linespecific">cp .../hgwebdir.cgi ~/public_html
+chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
+
+      <para id="x_4d7">With basic configuration out of the way, try to
+	visit <literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>
+	in your	browser.  It should
+	display an empty list of repositories.  If you get a blank
+	window or error message, try walking through the list of
+	potential problems in <xref linkend="sec:collab:wtf"/>.</para>
+
+      <para id="x_4d8">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
+	script relies on an external configuration file.  By default,
+	it searches for a file named <filename role="special" moreinfo="none">hgweb.config</filename> in the same directory
+	as itself.  You'll need to create this file, and make it
+	world-readable.  The format of the file is similar to a
+	Windows <quote>ini</quote> file, as understood by Python's
+	<literal moreinfo="none">ConfigParser</literal>
+	<citation>web:configparser</citation> module.</para>
+
+      <para id="x_4d9">The easiest way to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is with a section
+	named <literal moreinfo="none">collections</literal>.  This will automatically
+	publish <emphasis>every</emphasis> repository under the
+	directories you name.  The section should look like
+	this:</para>
+      <programlisting format="linespecific">[collections]
+/my/root = /my/root</programlisting>
+      <para id="x_4da">Mercurial interprets this by looking at the directory name
+	on the <emphasis>right</emphasis> hand side of the
+	<quote><literal moreinfo="none">=</literal></quote> sign; finding repositories
+	in that directory hierarchy; and using the text on the
+	<emphasis>left</emphasis> to strip off matching text from the
+	names it will actually list in the web interface.  The
+	remaining component of a path after this stripping has
+	occurred is called a <quote>virtual path</quote>.</para>
+
+      <para id="x_4db">Given the example above, if we have a
+	repository whose local path is <filename class="directory" moreinfo="none">/my/root/this/repo</filename>, the CGI
+	script will strip the leading <filename class="directory" moreinfo="none">/my/root</filename> from the name, and
+	publish the repository with a virtual path of <filename class="directory" moreinfo="none">this/repo</filename>.  If the base URL for
+	our CGI script is
+	<literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>, the
+	complete URL for that repository will be
+	<literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
+
+      <para id="x_4dc">If we replace <filename class="directory" moreinfo="none">/my/root</filename> on the left hand side
+	of this example with <filename class="directory" moreinfo="none">/my</filename>, then <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will only strip off
+	<filename class="directory" moreinfo="none">/my</filename> from the repository
+	name, and will give us a virtual path of <filename class="directory" moreinfo="none">root/this/repo</filename> instead of
+	<filename class="directory" moreinfo="none">this/repo</filename>.</para>
+
+      <para id="x_4dd">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
+	script will recursively search each directory listed in the
+	<literal moreinfo="none">collections</literal> section of its configuration
+	file, but it will <literal moreinfo="none">not</literal> recurse into the
+	repositories it finds.</para>
+
+      <para id="x_4de">The <literal moreinfo="none">collections</literal> mechanism makes it easy
+	to publish many repositories in a <quote>fire and
+	  forget</quote> manner.  You only need to set up the CGI
+	script and configuration file one time.  Afterwards, you can
+	publish or unpublish a repository at any time by simply moving
+	it into, or out of, the directory hierarchy in which you've
+	configured <filename role="special" moreinfo="none">hgwebdir.cgi</filename> to
+	look.</para>
+
+      <sect3>
+	<title>Explicitly specifying which repositories to
+	  publish</title>
+
+	<para id="x_4df">In addition to the <literal moreinfo="none">collections</literal>
+	  mechanism, the <filename role="special" moreinfo="none">hgwebdir.cgi</filename> script allows you
+	  to publish a specific list of repositories.  To do so,
+	  create a <literal moreinfo="none">paths</literal> section, with contents of
+	  the following form.</para>
+	<programlisting format="linespecific">[paths]
+repo1 = /my/path/to/some/repo
+repo2 = /some/path/to/another</programlisting>
+	<para id="x_4e0">In this case, the virtual path (the component that will
+	  appear in a URL) is on the left hand side of each
+	  definition, while the path to the repository is on the
+	  right.  Notice that there does not need to be any
+	  relationship between the virtual path you choose and the
+	  location of a repository in your filesystem.</para>
+
+	<para id="x_4e1">If you wish, you can use both the
+	  <literal moreinfo="none">collections</literal> and <literal moreinfo="none">paths</literal>
+	  mechanisms simultaneously in a single configuration
+	  file.</para>
+
+	<note>
+	  <title>Beware duplicate virtual paths</title>
+
+	  <para id="x_4e2">  If several repositories have the same
+	    virtual path, <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will not report
+	    an error.  Instead, it will behave unpredictably.</para>
+	</note>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Downloading source archives</title>
+
+      <para id="x_4e3">Mercurial's web interface lets users download an archive
+	of any revision.  This archive will contain a snapshot of the
+	working directory as of that revision, but it will not contain
+	a copy of the repository data.</para>
+
+      <para id="x_4e4">By default, this feature is not enabled.  To enable it,
+	you'll need to add an <envar role="rc-item-web">allow_archive</envar> item to the
+	<literal role="rc-web" moreinfo="none">web</literal> section of your <filename role="special" moreinfo="none">~/.hgrc</filename>; see below for details.</para>
+    </sect2>
+    <sect2>
+      <title>Web configuration options</title>
+
+      <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd" moreinfo="none">hg
+	  serve</command> command, and the <filename role="special" moreinfo="none">hgweb.cgi</filename> and <filename role="special" moreinfo="none">hgwebdir.cgi</filename> scripts) have a
+	number of configuration options that you can set.  These
+	belong in a section named <literal role="rc-web" moreinfo="none">web</literal>.</para>
+      <itemizedlist>
+	<listitem><para id="x_4e6"><envar role="rc-item-web">allow_archive</envar>: Determines
+	    which (if any) archive download mechanisms Mercurial
+	    supports.  If you enable this feature, users of the web
+	    interface will be able to download an archive of whatever
+	    revision of a repository they are viewing. To enable the
+	    archive feature, this item must take the form of a
+	    sequence of words drawn from the list below.</para>
+	  <itemizedlist>
+	    <listitem><para id="x_4e7"><literal moreinfo="none">bz2</literal>: A
+		<command moreinfo="none">tar</command> archive, compressed using
+		<literal moreinfo="none">bzip2</literal> compression.  This has the
+		best compression ratio, but uses the most CPU time on
+		the server.</para>
+	    </listitem>
+	    <listitem><para id="x_4e8"><literal moreinfo="none">gz</literal>: A
+		<command moreinfo="none">tar</command> archive, compressed using
+		<literal moreinfo="none">gzip</literal> compression.</para>
+	    </listitem>
+	    <listitem><para id="x_4e9"><literal moreinfo="none">zip</literal>: A
+		<command moreinfo="none">zip</command> archive, compressed using LZW
+		compression.  This format has the worst compression
+		ratio, but is widely used in the Windows world.</para>
+	    </listitem>
+	  </itemizedlist>
+	  <para id="x_4ea">  If you provide an empty list, or don't have an
+	    <envar role="rc-item-web">allow_archive</envar> entry at
+	    all, this feature will be disabled.  Here is an example of
+	    how to enable all three supported formats.</para>
+	  <programlisting format="linespecific">[web]
+allow_archive = bz2 gz zip</programlisting>
+	</listitem>
+	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
+	    Boolean.  Determines whether the web interface allows
+	    remote users to <command role="hg-cmd" moreinfo="none">hg pull</command>
+	    and <command role="hg-cmd" moreinfo="none">hg clone</command> this
+	    repository over HTTP.  If set to <literal moreinfo="none">no</literal> or
+	    <literal moreinfo="none">false</literal>, only the
+	    <quote>human-oriented</quote> portion of the web interface
+	    is available.</para>
+	</listitem>
+	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
+	    String.  A free-form (but preferably brief) string
+	    identifying the person or group in charge of the
+	    repository.  This often contains the name and email
+	    address of a person or mailing list.  It often makes sense
+	    to place this entry in a repository's own <filename role="special" moreinfo="none">.hg/hgrc</filename> file, but it can make
+	    sense to use in a global <filename role="special" moreinfo="none">~/.hgrc</filename> if every repository
+	    has a single maintainer.</para>
+	</listitem>
+	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
+	    Integer.  The default maximum number of changesets to
+	    display in a single page of output.</para>
+	</listitem>
+	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
+	    Integer.  The default maximum number of modified files to
+	    display in a single page of output.</para>
+	</listitem>
+	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
+	    Integer.  If the web interface displays alternating
+	    <quote>stripes</quote> to make it easier to visually align
+	    rows when you are looking at a table, this number controls
+	    the number of rows in each stripe.</para>
+	</listitem>
+	<listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>: Controls the template
+	    Mercurial uses to display the web interface.  Mercurial
+	    ships with several web templates.</para>
+	  <itemizedlist>
+	    <listitem>
+	      <para id="x_6aa"><literal moreinfo="none">coal</literal> is monochromatic.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ab"><literal moreinfo="none">gitweb</literal> emulates the visual
+		style of git's web interface.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ac"><literal moreinfo="none">monoblue</literal> uses solid blues and
+		greys.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ad"><literal moreinfo="none">paper</literal> is the default.</para>
+	    </listitem>
+	    <listitem>
+	      <para id="x_6ae"><literal moreinfo="none">spartan</literal> was the default for a
+		long time.</para>
+	    </listitem>
+	  </itemizedlist>
+	  <para id="x_6af">You can
+	    also specify a custom template of your own; see 
+	    <xref linkend="chap:template"/> for details. Here, you can
+	    see how to enable the <literal moreinfo="none">gitweb</literal>
+	    style.</para>
+	  <programlisting format="linespecific">[web]
+style = gitweb</programlisting>
+	</listitem>
+	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
+	    Path.  The directory in which to search for template
+	    files.  By default, Mercurial searches in the directory in
+	    which it was installed.</para>
+	</listitem></itemizedlist>
+      <para id="x_4f2">If you are using <filename role="special" moreinfo="none">hgwebdir.cgi</filename>, you can place a few
+	configuration items in a <literal role="rc-web" moreinfo="none">web</literal>
+	section of the <filename role="special" moreinfo="none">hgweb.config</filename> file instead of a
+	<filename role="special" moreinfo="none">~/.hgrc</filename> file, for
+	convenience.  These items are <envar role="rc-item-web">motd</envar> and <envar role="rc-item-web">style</envar>.</para>
+
+      <sect3>
+	<title>Options specific to an individual repository</title>
+
+	<para id="x_4f3">A few <literal role="rc-web" moreinfo="none">web</literal> configuration
+	  items ought to be placed in a repository's local <filename role="special" moreinfo="none">.hg/hgrc</filename>, rather than a user's
+	  or global <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
+	<itemizedlist>
+	  <listitem><para id="x_4f4"><envar role="rc-item-web">description</envar>: String.  A
+	      free-form (but preferably brief) string that describes
+	      the contents or purpose of the repository.</para>
+	  </listitem>
+	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
+	      String.  The name to use for the repository in the web
+	      interface.  This overrides the default name, which is
+	      the last component of the repository's path.</para>
+	  </listitem></itemizedlist>
+      </sect3>
+
+      <sect3>
+	<title>Options specific to the <command role="hg-cmd" moreinfo="none">hg
+	    serve</command> command</title>
+
+	<para id="x_4f6">Some of the items in the <literal role="rc-web" moreinfo="none">web</literal> section of a <filename role="special" moreinfo="none">~/.hgrc</filename> file are only for use
+	  with the <command role="hg-cmd" moreinfo="none">hg serve</command>
+	  command.</para>
+	<itemizedlist>
+	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
+	      Path.  The name of a file into which to write an access
+	      log.  By default, the <command role="hg-cmd" moreinfo="none">hg
+		serve</command> command writes this information to
+	      standard output, not to a file.  Log entries are written
+	      in the standard <quote>combined</quote> file format used
+	      by almost all web servers.</para>
+	  </listitem>
+	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
+	      String.  The local address on which the server should
+	      listen for incoming connections.  By default, the server
+	      listens on all addresses.</para>
+	  </listitem>
+	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
+	      Path.  The name of a file into which to write an error
+	      log.  By default, the <command role="hg-cmd" moreinfo="none">hg
+		serve</command> command writes this information to
+	      standard error, not to a file.</para>
+	  </listitem>
+	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
+	      Boolean.  Whether to use the IPv6 protocol. By default,
+	      IPv6 is not used.</para>
+	  </listitem>
+	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
+	      Integer.  The TCP port number on which the server should
+	      listen.  The default port number used is 8000.</para>
+	  </listitem></itemizedlist>
+      </sect3>
+
+      <sect3>
+	<title>Choosing the right <filename role="special" moreinfo="none">~/.hgrc</filename> file to add <literal role="rc-web" moreinfo="none">web</literal> items to</title>
+
+	<para id="x_4fc">It is important to remember that a web server like
+	  Apache or <literal moreinfo="none">lighttpd</literal> will run under a user
+	  ID that is different to yours. CGI scripts run by your
+	  server, such as <filename role="special" moreinfo="none">hgweb.cgi</filename>, will usually also run
+	  under that user ID.</para>
+
+	<para id="x_4fd">If you add <literal role="rc-web" moreinfo="none">web</literal> items to
+	  your own personal <filename role="special" moreinfo="none">~/.hgrc</filename> file, CGI scripts won't read that
+	  <filename role="special" moreinfo="none">~/.hgrc</filename> file.  Those
+	  settings will thus only affect the behavior of the <command role="hg-cmd" moreinfo="none">hg serve</command> command when you run it.
+	  To cause CGI scripts to see your settings, either create a
+	  <filename role="special" moreinfo="none">~/.hgrc</filename> file in the
+	  home directory of the user ID that runs your web server, or
+	  add those settings to a system-wide <filename role="special" moreinfo="none">hgrc</filename> file.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>System-wide configuration</title>
+
+    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
+      server to which people publish changes), it often makes sense to
+      set up some global default behaviors, such as what theme to use
+      in web interfaces.</para>
+
+    <para id="x_6b1">If a file named <filename moreinfo="none">/etc/mercurial/hgrc</filename>
+      exists, Mercurial will read it at startup time and apply any
+      configuration settings it finds in that file.  It will also look
+      for files ending in a <literal moreinfo="none">.rc</literal> extension in a
+      directory named <filename moreinfo="none">/etc/mercurial/hgrc.d</filename>, and
+      apply any configuration settings it finds in each of those
+      files.</para>
+
+    <sect2>
+      <title>Making Mercurial more trusting</title>
+
+      <para id="x_6b2">One situation in which a global <filename moreinfo="none">hgrc</filename>
+	can be useful is if users are pulling changes owned by other
+	users.  By default, Mercurial will not trust most of the
+	configuration items in a <filename moreinfo="none">.hg/hgrc</filename> file
+	inside a repository that is owned by a different user. If we
+	clone or pull changes from such a repository, Mercurial will
+	print a warning stating that it does not trust their
+	<filename moreinfo="none">.hg/hgrc</filename>.</para>
+
+      <para id="x_6b3">If everyone in a particular Unix group is on the same team
+	and <emphasis>should</emphasis> trust each other's
+	configuration settings, or we want to trust particular users,
+	we can override Mercurial's skeptical defaults by creating a
+	system-wide <filename moreinfo="none">hgrc</filename> file such as the
+	following:</para>
+
+    <programlisting format="linespecific"># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
+[trusted]
+# Trust all entries in any hgrc file owned by the "editors" or
+# "www-data" groups.
+groups = editors, www-data
+
+# Trust entries in hgrc files owned by the following users.
+users = apache, bobo
+</programlisting>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch07 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:names">
+  <?dbhtml filename="file-names-and-pattern-matching.html"?>
+  <title>File names and pattern matching</title>
+
+  <para id="x_543">Mercurial provides mechanisms that let you work with file
+    names in a consistent and expressive way.</para>
+
+  <sect1>
+    <title>Simple file naming</title>
+
+    <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the
+	hood</quote> to handle file names.  Every command behaves
+      uniformly with respect to file names.  The way in which commands
+      work with file names is as follows.</para>
+
+    <para id="x_545">If you explicitly name real files on the command line,
+      Mercurial works with exactly those files, as you would expect.
+      <!-- BEGIN filenames.files -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add COPYING README examples/simple.py</userinput>
+</screen>
+<!-- END filenames.files -->
+</para>
+
+    <para id="x_546">When you provide a directory name, Mercurial will interpret
+      this as <quote>operate on every file in this directory and its
+	subdirectories</quote>. Mercurial traverses the files and
+      subdirectories in a directory in alphabetical order.  When it
+      encounters a subdirectory, it will traverse that subdirectory
+      before continuing with the current directory.</para>
+
+      <!-- BEGIN filenames.dirs -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status src</userinput>
+? src/main.py
+? src/watcher/_watcher.c
+? src/watcher/watcher.py
+? src/xyzzy.txt
+</screen>
+<!-- END filenames.dirs -->
+
+  </sect1>
+
+  <sect1>
+    <title>Running commands without any file names</title>
+
+    <para id="x_547">Mercurial's commands that work with file names have useful
+      default behaviors when you invoke them without providing any
+      file names or patterns.  What kind of behavior you should
+      expect depends on what the command does.  Here are a few rules
+      of thumb you can use to predict what a command is likely to do
+      if you don't give it any names to work with.</para>
+    <itemizedlist>
+      <listitem><para id="x_548">Most commands will operate on the entire working
+	  directory. This is what the <command role="hg-cmd" moreinfo="none">hg
+	    add</command> command does, for example.</para>
+      </listitem>
+      <listitem><para id="x_549">If the command has effects that are difficult or
+	  impossible to reverse, it will force you to explicitly
+	  provide at least one name or pattern (see below).  This
+	  protects you from accidentally deleting files by running
+	  <command role="hg-cmd" moreinfo="none">hg remove</command> with no
+	  arguments, for example.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_54a">It's easy to work around these default behaviors if they
+      don't suit you.  If a command normally operates on the whole
+      working directory, you can invoke it on just the current
+      directory and its subdirectories by giving it the name
+      <quote><filename class="directory" moreinfo="none">.</filename></quote>.</para>
+
+    <!-- BEGIN filenames.wdir-subdir -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd src</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n</userinput>
+adding ../MANIFEST.in
+adding ../examples/performant.py
+adding ../setup.py
+adding main.py
+adding watcher/_watcher.c
+adding watcher/watcher.py
+adding xyzzy.txt
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n .</userinput>
+adding main.py
+adding watcher/_watcher.c
+adding watcher/watcher.py
+adding xyzzy.txt
+</screen>
+<!-- END filenames.wdir-subdir -->
+
+
+    <para id="x_54b">Along the same lines, some commands normally print file
+      names relative to the root of the repository, even if you're
+      invoking them from a subdirectory.  Such a command will print
+      file names relative to your subdirectory if you give it explicit
+      names.  Here, we're going to run <command role="hg-cmd" moreinfo="none">hg
+	status</command> from a subdirectory, and get it to operate on
+      the entire working directory while printing file names relative
+      to our subdirectory, by passing it the output of the <command role="hg-cmd" moreinfo="none">hg root</command> command.</para>
+
+      <!-- BEGIN filenames.wdir-relname -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+A COPYING
+A README
+A examples/simple.py
+? MANIFEST.in
+? examples/performant.py
+? setup.py
+? src/main.py
+? src/watcher/_watcher.c
+? src/watcher/watcher.py
+? src/xyzzy.txt
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput>
+A ../COPYING
+A ../README
+A ../examples/simple.py
+? ../MANIFEST.in
+? ../examples/performant.py
+? ../setup.py
+? main.py
+? watcher/_watcher.c
+? watcher/watcher.py
+? xyzzy.txt
+</screen>
+<!-- END filenames.wdir-relname -->
+
+  </sect1>
+
+  <sect1>
+    <title>Telling you what's going on</title>
+
+    <para id="x_54c">The <command role="hg-cmd" moreinfo="none">hg add</command> example in the
+      preceding section illustrates something else that's helpful
+      about Mercurial commands.  If a command operates on a file that
+      you didn't name explicitly on the command line, it will usually
+      print the name of the file, so that you will not be surprised
+      what's going on.</para>
+
+    <para id="x_54d">The principle here is of <emphasis>least
+	surprise</emphasis>.  If you've exactly named a file on the
+      command line, there's no point in repeating it back at you.  If
+      Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
+      because you provided no names, or a directory, or a pattern (see
+      below), it is safest to tell you what files it's operating on.</para>
+
+    <para id="x_54e">For commands that behave this way, you can silence them
+      using the <option role="hg-opt-global">-q</option> option.  You
+      can also get them to print the name of every file, even those
+      you've named explicitly, using the <option role="hg-opt-global">-v</option> option.</para>
+  </sect1>
+
+  <sect1>
+    <title>Using patterns to identify files</title>
+
+    <para id="x_54f">In addition to working with file and directory names,
+      Mercurial lets you use <emphasis>patterns</emphasis> to identify
+      files.  Mercurial's pattern handling is expressive.</para>
+
+    <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of
+      matching file names to patterns normally falls to the shell.  On
+      these systems, you must explicitly tell Mercurial that a name is
+      a pattern.  On Windows, the shell does not expand patterns, so
+      Mercurial will automatically identify names that are patterns,
+      and expand them for you.</para>
+
+    <para id="x_551">To provide a pattern in place of a regular name on the
+      command line, the mechanism is simple:</para>
+    <programlisting format="linespecific">syntax:patternbody</programlisting>
+    <para id="x_552">That is, a pattern is identified by a short text string that
+      says what kind of pattern this is, followed by a colon, followed
+      by the actual pattern.</para>
+
+    <para id="x_553">Mercurial supports two kinds of pattern syntax.  The most
+      frequently used is called <literal moreinfo="none">glob</literal>; this is the
+      same kind of pattern matching used by the Unix shell, and should
+      be familiar to Windows command prompt users, too.</para>
+
+    <para id="x_554">When Mercurial does automatic pattern matching on Windows,
+      it uses <literal moreinfo="none">glob</literal> syntax.  You can thus omit the
+      <quote><literal moreinfo="none">glob:</literal></quote> prefix on Windows, but
+      it's safe to use it, too.</para>
+
+    <para id="x_555">The <literal moreinfo="none">re</literal> syntax is more powerful; it lets
+      you specify patterns using regular expressions, also known as
+      regexps.</para>
+
+    <para id="x_556">By the way, in the examples that follow, notice that I'm
+      careful to wrap all of my patterns in quote characters, so that
+      they won't get expanded by the shell before Mercurial sees
+      them.</para>
+
+    <sect2>
+      <title>Shell-style <literal moreinfo="none">glob</literal> patterns</title>
+
+      <para id="x_557">This is an overview of the kinds of patterns you can use
+	when you're matching on glob patterns.</para>
+
+      <para id="x_558">The <quote><literal moreinfo="none">*</literal></quote> character matches
+	any string, within a single directory.</para>
+
+      <!-- BEGIN filenames.glob.star -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add 'glob:*.py'</userinput>
+adding main.py
+</screen>
+<!-- END filenames.glob.star -->
+
+
+      <para id="x_559">The <quote><literal moreinfo="none">**</literal></quote> pattern matches
+	any string, and crosses directory boundaries.  It's not a
+	standard Unix glob token, but it's accepted by several popular
+	Unix shells, and is very useful.</para>
+
+      <!-- BEGIN filenames.glob.starstar -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
+A examples/simple.py
+A src/main.py
+? examples/performant.py
+? setup.py
+? src/watcher/watcher.py
+</screen>
+<!-- END filenames.glob.starstar -->
+
+
+      <para id="x_55a">The <quote><literal moreinfo="none">?</literal></quote> pattern matches
+	any single character.</para>
+
+      <!-- BEGIN filenames.glob.question -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.?'</userinput>
+? src/watcher/_watcher.c
+</screen>
+<!-- END filenames.glob.question -->
+
+
+      <para id="x_55b">The <quote><literal moreinfo="none">[</literal></quote> character begins a
+	<emphasis>character class</emphasis>.  This matches any single
+	character within the class.  The class ends with a
+	<quote><literal moreinfo="none">]</literal></quote> character.  A class may
+	contain multiple <emphasis>range</emphasis>s of the form
+	<quote><literal moreinfo="none">a-f</literal></quote>, which is shorthand for
+	<quote><literal moreinfo="none">abcdef</literal></quote>.</para>
+
+	<!-- BEGIN filenames.glob.range -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**[nr-t]'</userinput>
+? MANIFEST.in
+? src/xyzzy.txt
+</screen>
+<!-- END filenames.glob.range -->
+
+
+      <para id="x_55c">If the first character after the
+	<quote><literal moreinfo="none">[</literal></quote> in a character class is a
+	<quote><literal moreinfo="none">!</literal></quote>, it
+	<emphasis>negates</emphasis> the class, making it match any
+	single character not in the class.</para>
+
+      <para id="x_55d">A <quote><literal moreinfo="none">{</literal></quote> begins a group of
+	subpatterns, where the whole group matches if any subpattern
+	in the group matches.  The <quote><literal moreinfo="none">,</literal></quote>
+	character separates subpatterns, and
+	<quote><literal moreinfo="none">}</literal></quote> ends the group.</para>
+
+      <!-- BEGIN filenames.glob.group -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.{in,py}'</userinput>
+? MANIFEST.in
+? setup.py
+</screen>
+<!-- END filenames.glob.group -->
+
+
+      <sect3>
+	<title>Watch out!</title>
+
+	<para id="x_55e">Don't forget that if you want to match a pattern in any
+	  directory, you should not be using the
+	  <quote><literal moreinfo="none">*</literal></quote> match-any token, as this
+	  will only match within one directory.  Instead, use the
+	  <quote><literal moreinfo="none">**</literal></quote> token.  This small
+	  example illustrates the difference between the two.</para>
+
+	  <!-- BEGIN filenames.glob.star-starstar -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.py'</userinput>
+? setup.py
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
+A examples/simple.py
+A src/main.py
+? examples/performant.py
+? setup.py
+? src/watcher/watcher.py
+</screen>
+<!-- END filenames.glob.star-starstar -->
+
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Regular expression matching with <literal moreinfo="none">re</literal>
+	patterns</title>
+
+      <para id="x_55f">Mercurial accepts the same regular expression syntax as
+	the Python programming language (it uses Python's regexp
+	engine internally). This is based on the Perl language's
+	regexp syntax, which is the most popular dialect in use (it's
+	also used in Java, for example).</para>
+
+      <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail
+	here, as regexps are not often used.  Perl-style regexps are
+	in any case already exhaustively documented on a multitude of
+	web sites, and in many books.  Instead, I will focus here on a
+	few things you should know if you find yourself needing to use
+	regexps with Mercurial.</para>
+
+      <para id="x_561">A regexp is matched against an entire file name, relative
+	to the root of the repository.  In other words, even if you're
+	already in subbdirectory <filename class="directory" moreinfo="none">foo</filename>, if you want to match files
+	under this directory, your pattern must start with
+	<quote><literal moreinfo="none">foo/</literal></quote>.</para>
+
+      <para id="x_562">One thing to note, if you're familiar with Perl-style
+	regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
+	That is, a regexp starts matching against the beginning of a
+	string; it doesn't look for a match anywhere within the
+	string.  To match anywhere in a string, start your pattern
+	with <quote><literal moreinfo="none">.*</literal></quote>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Filtering files</title>
+
+    <para id="x_563">Not only does Mercurial give you a variety of ways to
+      specify files; it lets you further winnow those files using
+      <emphasis>filters</emphasis>.  Commands that work with file
+      names accept two filtering options.</para>
+    <itemizedlist>
+      <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or
+	  <option role="hg-opt-global">--include</option>, lets you
+	  specify a pattern that file names must match in order to be
+	  processed.</para>
+      </listitem>
+      <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or
+	  <option role="hg-opt-global">--exclude</option>, gives you a
+	  way to <emphasis>avoid</emphasis> processing files, if they
+	  match this pattern.</para>
+      </listitem></itemizedlist>
+    <para id="x_566">You can provide multiple <option role="hg-opt-global">-I</option> and <option role="hg-opt-global">-X</option> options on the command line,
+      and intermix them as you please.  Mercurial interprets the
+      patterns you provide using glob syntax by default (but you can
+      use regexps if you need to).</para>
+
+    <para id="x_567">You can read a <option role="hg-opt-global">-I</option>
+      filter as <quote>process only the files that match this
+	filter</quote>.</para>
+
+    <!-- BEGIN filenames.filter.include -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -I '*.in'</userinput>
+? MANIFEST.in
+</screen>
+<!-- END filenames.filter.include -->
+
+
+    <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best
+      read as <quote>process only the files that don't match this
+	pattern</quote>.</para>
+
+    <!-- BEGIN filenames.filter.exclude -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -X '**.py' src</userinput>
+? src/watcher/_watcher.c
+? src/xyzzy.txt
+</screen>
+<!-- END filenames.filter.exclude -->
+
+  </sect1>
+
+  <sect1>
+    <title>Permanently ignoring unwanted files and directories</title>
+
+    <para id="x_569">When you create a new repository, the chances are
+      that over time it will grow to contain files that ought to
+      <emphasis>not</emphasis> be managed by Mercurial, but which you
+      don't want to see listed every time you run <command moreinfo="none">hg
+	status</command>.  For instance, <quote>build products</quote>
+      are files that are created as part of a build but which should
+      not be managed by a revision control system.  The most common
+      build products are output files produced by software tools such
+      as compilers.  As another example, many text editors litter a
+      directory with lock files, temporary working files, and backup
+      files, which it also makes no sense to manage.</para>
+
+    <para id="x_6b4">To have Mercurial permanently ignore such files, create a
+      file named <filename moreinfo="none">.hgignore</filename> in the root of your
+      repository.  You <emphasis>should</emphasis> <command moreinfo="none">hg
+      add</command> this file so that it gets tracked with the rest of
+      your repository contents, since your collaborators will probably
+      find it useful too.</para>
+
+    <para id="x_6b5">By default, the <filename moreinfo="none">.hgignore</filename> file should
+      contain a list of regular expressions, one per line.  Empty
+      lines are skipped. Most people prefer to describe the files they
+      want to ignore using the <quote>glob</quote> syntax that we
+      described above, so a typical <filename moreinfo="none">.hgignore</filename>
+      file will start with this directive:</para>
+
+    <programlisting format="linespecific">syntax: glob</programlisting>
+
+    <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
+      glob patterns, not regular expressions.</para>
+
+    <para id="x_6b7">Here is a typical-looking <filename moreinfo="none">.hgignore</filename>
+      file.</para>
+
+    <programlisting format="linespecific">syntax: glob
+# This line is a comment, and will be skipped.
+# Empty lines are skipped too.
+
+# Backup files left behind by the Emacs editor.
+*~
+
+# Lock files used by the Emacs editor.
+# Notice that the "#" character is quoted with a backslash.
+# This prevents it from being interpreted as starting a comment.
+.\#*
+
+# Temporary files used by the vim editor.
+.*.swp
+
+# A hidden file created by the Mac OS X Finder.
+.DS_Store
+</programlisting>
+  </sect1>
+
+  <sect1 id="sec:names:case">
+    <title>Case sensitivity</title>
+
+    <para id="x_56a">If you're working in a mixed development environment that
+      contains both Linux (or other Unix) systems and Macs or Windows
+      systems, you should keep in the back of your mind the knowledge
+      that they treat the case (<quote>N</quote> versus
+      <quote>n</quote>) of file names in incompatible ways.  This is
+      not very likely to affect you, and it's easy to deal with if it
+      does, but it could surprise you if you don't know about
+      it.</para>
+
+    <para id="x_56b">Operating systems and filesystems differ in the way they
+      handle the <emphasis>case</emphasis> of characters in file and
+      directory names.  There are three common ways to handle case in
+      names.</para>
+    <itemizedlist>
+      <listitem><para id="x_56c">Completely case insensitive.  Uppercase and
+	  lowercase versions of a letter are treated as identical,
+	  both when creating a file and during subsequent accesses.
+	  This is common on older DOS-based systems.</para>
+      </listitem>
+      <listitem><para id="x_56d">Case preserving, but insensitive.  When a file
+	  or directory is created, the case of its name is stored, and
+	  can be retrieved and displayed by the operating system.
+	  When an existing file is being looked up, its case is
+	  ignored.  This is the standard arrangement on Windows and
+	  MacOS.  The names <filename moreinfo="none">foo</filename> and
+	  <filename moreinfo="none">FoO</filename> identify the same file.  This
+	  treatment of uppercase and lowercase letters as
+	  interchangeable is also referred to as <emphasis>case
+	    folding</emphasis>.</para>
+      </listitem>
+      <listitem><para id="x_56e">Case sensitive.  The case of a name
+	  is significant at all times. The names
+	  <filename moreinfo="none">foo</filename> and <filename moreinfo="none">FoO</filename>
+	  identify different files.  This is the way Linux and Unix
+	  systems normally work.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_56f">On Unix-like systems, it is possible to have any or all of
+      the above ways of handling case in action at once.  For example,
+      if you use a USB thumb drive formatted with a FAT32 filesystem
+      on a Linux system, Linux will handle names on that filesystem in
+      a case preserving, but insensitive, way.</para>
+
+    <sect2>
+      <title>Safe, portable repository storage</title>
+
+      <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case
+	  safe</emphasis>.  It translates file names so that they can
+	be safely stored on both case sensitive and case insensitive
+	filesystems.  This means that you can use normal file copying
+	tools to transfer a Mercurial repository onto, for example, a
+	USB thumb drive, and safely move that drive and repository
+	back and forth between a Mac, a PC running Windows, and a
+	Linux box.</para>
+
+    </sect2>
+    <sect2>
+      <title>Detecting case conflicts</title>
+
+      <para id="x_571">When operating in the working directory, Mercurial honours
+	the naming policy of the filesystem where the working
+	directory is located.  If the filesystem is case preserving,
+	but insensitive, Mercurial will treat names that differ only
+	in case as the same.</para>
+
+      <para id="x_572">An important aspect of this approach is that it is
+	possible to commit a changeset on a case sensitive (typically
+	Linux or Unix) filesystem that will cause trouble for users on
+	case insensitive (usually Windows and MacOS) users.  If a
+	Linux user commits changes to two files, one named
+	<filename moreinfo="none">myfile.c</filename> and the other named
+	<filename moreinfo="none">MyFile.C</filename>, they will be stored correctly
+	in the repository.  And in the working directories of other
+	Linux users, they will be correctly represented as separate
+	files.</para>
+
+      <para id="x_573">If a Windows or Mac user pulls this change, they will not
+	initially have a problem, because Mercurial's repository
+	storage mechanism is case safe.  However, once they try to
+	<command role="hg-cmd" moreinfo="none">hg update</command> the working
+	directory to that changeset, or <command role="hg-cmd" moreinfo="none">hg
+	  merge</command> with that changeset, Mercurial will spot the
+	conflict between the two file names that the filesystem would
+	treat as the same, and forbid the update or merge from
+	occurring.</para>
+    </sect2>
+
+    <sect2>
+      <title>Fixing a case conflict</title>
+
+      <para id="x_574">If you are using Windows or a Mac in a mixed environment
+	where some of your collaborators are using Linux or Unix, and
+	Mercurial reports a case folding conflict when you try to
+	<command role="hg-cmd" moreinfo="none">hg update</command> or <command role="hg-cmd" moreinfo="none">hg merge</command>, the procedure to fix the
+	problem is simple.</para>
+
+      <para id="x_575">Just find a nearby Linux or Unix box, clone the problem
+	repository onto it, and use Mercurial's <command role="hg-cmd" moreinfo="none">hg rename</command> command to change the
+	names of any offending files or directories so that they will
+	no longer cause case folding conflicts.  Commit this change,
+	<command role="hg-cmd" moreinfo="none">hg pull</command> or <command role="hg-cmd" moreinfo="none">hg push</command> it across to your Windows or
+	MacOS system, and <command role="hg-cmd" moreinfo="none">hg update</command>
+	to the revision with the non-conflicting names.</para>
+
+      <para id="x_576">The changeset with case-conflicting names will remain in
+	your project's history, and you still won't be able to
+	<command role="hg-cmd" moreinfo="none">hg update</command> your working
+	directory to that changeset on a Windows or MacOS system, but
+	you can continue development unimpeded.</para>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch08 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:branch">
+  <?dbhtml filename="managing-releases-and-branchy-development.html"?>
+  <title>Managing releases and branchy development</title>
+
+  <para id="x_369">Mercurial provides several mechanisms for you to manage a
+    project that is making progress on multiple fronts at once.  To
+    understand these mechanisms, let's first take a brief look at a
+    fairly normal software project structure.</para>
+
+  <para id="x_36a">Many software projects issue periodic <quote>major</quote>
+    releases that contain substantial new features.  In parallel, they
+    may issue <quote>minor</quote> releases.  These are usually
+    identical to the major releases off which they're based, but with
+    a few bugs fixed.</para>
+
+  <para id="x_36b">In this chapter, we'll start by talking about how to keep
+    records of project milestones such as releases.  We'll then
+    continue on to talk about the flow of work between different
+    phases of a project, and how Mercurial can help you to isolate and
+    manage this work.</para>
+
+  <sect1>
+    <title>Giving a persistent name to a revision</title>
+
+    <para id="x_36c">Once you decide that you'd like to call a particular
+      revision a <quote>release</quote>, it's a good idea to record
+      the identity of that revision. This will let you reproduce that
+      release at a later date, for whatever purpose you might need at
+      the time (reproducing a bug, porting to a new platform, etc).
+      <!-- BEGIN tag.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mytag</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mytag</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello &gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Initial commit'</userinput>
+adding myfile
+</screen>
+<!-- END tag.init -->
+</para>
+
+    <para id="x_36d">Mercurial lets you give a permanent name to any revision
+      using the <command role="hg-cmd" moreinfo="none">hg tag</command> command.  Not
+      surprisingly, these names are called <quote>tags</quote>.</para>
+
+    <!-- BEGIN tag.tag -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
+</screen>
+<!-- END tag.tag -->
+
+
+    <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
+      for a revision.  Tags exist purely for your convenience, so that
+      you have a handy permanent way to refer to a revision; Mercurial
+      doesn't interpret the tag names you use in any way.  Neither
+      does Mercurial place any restrictions on the name of a tag,
+      beyond a few that are necessary to ensure that a tag can be
+      parsed unambiguously.  A tag name cannot contain any of the
+      following characters:</para>
+    <itemizedlist>
+      <listitem><para id="x_36f">Colon (ASCII 58,
+	  <quote><literal moreinfo="none">:</literal></quote>)</para>
+      </listitem>
+      <listitem><para id="x_370">Carriage return (ASCII 13,
+	  <quote><literal moreinfo="none">\r</literal></quote>)</para>
+      </listitem>
+      <listitem><para id="x_371">Newline (ASCII 10,
+	  <quote><literal moreinfo="none">\n</literal></quote>)</para>
+      </listitem></itemizedlist>
+
+    <para id="x_372">You can use the <command role="hg-cmd" moreinfo="none">hg tags</command>
+      command to display the tags present in your repository.  In the
+      output, each tagged revision is identified first by its name,
+      then by revision number, and finally by the unique hash of the
+      revision.</para>
+
+    <!-- BEGIN tag.tags -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
+tip                                1:f283c2669b38
+v1.0                               0:0c957785065f
+</screen>
+<!-- END tag.tags -->
+
+
+    <para id="x_373">Notice that <literal moreinfo="none">tip</literal> is listed in the output
+      of <command role="hg-cmd" moreinfo="none">hg tags</command>.  The
+      <literal moreinfo="none">tip</literal> tag is a special <quote>floating</quote>
+      tag, which always identifies the newest revision in the
+      repository.</para>
+
+    <para id="x_374">In the output of the <command role="hg-cmd" moreinfo="none">hg
+	tags</command> command, tags are listed in reverse order, by
+      revision number.  This usually means that recent tags are listed
+      before older tags.  It also means that <literal moreinfo="none">tip</literal> is
+      always going to be the first tag listed in the output of
+      <command role="hg-cmd" moreinfo="none">hg tags</command>.</para>
+
+    <para id="x_375">When you run <command role="hg-cmd" moreinfo="none">hg log</command>, if it
+      displays a revision that has tags associated with it, it will
+      print those tags.</para>
+
+    <!-- BEGIN tag.log -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
+changeset:   1:f283c2669b38
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:16 2009 +0000
+summary:     Added tag v1.0 for changeset 0c957785065f
+
+changeset:   0:0c957785065f
+tag:         v1.0
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:15 2009 +0000
+summary:     Initial commit
+
+</screen>
+<!-- END tag.log -->
+
+
+    <para id="x_376">Any time you need to provide a revision ID to a Mercurial
+      command, the command will accept a tag name in its place.
+      Internally, Mercurial will translate your tag name into the
+      corresponding revision ID, then use that.</para>
+
+    <!-- BEGIN tag.log.v1.0 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye &gt; myfile2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Second commit'</userinput>
+adding myfile2
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r v1.0</userinput>
+changeset:   0:0c957785065f
+tag:         v1.0
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:15 2009 +0000
+summary:     Initial commit
+
+</screen>
+<!-- END tag.log.v1.0 -->
+
+
+    <para id="x_377">There's no limit on the number of tags you can have in a
+      repository, or on the number of tags that a single revision can
+      have.  As a practical matter, it's not a great idea to have
+      <quote>too many</quote> (a number which will vary from project
+      to project), simply because tags are supposed to help you to
+      find revisions.  If you have lots of tags, the ease of using
+      them to identify revisions diminishes rapidly.</para>
+
+    <para id="x_378">For example, if your project has milestones as frequent as
+      every few days, it's perfectly reasonable to tag each one of
+      those.  But if you have a continuous build system that makes
+      sure every revision can be built cleanly, you'd be introducing a
+      lot of noise if you were to tag every clean build.  Instead, you
+      could tag failed builds (on the assumption that they're rare!),
+      or simply not use tags to track buildability.</para>
+
+    <para id="x_379">If you want to remove a tag that you no longer want, use
+      <command role="hg-cmd" moreinfo="none">hg tag --remove</command>.</para>
+
+    <!-- BEGIN tag.remove -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag --remove v1.0</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
+tip                                3:0f446f1d1f7f
+</screen>
+<!-- END tag.remove -->
+
+
+    <para id="x_37a">You can also modify a tag at any time, so that it identifies
+      a different revision, by simply issuing a new <command role="hg-cmd" moreinfo="none">hg tag</command> command. You'll have to use the
+      <option role="hg-opt-tag">-f</option> option to tell Mercurial
+      that you <emphasis>really</emphasis> want to update the
+      tag.</para>
+
+    <!-- BEGIN tag.replace -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 1 v1.1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
+tip                                4:12fc7bf92915
+v1.1                               1:f283c2669b38
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 2 v1.1</userinput>
+abort: tag 'v1.1' already exists (use -f to force)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -f -r 2 v1.1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
+tip                                5:17e25cf010af
+v1.1                               2:737882b3cc76
+</screen>
+<!-- END tag.replace -->
+
+
+    <para id="x_37b">There will still be a permanent record of the previous
+      identity of the tag, but Mercurial will no longer use it.
+      There's thus no penalty to tagging the wrong revision; all you
+      have to do is turn around and tag the correct revision once you
+      discover your error.</para>
+
+    <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
+      in your repository.  If you've created any tags, you'll find
+      them in a file in the root of your repository named <filename role="special" moreinfo="none">.hgtags</filename>.  When you run the <command role="hg-cmd" moreinfo="none">hg tag</command> command, Mercurial modifies
+      this file, then automatically commits the change to it.  This
+      means that every time you run <command role="hg-cmd" moreinfo="none">hg
+	tag</command>, you'll see a corresponding changeset in the
+      output of <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
+
+    <!-- BEGIN tag.tip -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   5:17e25cf010af
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:16 2009 +0000
+summary:     Added tag v1.1 for changeset 737882b3cc76
+
+</screen>
+<!-- END tag.tip -->
+
+
+    <sect2>
+      <title>Handling tag conflicts during a merge</title>
+
+      <para id="x_37d">You won't often need to care about the <filename role="special" moreinfo="none">.hgtags</filename> file, but it sometimes
+	makes its presence known during a merge.  The format of the
+	file is simple: it consists of a series of lines.  Each line
+	starts with a changeset hash, followed by a space, followed by
+	the name of a tag.</para>
+
+      <para id="x_37e">If you're resolving a conflict in the <filename role="special" moreinfo="none">.hgtags</filename> file during a merge,
+	there's one twist to modifying the <filename role="special" moreinfo="none">.hgtags</filename> file: when Mercurial is
+	parsing the tags in a repository, it
+	<emphasis>never</emphasis> reads the working copy of the
+	<filename role="special" moreinfo="none">.hgtags</filename> file.  Instead, it
+	reads the <emphasis>most recently committed</emphasis>
+	revision of the file.</para>
+
+      <para id="x_37f">An unfortunate consequence of this design is that you
+	can't actually verify that your merged <filename role="special" moreinfo="none">.hgtags</filename> file is correct until
+	<emphasis>after</emphasis> you've committed a change.  So if
+	you find yourself resolving a conflict on <filename role="special" moreinfo="none">.hgtags</filename> during a merge, be sure to
+	run <command role="hg-cmd" moreinfo="none">hg tags</command> after you commit.
+	If it finds an error in the <filename role="special" moreinfo="none">.hgtags</filename> file, it will report the
+	location of the error, which you can then fix and commit.  You
+	should then run <command role="hg-cmd" moreinfo="none">hg tags</command>
+	again, just to be sure that your fix is correct.</para>
+    </sect2>
+
+    <sect2>
+      <title>Tags and cloning</title>
+
+      <para id="x_380">You may have noticed that the <command role="hg-cmd" moreinfo="none">hg
+	  clone</command> command has a <option role="hg-opt-clone">-r</option> option that lets you clone
+	an exact copy of the repository as of a particular changeset.
+	The new clone will not contain any project history that comes
+	after the revision you specified.  This has an interaction
+	with tags that can surprise the unwary.</para>
+
+      <para id="x_381">Recall that a tag is stored as a revision to
+	the <filename role="special" moreinfo="none">.hgtags</filename> file. When you
+	create a tag, the changeset in which its recorded refers to an
+	older changeset.  When you run <command role="hg-cmd" moreinfo="none">hg clone
+	  -r foo</command> to clone a repository as of tag
+	<literal moreinfo="none">foo</literal>, the new clone <emphasis>will not
+	  contain any revision newer than the one the tag refers to,
+	  including the revision where the tag was created</emphasis>.
+	The result is that you'll get exactly the right subset of the
+	project's history in the new repository, but
+	<emphasis>not</emphasis> the tag you might have
+	expected.</para>
+    </sect2>
+
+    <sect2>
+      <title>When permanent tags are too much</title>
+
+      <para id="x_382">Since Mercurial's tags are revision controlled and carried
+	around with a project's history, everyone you work with will
+	see the tags you create.  But giving names to revisions has
+	uses beyond simply noting that revision
+	<literal moreinfo="none">4237e45506ee</literal> is really
+	<literal moreinfo="none">v2.0.2</literal>.  If you're trying to track down a
+	subtle bug, you might want a tag to remind you of something
+	like <quote>Anne saw the symptoms with this
+	  revision</quote>.</para>
+
+      <para id="x_383">For cases like this, what you might want to use are
+	<emphasis>local</emphasis> tags. You can create a local tag
+	with the <option role="hg-opt-tag">-l</option> option to the
+	<command role="hg-cmd" moreinfo="none">hg tag</command> command.  This will
+	store the tag in a file called <filename role="special" moreinfo="none">.hg/localtags</filename>.  Unlike <filename role="special" moreinfo="none">.hgtags</filename>, <filename role="special" moreinfo="none">.hg/localtags</filename> is not revision
+	controlled.  Any tags you create using <option role="hg-opt-tag">-l</option> remain strictly local to the
+	repository you're currently working in.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>The flow of changes—big picture vs. little</title>
+
+    <para id="x_384">To return to the outline I sketched at the
+      beginning of the chapter, let's think about a project that has
+      multiple concurrent pieces of work under development at
+      once.</para>
+
+    <para id="x_385">There might be a push for a new <quote>main</quote> release;
+      a new minor bugfix release to the last main release; and an
+      unexpected <quote>hot fix</quote> to an old release that is now
+      in maintenance mode.</para>
+
+    <para id="x_386">The usual way people refer to these different concurrent
+      directions of development is as <quote>branches</quote>.
+      However, we've already seen numerous times that Mercurial treats
+      <emphasis>all of history</emphasis> as a series of branches and
+      merges.  Really, what we have here is two ideas that are
+      peripherally related, but which happen to share a name.</para>
+    <itemizedlist>
+      <listitem><para id="x_387"><quote>Big picture</quote> branches represent
+	  the sweep of a project's evolution; people give them names,
+	  and talk about them in conversation.</para>
+      </listitem>
+      <listitem><para id="x_388"><quote>Little picture</quote> branches are
+	  artefacts of the day-to-day activity of developing and
+	  merging changes.  They expose the narrative of how the code
+	  was developed.</para>
+      </listitem></itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Managing big-picture branches in repositories</title>
+
+    <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
+      branch in Mercurial is in a dedicated repository.  If you have
+      an existing shared repository—let's call it
+      <literal moreinfo="none">myproject</literal>—that reaches a
+      <quote>1.0</quote> milestone, you can start to prepare for
+      future maintenance releases on top of version 1.0 by tagging the
+      revision from which you prepared the 1.0 release.</para>
+
+    <!-- BEGIN branch-repo.tag -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
+</screen>
+<!-- END branch-repo.tag -->
+
+
+    <para id="x_38a">You can then clone a new shared
+      <literal moreinfo="none">myproject-1.0.1</literal> repository as of that
+      tag.</para>
+
+    <!-- BEGIN branch-repo.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-1.0.1</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END branch-repo.clone -->
+
+
+    <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
+      to go into an upcoming 1.0.1 minor release, they clone the
+      <literal moreinfo="none">myproject-1.0.1</literal> repository, make their
+      changes, and push them back.</para>
+
+    <!-- BEGIN branch-repo.bugfix -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject-1.0.1 my-1.0.1-bugfix</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-1.0.1-bugfix</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'I fixed a bug using only echo!' &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Important fix for 1.0.1'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
+pushing to /tmp/branch-repo3rVLLS/myproject-1.0.1
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+</screen>
+<!-- END branch-repo.bugfix -->
+
+
+    <para id="x_38c">Meanwhile, development for
+      the next major release can continue, isolated and unabated, in
+      the <literal moreinfo="none">myproject</literal> repository.</para>
+
+    <!-- BEGIN branch-repo.new -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject my-feature</userinput>
+updating working directory
+2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-feature</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This sure is an exciting new feature!' &gt; mynewfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New feature'</userinput>
+adding mynewfile
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
+pushing to /tmp/branch-repo3rVLLS/myproject
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files
+</screen>
+<!-- END branch-repo.new -->
+
+  </sect1>
+
+  <sect1>
+    <title>Don't repeat yourself: merging across branches</title>
+
+    <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
+      branch, the chances are good that the bug exists on your
+      project's main branch (and possibly other maintenance branches,
+      too).  It's a rare developer who wants to fix the same bug
+      multiple times, so let's look at a few ways that Mercurial can
+      help you to manage these bugfixes without duplicating your
+      work.</para>
+
+    <para id="x_38e">In the simplest instance, all you need to do is pull changes
+      from your maintenance branch into your local clone of the target
+      branch.</para>
+
+    <!-- BEGIN branch-repo.pull -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-merge</userinput>
+updating working directory
+3 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject-merge</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../myproject-1.0.1</userinput>
+pulling from ../myproject-1.0.1
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 1 changes to 1 files (+1 heads)
+(run 'hg heads' to see heads, 'hg merge' to merge)
+</screen>
+<!-- END branch-repo.pull -->
+
+
+    <para id="x_38f">You'll then need to merge the heads of the two branches, and
+      push back to the main branch.</para>
+
+    <!-- BEGIN branch-repo.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge bugfix from 1.0.1 branch'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
+pushing to /tmp/branch-repo3rVLLS/myproject
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 2 changesets with 1 changes to 1 files
+</screen>
+<!-- END branch-repo.merge -->
+
+  </sect1>
+
+  <sect1>
+    <title>Naming branches within one repository</title>
+
+    <para id="x_390">In most instances, isolating branches in repositories is the
+      right approach.  Its simplicity makes it easy to understand; and
+      so it's hard to make mistakes.  There's a one-to-one
+      relationship between branches you're working in and directories
+      on your system.  This lets you use normal (non-Mercurial-aware)
+      tools to work on files within a branch/repository.</para>
+
+    <para id="x_391">If you're more in the <quote>power user</quote> category
+      (<emphasis>and</emphasis> your collaborators are too), there is
+      an alternative way of handling branches that you can consider.
+      I've already mentioned the human-level distinction between
+      <quote>small picture</quote> and <quote>big picture</quote>
+      branches.  While Mercurial works with multiple <quote>small
+	picture</quote> branches in a repository all the time (for
+      example after you pull changes in, but before you merge them),
+      it can <emphasis>also</emphasis> work with multiple <quote>big
+	picture</quote> branches.</para>
+
+    <para id="x_392">The key to working this way is that Mercurial lets you
+      assign a persistent <emphasis>name</emphasis> to a branch.
+      There always exists a branch named <literal moreinfo="none">default</literal>.
+      Even before you start naming branches yourself, you can find
+      traces of the <literal moreinfo="none">default</literal> branch if you look for
+      them.</para>
+
+    <para id="x_393">As an example, when you run the <command role="hg-cmd" moreinfo="none">hg
+	commit</command> command, and it pops up your editor so that
+      you can enter a commit message, look for a line that contains
+      the text <quote><literal moreinfo="none">HG: branch default</literal></quote> at
+      the bottom. This is telling you that your commit will occur on
+      the branch named <literal moreinfo="none">default</literal>.</para>
+
+    <para id="x_394">To start working with named branches, use the <command role="hg-cmd" moreinfo="none">hg branches</command> command.  This command
+      lists the named branches already present in your repository,
+      telling you which changeset is the tip of each.</para>
+
+    <!-- BEGIN branch-named.branches -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   0:90897f9e54e3
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Initial commit
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
+default                        0:90897f9e54e3
+</screen>
+<!-- END branch-named.branches -->
+
+
+    <para id="x_395">Since you haven't created any named branches yet, the only
+      one that exists is <literal moreinfo="none">default</literal>.</para>
+
+    <para id="x_396">To find out what the <quote>current</quote> branch is, run
+      the <command role="hg-cmd" moreinfo="none">hg branch</command> command, giving
+      it no arguments.  This tells you what branch the parent of the
+      current changeset is on.</para>
+
+    <!-- BEGIN branch-named.branch -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
+default
+</screen>
+<!-- END branch-named.branch -->
+
+
+    <para id="x_397">To create a new branch, run the <command role="hg-cmd" moreinfo="none">hg
+	branch</command> command again.  This time, give it one
+      argument: the name of the branch you want to create.</para>
+
+    <!-- BEGIN branch-named.create -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch foo</userinput>
+marked working directory as branch foo
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
+foo
+</screen>
+<!-- END branch-named.create -->
+
+
+    <para id="x_398">After you've created a branch, you might wonder what effect
+      the <command role="hg-cmd" moreinfo="none">hg branch</command> command has had.
+      What do the <command role="hg-cmd" moreinfo="none">hg status</command> and
+      <command role="hg-cmd" moreinfo="none">hg tip</command> commands report?</para>
+
+    <!-- BEGIN branch-named.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   0:90897f9e54e3
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Initial commit
+
+</screen>
+<!-- END branch-named.status -->
+
+
+    <para id="x_399">Nothing has changed in the
+      working directory, and there's been no new history created.  As
+      this suggests, running the <command role="hg-cmd" moreinfo="none">hg
+	branch</command> command has no permanent effect; it only
+      tells Mercurial what branch name to use the
+      <emphasis>next</emphasis> time you commit a changeset.</para>
+
+    <para id="x_39a">When you commit a change, Mercurial records the name of the
+      branch on which you committed.  Once you've switched from the
+      <literal moreinfo="none">default</literal> branch to another and committed,
+      you'll see the name of the new branch show up in the output of
+      <command role="hg-cmd" moreinfo="none">hg log</command>, <command role="hg-cmd" moreinfo="none">hg tip</command>, and other commands that
+      display the same kind of output.</para>
+
+    <!-- BEGIN branch-named.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'hello again' &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Second commit'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   1:5656f8ffdd49
+branch:      foo
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Second commit
+
+</screen>
+<!-- END branch-named.commit -->
+
+
+    <para id="x_39b">The <command role="hg-cmd" moreinfo="none">hg log</command>-like commands
+      will print the branch name of every changeset that's not on the
+      <literal moreinfo="none">default</literal> branch.  As a result, if you never
+      use named branches, you'll never see this information.</para>
+
+    <para id="x_39c">Once you've named a branch and committed a change with that
+      name, every subsequent commit that descends from that change
+      will inherit the same branch name.  You can change the name of a
+      branch at any time, using the <command role="hg-cmd" moreinfo="none">hg
+	branch</command> command.</para>
+
+    <!-- BEGIN branch-named.rebranch -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
+foo
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch bar</userinput>
+marked working directory as branch bar
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo new file &gt; newfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Third commit'</userinput>
+adding newfile
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   2:c59d680fc2ec
+branch:      bar
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Third commit
+
+</screen>
+<!-- END branch-named.rebranch -->
+
+
+    <para id="x_39d">In practice, this is something you won't do very often, as
+      branch names tend to have fairly long lifetimes.  (This isn't a
+      rule, just an observation.)</para>
+  </sect1>
+
+  <sect1>
+    <title>Dealing with multiple named branches in a
+      repository</title>
+
+    <para id="x_39e">If you have more than one named branch in a repository,
+      Mercurial will remember the branch that your working directory
+      is on when you start a command like <command role="hg-cmd" moreinfo="none">hg
+	update</command> or <command role="hg-cmd" moreinfo="none">hg pull
+	-u</command>.  It will update the working directory to the tip
+      of this branch, no matter what the <quote>repo-wide</quote> tip
+      is.  To update to a revision that's on a different named branch,
+      you may need to use the <option role="hg-opt-update">-C</option>
+      option to <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
+
+    <para id="x_39f">This behavior is a little subtle, so let's see it in
+      action.  First, let's remind ourselves what branch we're
+      currently on, and what branches are in our repository.</para>
+
+    <!-- BEGIN branch-named.parents -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   2:c59d680fc2ec
+branch:      bar
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Third commit
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
+bar                            2:c59d680fc2ec
+foo                            1:5656f8ffdd49 (inactive)
+default                        0:90897f9e54e3 (inactive)
+</screen>
+<!-- END branch-named.parents -->
+
+
+    <para id="x_3a0">We're on the <literal moreinfo="none">bar</literal> branch, but there also
+      exists an older <command role="hg-cmd" moreinfo="none">hg foo</command>
+      branch.</para>
+
+    <para id="x_3a1">We can <command role="hg-cmd" moreinfo="none">hg update</command> back and
+      forth between the tips of the <literal moreinfo="none">foo</literal> and
+      <literal moreinfo="none">bar</literal> branches without needing to use the
+      <option role="hg-opt-update">-C</option> option, because this
+      only involves going backwards and forwards linearly through our
+      change history.</para>
+
+    <!-- BEGIN branch-named.update-switchy -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
+0 files updated, 0 files merged, 1 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   1:5656f8ffdd49
+branch:      foo
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Second commit
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update bar</userinput>
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   2:c59d680fc2ec
+branch:      bar
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Third commit
+
+</screen>
+<!-- END branch-named.update-switchy -->
+
+
+    <para id="x_3a2">If we go back to the <literal moreinfo="none">foo</literal> branch and then
+      run <command role="hg-cmd" moreinfo="none">hg update</command>, it will keep us
+      on <literal moreinfo="none">foo</literal>, not move us to the tip of
+      <literal moreinfo="none">bar</literal>.</para>
+
+    <!-- BEGIN branch-named.update-nothing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
+0 files updated, 0 files merged, 1 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
+0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END branch-named.update-nothing -->
+
+
+    <para id="x_3a3">Committing a new change on the <literal moreinfo="none">foo</literal> branch
+      introduces a new head.</para>
+
+    <!-- BEGIN branch-named.foo-commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo something &gt; somefile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New file'</userinput>
+adding somefile
+created new head
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
+changeset:   3:4dd2f7a37288
+branch:      foo
+tag:         tip
+parent:      1:5656f8ffdd49
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:43 2009 +0000
+summary:     New file
+
+changeset:   2:c59d680fc2ec
+branch:      bar
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:42 2009 +0000
+summary:     Third commit
+
+</screen>
+<!-- END branch-named.foo-commit -->
+
+  </sect1>
+
+  <sect1>
+    <title>Branch names and merging</title>
+
+    <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
+      symmetrical. Let's say our repository has two heads, 17 and 23.
+      If I <command role="hg-cmd" moreinfo="none">hg update</command> to 17 and then
+      <command role="hg-cmd" moreinfo="none">hg merge</command> with 23, Mercurial
+      records 17 as the first parent of the merge, and 23 as the
+      second.  Whereas if I <command role="hg-cmd" moreinfo="none">hg update</command>
+      to 23 and then <command role="hg-cmd" moreinfo="none">hg merge</command> with
+      17, it records 23 as the first parent, and 17 as the
+      second.</para>
+
+    <para id="x_3a5">This affects Mercurial's choice of branch name when you
+      merge.  After a merge, Mercurial will retain the branch name of
+      the first parent when you commit the result of the merge.  If
+      your first parent's branch name is <literal moreinfo="none">foo</literal>, and
+      you merge with <literal moreinfo="none">bar</literal>, the branch name will
+      still be <literal moreinfo="none">foo</literal> after you merge.</para>
+
+    <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
+      each with the same branch name.  Let's say I'm working on the
+      <literal moreinfo="none">foo</literal> branch, and so are you.  We commit
+      different changes; I pull your changes; I now have two heads,
+      each claiming to be on the <literal moreinfo="none">foo</literal> branch.  The
+      result of a merge will be a single head on the
+      <literal moreinfo="none">foo</literal> branch, as you might hope.</para>
+
+    <para id="x_3a7">But if I'm working on the <literal moreinfo="none">bar</literal> branch, and
+      I merge work from the <literal moreinfo="none">foo</literal> branch, the result
+      will remain on the <literal moreinfo="none">bar</literal> branch.</para>
+
+    <!-- BEGIN branch-named.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
+bar
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge foo</userinput>
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   4:9f05d4ef3efe
+branch:      bar
+tag:         tip
+parent:      2:c59d680fc2ec
+parent:      3:4dd2f7a37288
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:44 2009 +0000
+summary:     Merge
+
+</screen>
+<!-- END branch-named.merge -->
+
+
+    <para id="x_3a8">To give a more concrete example, if I'm working on the
+      <literal moreinfo="none">bleeding-edge</literal> branch, and I want to bring in
+      the latest fixes from the <literal moreinfo="none">stable</literal> branch,
+      Mercurial will choose the <quote>right</quote>
+      (<literal moreinfo="none">bleeding-edge</literal>) branch name when I pull and
+      merge from <literal moreinfo="none">stable</literal>.</para>
+  </sect1>
+
+  <sect1>
+    <title>Branch naming is generally useful</title>
+
+    <para id="x_3a9">You shouldn't think of named branches as applicable only to
+      situations where you have multiple long-lived branches
+      cohabiting in a single repository.  They're very useful even in
+      the one-branch-per-repository case.</para>
+
+    <para id="x_3aa">In the simplest case, giving a name to each branch gives you
+      a permanent record of which branch a changeset originated on.
+      This gives you more context when you're trying to follow the
+      history of a long-lived branchy project.</para>
+
+    <para id="x_3ab">If you're working with shared repositories, you can set up a
+      <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook on each
+      that will block incoming changes that have the
+      <quote>wrong</quote> branch name.  This provides a simple, but
+      effective, defence against people accidentally pushing changes
+      from a <quote>bleeding edge</quote> branch to a
+      <quote>stable</quote> branch.  Such a hook might look like this
+      inside the shared repo's <filename role="special" moreinfo="none">
+	/.hgrc</filename>.</para>
+    <programlisting format="linespecific">[hooks]
+pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch09 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:undo">
+  <?dbhtml filename="finding-and-fixing-mistakes.html"?>
+  <title>Finding and fixing mistakes</title>
+
+  <para id="x_d2">To err might be human, but to really handle the consequences
+    well takes a top-notch revision control system.  In this chapter,
+    we'll discuss some of the techniques you can use when you find
+    that a problem has crept into your project.  Mercurial has some
+    highly capable features that will help you to isolate the sources
+    of problems, and to handle them appropriately.</para>
+
+  <sect1>
+    <title>Erasing local history</title>
+
+    <sect2>
+      <title>The accidental commit</title>
+
+      <para id="x_d3">I have the occasional but persistent problem of typing
+	rather more quickly than I can think, which sometimes results
+	in me committing a changeset that is either incomplete or
+	plain wrong.  In my case, the usual kind of incomplete
+	changeset is one in which I've created a new source file, but
+	forgotten to <command role="hg-cmd" moreinfo="none">hg add</command> it.  A
+	<quote>plain wrong</quote> changeset is not as common, but no
+	less annoying.</para>
+
+    </sect2>
+    <sect2 id="sec:undo:rollback">
+      <title>Rolling back a transaction</title>
+
+      <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I
+	mentioned that Mercurial treats each modification of a
+	repository as a <emphasis>transaction</emphasis>.  Every time
+	you commit a changeset or pull changes from another
+	repository, Mercurial remembers what you did.  You can undo,
+	or <emphasis>roll back</emphasis>, exactly one of these
+	actions using the <command role="hg-cmd" moreinfo="none">hg rollback</command>
+	command.  (See <xref linkend="sec:undo:rollback-after-push"/>
+	for an important caveat about the use of this command.)</para>
+
+      <para id="x_d5">Here's a mistake that I often find myself making:
+	committing a change in which I've created a new file, but
+	forgotten to <command role="hg-cmd" moreinfo="none">hg add</command>
+	it.</para>
+
+      <!-- BEGIN rollback.commit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+M a
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b'</userinput>
+</screen>
+<!-- END rollback.commit -->
+
+
+      <para id="x_d6">Looking at the output of <command role="hg-cmd" moreinfo="none">hg
+	  status</command> after the commit immediately confirms the
+	error.</para>
+
+      <!-- BEGIN rollback.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+? b
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   1:246e2aada1c5
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:14 2009 +0000
+summary:     Add file b
+
+</screen>
+<!-- END rollback.status -->
+
+
+      <para id="x_d7">The commit captured the changes to the file
+	<filename moreinfo="none">a</filename>, but not the new file
+	<filename moreinfo="none">b</filename>.  If I were to push this changeset to a
+	repository that I shared with a colleague, the chances are
+	high that something in <filename moreinfo="none">a</filename> would refer to
+	<filename moreinfo="none">b</filename>, which would not be present in their
+	repository when they pulled my changes.  I would thus become
+	the object of some indignation.</para>
+
+      <para id="x_d8">However, luck is with me—I've caught my error
+	before I pushed the changeset.  I use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, and Mercurial
+	makes that last changeset vanish.</para>
+
+      <!-- BEGIN rollback.rollback -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
+rolling back last transaction
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   0:c37ce4157509
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:14 2009 +0000
+summary:     First commit
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+M a
+? b
+</screen>
+<!-- END rollback.rollback -->
+
+
+      <para id="x_d9">Notice that the changeset is no longer present in the
+	repository's history, and the working directory once again
+	thinks that the file <filename moreinfo="none">a</filename> is modified.  The
+	commit and rollback have left the working directory exactly as
+	it was prior to the commit; the changeset has been completely
+	erased.  I can now safely <command role="hg-cmd" moreinfo="none">hg
+	  add</command> the file <filename moreinfo="none">b</filename>, and rerun my
+	commit.</para>
+
+      <!-- BEGIN rollback.add -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b, this time for real'</userinput>
+</screen>
+<!-- END rollback.add -->
+
+
+    </sect2>
+    <sect2>
+      <title>The erroneous pull</title>
+
+      <para id="x_da">It's common practice with Mercurial to maintain separate
+	development branches of a project in different repositories.
+	Your development team might have one shared repository for
+	your project's <quote>0.9</quote> release, and another,
+	containing different changes, for the <quote>1.0</quote>
+	release.</para>
+
+      <para id="x_db">Given this, you can imagine that the consequences could be
+	messy if you had a local <quote>0.9</quote> repository, and
+	accidentally pulled changes from the shared <quote>1.0</quote>
+	repository into it.  At worst, you could be paying
+	insufficient attention, and push those changes into the shared
+	<quote>0.9</quote> tree, confusing your entire team (but don't
+	worry, we'll return to this horror scenario later).  However,
+	it's more likely that you'll notice immediately, because
+	Mercurial will display the URL it's pulling from, or you will
+	see it pull a suspiciously large number of changes into the
+	repository.</para>
+
+      <para id="x_dc">The <command role="hg-cmd" moreinfo="none">hg rollback</command> command
+	will work nicely to expunge all of the changesets that you
+	just pulled.  Mercurial groups all changes from one <command role="hg-cmd" moreinfo="none">hg pull</command> into a single transaction,
+	so one <command role="hg-cmd" moreinfo="none">hg rollback</command> is all you
+	need to undo this mistake.</para>
+
+    </sect2>
+    <sect2 id="sec:undo:rollback-after-push">
+      <title>Rolling back is useless once you've pushed</title>
+
+      <para id="x_dd">The value of the <command role="hg-cmd" moreinfo="none">hg
+	  rollback</command> command drops to zero once you've pushed
+	your changes to another repository.  Rolling back a change
+	makes it disappear entirely, but <emphasis>only</emphasis> in
+	the repository in which you perform the <command role="hg-cmd" moreinfo="none">hg rollback</command>.  Because a rollback
+	eliminates history, there's no way for the disappearance of a
+	change to propagate between repositories.</para>
+
+      <para id="x_de">If you've pushed a change to another
+	repository—particularly if it's a shared
+	repository—it has essentially <quote>escaped into the
+	  wild,</quote> and you'll have to recover from your mistake
+	in a different way.  If you push a changeset somewhere, then
+	roll it back, then pull from the repository you pushed to, the
+	changeset you thought you'd gotten rid of will simply reappear
+	in your repository.</para>
+
+      <para id="x_df">(If you absolutely know for sure that the change
+	you want to roll back is the most recent change in the
+	repository that you pushed to, <emphasis>and</emphasis> you
+	know that nobody else could have pulled it from that
+	repository, you can roll back the changeset there, too, but
+	you really should not expect this to work reliably.  Sooner or
+	later a change really will make it into a repository that you
+	don't directly control (or have forgotten about), and come
+	back to bite you.)</para>
+
+    </sect2>
+    <sect2>
+      <title>You can only roll back once</title>
+
+      <para id="x_e0">Mercurial stores exactly one transaction in its
+	transaction log; that transaction is the most recent one that
+	occurred in the repository. This means that you can only roll
+	back one transaction.  If you expect to be able to roll back
+	one transaction, then its predecessor, this is not the
+	behavior you will get.</para>
+
+      <!-- BEGIN rollback.twice -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
+rolling back last transaction
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
+no rollback information available
+</screen>
+<!-- END rollback.twice -->
+
+
+      <para id="x_e1">Once you've rolled back one transaction in a repository,
+	you can't roll back again in that repository until you perform
+	another commit or pull.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Reverting the mistaken change</title>
+
+    <para id="x_e2">If you make a modification to a file, and decide that you
+      really didn't want to change the file at all, and you haven't
+      yet committed your changes, the <command role="hg-cmd" moreinfo="none">hg
+	revert</command> command is the one you'll need.  It looks at
+      the changeset that's the parent of the working directory, and
+      restores the contents of the file to their state as of that
+      changeset. (That's a long-winded way of saying that, in the
+      normal case, it undoes your modifications.)</para>
+
+    <para id="x_e3">Let's illustrate how the <command role="hg-cmd" moreinfo="none">hg
+	revert</command> command works with yet another small example.
+      We'll begin by modifying a file that Mercurial is already
+      tracking.</para>
+
+    <!-- BEGIN daily.revert.modify -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
+original content
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo unwanted change &gt;&gt; file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff file</userinput>
+diff -r 2eacf948d309 file
+--- a/file	Sun Aug 16 14:05:00 2009 +0000
++++ b/file	Sun Aug 16 14:05:00 2009 +0000
+@@ -1,1 +1,2 @@
+ original content
++unwanted change
+</screen>
+<!-- END daily.revert.modify -->
+
+
+    <para id="x_e4">If we don't
+      want that change, we can simply <command role="hg-cmd" moreinfo="none">hg
+	revert</command> the file.</para>
+
+      <!-- BEGIN daily.revert.unmodify -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+M file
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
+original content
+</screen>
+<!-- END daily.revert.unmodify -->
+
+
+    <para id="x_e5">The <command role="hg-cmd" moreinfo="none">hg revert</command> command
+      provides us with an extra degree of safety by saving our
+      modified file with a <filename moreinfo="none">.orig</filename>
+      extension.</para>
+
+    <!-- BEGIN daily.revert.status -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+? file.orig
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file.orig</userinput>
+original content
+unwanted change
+</screen>
+<!-- END daily.revert.status -->
+
+
+    <tip>
+      <title>Be careful with <filename moreinfo="none">.orig</filename> files</title>
+
+      <para id="x_6b8">It's extremely unlikely that you are either using
+	Mercurial to manage files with <filename moreinfo="none">.orig</filename>
+	extensions or that you even care about the contents of such
+	files.  Just in case, though, it's useful to remember that
+	<command role="hg-cmd" moreinfo="none">hg revert</command> will
+	unconditionally overwrite an existing file with a
+	<filename moreinfo="none">.orig</filename> extension. For instance, if you
+	already have a file named <filename moreinfo="none">foo.orig</filename> when
+	you revert <filename moreinfo="none">foo</filename>, the contents of
+	<filename moreinfo="none">foo.orig</filename> will be clobbered.</para>
+    </tip>
+
+    <para id="x_e6">Here is a summary of the cases that the <command role="hg-cmd" moreinfo="none">hg revert</command> command can deal with.  We
+      will describe each of these in more detail in the section that
+      follows.</para>
+    <itemizedlist>
+      <listitem><para id="x_e7">If you modify a file, it will restore the file
+	  to its unmodified state.</para>
+      </listitem>
+      <listitem><para id="x_e8">If you <command role="hg-cmd" moreinfo="none">hg add</command> a
+	  file, it will undo the <quote>added</quote> state of the
+	  file, but leave the file itself untouched.</para>
+      </listitem>
+      <listitem><para id="x_e9">If you delete a file without telling Mercurial,
+	  it will restore the file to its unmodified contents.</para>
+      </listitem>
+      <listitem><para id="x_ea">If you use the <command role="hg-cmd" moreinfo="none">hg
+	    remove</command> command to remove a file, it will undo
+	  the <quote>removed</quote> state of the file, and restore
+	  the file to its unmodified contents.</para>
+      </listitem></itemizedlist>
+
+    <sect2 id="sec:undo:mgmt">
+      <title>File management errors</title>
+
+      <para id="x_eb">The <command role="hg-cmd" moreinfo="none">hg revert</command> command is
+	useful for more than just modified files.  It lets you reverse
+	the results of all of Mercurial's file management
+	commands—<command role="hg-cmd" moreinfo="none">hg add</command>,
+	<command role="hg-cmd" moreinfo="none">hg remove</command>, and so on.</para>
+
+      <para id="x_ec">If you <command role="hg-cmd" moreinfo="none">hg add</command> a file,
+	then decide that in fact you don't want Mercurial to track it,
+	use <command role="hg-cmd" moreinfo="none">hg revert</command> to undo the
+	add.  Don't worry; Mercurial will not modify the file in any
+	way.  It will just <quote>unmark</quote> the file.</para>
+
+      <!-- BEGIN daily.revert.add -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo oops &gt; oops</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add oops</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status oops</userinput>
+A oops
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert oops</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+? oops
+</screen>
+<!-- END daily.revert.add -->
+
+
+      <para id="x_ed">Similarly, if you ask Mercurial to <command role="hg-cmd" moreinfo="none">hg remove</command> a file, you can use
+	<command role="hg-cmd" moreinfo="none">hg revert</command> to restore it to
+	the contents it had as of the parent of the working directory.
+	<!-- BEGIN daily.revert.remove -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+R file
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
+file
+</screen>
+<!-- END daily.revert.remove -->
+ This works just as
+	well for a file that you deleted by hand, without telling
+	Mercurial (recall that in Mercurial terminology, this kind of
+	file is called <quote>missing</quote>).</para>
+
+      <!-- BEGIN daily.revert.missing -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+! file
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
+file
+</screen>
+<!-- END daily.revert.missing -->
+
+
+      <para id="x_ee">If you revert a <command role="hg-cmd" moreinfo="none">hg copy</command>,
+	the copied-to file remains in your working directory
+	afterwards, untracked.  Since a copy doesn't affect the
+	copied-from file in any way, Mercurial doesn't do anything
+	with the copied-from file.</para>
+
+      <!-- BEGIN daily.revert.copy -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert new-file</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+? new-file
+</screen>
+<!-- END daily.revert.copy -->
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Dealing with committed changes</title>
+
+    <para id="x_f5">Consider a case where you have committed a change
+      <emphasis>a</emphasis>, and another change
+      <emphasis>b</emphasis> on top of it; you then realise that
+      change <emphasis>a</emphasis> was incorrect.  Mercurial lets you
+      <quote>back out</quote> an entire changeset automatically, and
+      building blocks that let you reverse part of a changeset by
+      hand.</para>
+
+    <para id="x_f6">Before you read this section, here's something to
+      keep in mind: the <command role="hg-cmd" moreinfo="none">hg backout</command>
+      command undoes the effect of a change by
+      <emphasis>adding</emphasis> to your repository's history, not by
+      modifying or erasing it.  It's the right tool to use if you're
+      fixing bugs, but not if you're trying to undo some change that
+      has catastrophic consequences.  To deal with those, see
+      <xref linkend="sec:undo:aaaiiieee"/>.</para>
+
+    <sect2>
+      <title>Backing out a changeset</title>
+
+      <para id="x_f7">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
+	lets you <quote>undo</quote> the effects of an entire
+	changeset in an automated fashion.  Because Mercurial's
+	history is immutable, this command <emphasis>does
+	  not</emphasis> get rid of the changeset you want to undo.
+	Instead, it creates a new changeset that
+	<emphasis>reverses</emphasis> the effect of the to-be-undone
+	changeset.</para>
+
+      <para id="x_f8">The operation of the <command role="hg-cmd" moreinfo="none">hg
+	  backout</command> command is a little intricate, so let's
+	illustrate it with some examples.  First, we'll create a
+	repository with some simple changes.</para>
+
+      <!-- BEGIN backout.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first change &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'first change'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo second change &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'second change'</userinput>
+</screen>
+<!-- END backout.init -->
+
+
+      <para id="x_f9">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
+	takes a single changeset ID as its argument; this is the
+	changeset to back out.  Normally, <command role="hg-cmd" moreinfo="none">hg
+	  backout</command> will drop you into a text editor to write
+	a commit message, so you can record why you're backing the
+	change out.  In this example, we provide a commit message on
+	the command line using the <option role="hg-opt-backout">-m</option> option.</para>
+
+    </sect2>
+    <sect2>
+      <title>Backing out the tip changeset</title>
+
+      <para id="x_fa">We're going to start by backing out the last changeset we
+	committed.</para>
+
+      <!-- BEGIN backout.simple -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' tip</userinput>
+reverting myfile
+changeset 2:611a0cae251c backs out changeset 1:43700a9b3ec8
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+first change
+</screen>
+<!-- END backout.simple -->
+
+
+      <para id="x_fb">You can see that the second line from
+	<filename moreinfo="none">myfile</filename> is no longer present.  Taking a
+	look at the output of <command role="hg-cmd" moreinfo="none">hg log</command>
+	gives us an idea of what the <command role="hg-cmd" moreinfo="none">hg
+	  backout</command> command has done.
+	<!-- BEGIN backout.simple.log -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
+2[tip]   611a0cae251c   2009-08-16 14:04 +0000   bos
+  back out second change
+
+1   43700a9b3ec8   2009-08-16 14:04 +0000   bos
+  second change
+
+0   f2ef23d503fd   2009-08-16 14:04 +0000   bos
+  first change
+
+</screen>
+<!-- END backout.simple.log -->
+ Notice that the new changeset
+	that <command role="hg-cmd" moreinfo="none">hg backout</command> has created
+	is a child of the changeset we backed out.  It's easier to see
+	this in <xref linkend="fig:undo:backout"/>, which presents a
+	graphical view of the change history.  As you can see, the
+	history is nice and linear.</para>
+
+      <figure id="fig:undo:backout" float="0">
+	<title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+    </sect2>
+    <sect2>
+      <title>Backing out a non-tip change</title>
+
+      <para id="x_fd">If you want to back out a change other than the last one
+	you committed, pass the <option role="hg-opt-backout">--merge</option> option to the
+	<command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
+
+      <!-- BEGIN backout.non-tip.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo non-tip-repo</userinput>
+requesting all changes
+adding changesets
+adding manifests
+adding file changes
+added 2 changesets with 2 changes to 1 files
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd non-tip-repo</userinput>
+</screen>
+<!-- END backout.non-tip.clone -->
+
+
+      <para id="x_fe">This makes backing out any changeset a
+	<quote>one-shot</quote> operation that's usually simple and
+	fast.</para>
+
+      <!-- BEGIN backout.non-tip.backout -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout --merge -m 'back out second change' 1</userinput>
+reverting myfile
+created new head
+changeset 3:611a0cae251c backs out changeset 1:43700a9b3ec8
+merging with changeset 3:611a0cae251c
+merging myfile
+0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+(branch merge, don't forget to commit)
+</screen>
+<!-- END backout.non-tip.backout -->
+
+
+      <para id="x_ff">If you take a look at the contents of
+	<filename moreinfo="none">myfile</filename> after the backout finishes, you'll
+	see that the first and third changes are present, but not the
+	second.</para>
+
+      <!-- BEGIN backout.non-tip.cat -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+first change
+third change
+</screen>
+<!-- END backout.non-tip.cat -->
+
+
+      <para id="x_100">As the graphical history in <xref linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
+	still commits one change in this kind of situation (the
+	box-shaped node is the ones that Mercurial commits
+	automatically), but the revision graph now looks different.
+	Before Mercurial begins the backout process, it first
+	remembers what the current parent of the working directory is.
+	It then backs out the target changeset, and commits that as a
+	changeset.  Finally, it merges back to the previous parent of
+	the working directory, but notice that it <emphasis>does not
+	  commit</emphasis> the result of the merge.  The repository
+	now contains two heads, and the working directory is in a
+	merge state.</para>
+
+      <figure id="fig:undo:backout-non-tip" float="0">
+	<title>Automated backout of a non-tip change using the
+	  <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_103">The result is that you end up <quote>back where you
+	  were</quote>, only with some extra history that undoes the
+	effect of the changeset you wanted to back out.</para>
+
+      <para id="x_6b9">You might wonder why Mercurial does not commit the result
+	of the merge that it performed.  The reason lies in Mercurial
+	behaving conservatively: a merge naturally has more scope for
+	error than simply undoing the effect of the tip changeset,
+	so your work will be safest if you first inspect (and test!)
+	the result of the merge, <emphasis>then</emphasis> commit
+	it.</para>
+
+      <sect3>
+	<title>Always use the <option role="hg-opt-backout">--merge</option> option</title>
+
+	<para id="x_104">In fact, since the <option role="hg-opt-backout">--merge</option> option will do the
+	  <quote>right thing</quote> whether or not the changeset
+	  you're backing out is the tip (i.e. it won't try to merge if
+	  it's backing out the tip, since there's no need), you should
+	  <emphasis>always</emphasis> use this option when you run the
+	  <command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Gaining more control of the backout process</title>
+
+      <para id="x_105">While I've recommended that you always use the <option role="hg-opt-backout">--merge</option> option when backing
+	out a change, the <command role="hg-cmd" moreinfo="none">hg backout</command>
+	command lets you decide how to merge a backout changeset.
+	Taking control of the backout process by hand is something you
+	will rarely need to do, but it can be useful to understand
+	what the <command role="hg-cmd" moreinfo="none">hg backout</command> command
+	is doing for you automatically.  To illustrate this, let's
+	clone our first repository, but omit the backout change that
+	it contains.</para>
+
+      <!-- BEGIN backout.manual.clone -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo newrepo</userinput>
+requesting all changes
+adding changesets
+adding manifests
+adding file changes
+added 2 changesets with 2 changes to 1 files
+updating working directory
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd newrepo</userinput>
+</screen>
+<!-- END backout.manual.clone -->
+
+
+      <para id="x_106">As with our
+	earlier example, We'll commit a third changeset, then back out
+	its parent, and see what happens.</para>
+
+      <!-- BEGIN backout.manual.backout -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change &gt;&gt; myfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' 1</userinput>
+reverting myfile
+created new head
+changeset 3:bf906ee0baae backs out changeset 1:43700a9b3ec8
+the backout changeset is a new head - do not forget to merge
+(use "backout --merge" if you want to auto-merge)
+</screen>
+<!-- END backout.manual.backout -->
+
+
+      <para id="x_107">Our new changeset is again a descendant of the changeset
+	we backout out; it's thus a new head, <emphasis>not</emphasis>
+	a descendant of the changeset that was the tip.  The <command role="hg-cmd" moreinfo="none">hg backout</command> command was quite
+	explicit in telling us this.</para>
+
+      <!-- BEGIN backout.manual.log -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
+3[tip]:1   bf906ee0baae   2009-08-16 14:04 +0000   bos
+  back out second change
+
+2   2521379001ad   2009-08-16 14:04 +0000   bos
+  third change
+
+1   43700a9b3ec8   2009-08-16 14:04 +0000   bos
+  second change
+
+0   f2ef23d503fd   2009-08-16 14:04 +0000   bos
+  first change
+
+</screen>
+<!-- END backout.manual.log -->
+
+
+      <para id="x_108">Again, it's easier to see what has happened by looking at
+	a graph of the revision history, in <xref linkend="fig:undo:backout-manual"/>.  This makes it clear
+	that when we use <command role="hg-cmd" moreinfo="none">hg backout</command>
+	to back out a change other than the tip, Mercurial adds a new
+	head to the repository (the change it committed is
+	box-shaped).</para>
+
+      <figure id="fig:undo:backout-manual" float="0">
+	<title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_10a">After the <command role="hg-cmd" moreinfo="none">hg backout</command>
+	command has completed, it leaves the new
+	<quote>backout</quote> changeset as the parent of the working
+	directory.</para>
+
+      <!-- BEGIN backout.manual.parents -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
+changeset:   2:2521379001ad
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:37 2009 +0000
+summary:     third change
+
+</screen>
+<!-- END backout.manual.parents -->
+
+
+      <para id="x_10b">Now we have two isolated sets of changes.</para>
+
+      <!-- BEGIN backout.manual.heads -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
+changeset:   3:bf906ee0baae
+tag:         tip
+parent:      1:43700a9b3ec8
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:37 2009 +0000
+summary:     back out second change
+
+changeset:   2:2521379001ad
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:37 2009 +0000
+summary:     third change
+
+</screen>
+<!-- END backout.manual.heads -->
+
+
+      <para id="x_10c">Let's think about what we expect to see as the contents of
+	<filename moreinfo="none">myfile</filename> now.  The first change should be
+	present, because we've never backed it out.  The second change
+	should be missing, as that's the change we backed out.  Since
+	the history graph shows the third change as a separate head,
+	we <emphasis>don't</emphasis> expect to see the third change
+	present in <filename moreinfo="none">myfile</filename>.</para>
+
+      <!-- BEGIN backout.manual.cat -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+first change
+</screen>
+<!-- END backout.manual.cat -->
+
+
+      <para id="x_10d">To get the third change back into the file, we just do a
+	normal merge of our two heads.</para>
+
+      <!-- BEGIN backout.manual.merge -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
+abort: outstanding uncommitted changes
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'merged backout with previous tip'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
+first change
+</screen>
+<!-- END backout.manual.merge -->
+
+
+      <para id="x_10e">Afterwards, the graphical history of our
+	repository looks like
+	<xref linkend="fig:undo:backout-manual-merge"/>.</para>
+
+      <figure id="fig:undo:backout-manual-merge" float="0">
+	<title>Manually merging a backout change</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+    </sect2>
+    <sect2>
+      <title>Why <command role="hg-cmd" moreinfo="none">hg backout</command> works as
+	it does</title>
+
+      <para id="x_110">Here's a brief description of how the <command role="hg-cmd" moreinfo="none">hg backout</command> command works.</para>
+      <orderedlist inheritnum="ignore" continuation="restarts">
+	<listitem><para id="x_111">It ensures that the working directory is
+	    <quote>clean</quote>, i.e. that the output of <command role="hg-cmd" moreinfo="none">hg status</command> would be empty.</para>
+	</listitem>
+	<listitem><para id="x_112">It remembers the current parent of the working
+	    directory.  Let's call this changeset
+	    <literal moreinfo="none">orig</literal>.</para>
+	</listitem>
+	<listitem><para id="x_113">It does the equivalent of a <command role="hg-cmd" moreinfo="none">hg update</command> to sync the working
+	    directory to the changeset you want to back out.  Let's
+	    call this changeset <literal moreinfo="none">backout</literal>.</para>
+	</listitem>
+	<listitem><para id="x_114">It finds the parent of that changeset.  Let's
+	    call that changeset <literal moreinfo="none">parent</literal>.</para>
+	</listitem>
+	<listitem><para id="x_115">For each file that the
+	    <literal moreinfo="none">backout</literal> changeset affected, it does the
+	    equivalent of a <command role="hg-cmd" moreinfo="none">hg revert -r
+	      parent</command> on that file, to restore it to the
+	    contents it had before that changeset was
+	    committed.</para>
+	</listitem>
+	<listitem><para id="x_116">It commits the result as a new changeset.
+	    This changeset has <literal moreinfo="none">backout</literal> as its
+	    parent.</para>
+	</listitem>
+	<listitem><para id="x_117">If you specify <option role="hg-opt-backout">--merge</option> on the command
+	    line, it merges with <literal moreinfo="none">orig</literal>, and commits
+	    the result of the merge.</para>
+	</listitem></orderedlist>
+
+      <para id="x_118">An alternative way to implement the <command role="hg-cmd" moreinfo="none">hg backout</command> command would be to
+	<command role="hg-cmd" moreinfo="none">hg export</command> the
+	to-be-backed-out changeset as a diff, then use the <option role="cmd-opt-patch">--reverse</option> option to the
+	<command moreinfo="none">patch</command> command to reverse the effect of the
+	change without fiddling with the working directory.  This
+	sounds much simpler, but it would not work nearly as
+	well.</para>
+
+      <para id="x_119">The reason that <command role="hg-cmd" moreinfo="none">hg
+	  backout</command> does an update, a commit, a merge, and
+	another commit is to give the merge machinery the best chance
+	to do a good job when dealing with all the changes
+	<emphasis>between</emphasis> the change you're backing out and
+	the current tip.</para>
+
+      <para id="x_11a">If you're backing out a changeset that's 100 revisions
+	back in your project's history, the chances that the
+	<command moreinfo="none">patch</command> command will be able to apply a
+	reverse diff cleanly are not good, because intervening changes
+	are likely to have <quote>broken the context</quote> that
+	<command moreinfo="none">patch</command> uses to determine whether it can
+	apply a patch (if this sounds like gibberish, see <xref linkend="sec:mq:patch"/> for a
+	discussion of the <command moreinfo="none">patch</command> command).  Also,
+	Mercurial's merge machinery will handle files and directories
+	being renamed, permission changes, and modifications to binary
+	files, none of which <command moreinfo="none">patch</command> can deal
+	with.</para>
+
+    </sect2>
+  </sect1>
+  <sect1 id="sec:undo:aaaiiieee">
+    <title>Changes that should never have been</title>
+
+    <para id="x_11b">Most of the time, the <command role="hg-cmd" moreinfo="none">hg
+	backout</command> command is exactly what you need if you want
+      to undo the effects of a change.  It leaves a permanent record
+      of exactly what you did, both when committing the original
+      changeset and when you cleaned up after it.</para>
+
+    <para id="x_11c">On rare occasions, though, you may find that you've
+      committed a change that really should not be present in the
+      repository at all.  For example, it would be very unusual, and
+      usually considered a mistake, to commit a software project's
+      object files as well as its source files.  Object files have
+      almost no intrinsic value, and they're <emphasis>big</emphasis>,
+      so they increase the size of the repository and the amount of
+      time it takes to clone or pull changes.</para>
+
+    <para id="x_11d">Before I discuss the options that you have if you commit a
+      <quote>brown paper bag</quote> change (the kind that's so bad
+      that you want to pull a brown paper bag over your head), let me
+      first discuss some approaches that probably won't work.</para>
+
+    <para id="x_11e">Since Mercurial treats history as
+      accumulative—every change builds on top of all changes
+      that preceded it—you generally can't just make disastrous
+      changes disappear.  The one exception is when you've just
+      committed a change, and it hasn't been pushed or pulled into
+      another repository.  That's when you can safely use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, as I detailed in
+      <xref linkend="sec:undo:rollback"/>.</para>
+
+    <para id="x_11f">After you've pushed a bad change to another repository, you
+      <emphasis>could</emphasis> still use <command role="hg-cmd" moreinfo="none">hg
+	rollback</command> to make your local copy of the change
+      disappear, but it won't have the consequences you want.  The
+      change will still be present in the remote repository, so it
+      will reappear in your local repository the next time you
+      pull.</para>
+
+    <para id="x_120">If a situation like this arises, and you know which
+      repositories your bad change has propagated into, you can
+      <emphasis>try</emphasis> to get rid of the change from
+      <emphasis>every</emphasis> one of those repositories.  This is,
+      of course, not a satisfactory solution: if you miss even a
+      single repository while you're expunging, the change is still
+      <quote>in the wild</quote>, and could propagate further.</para>
+
+    <para id="x_121">If you've committed one or more changes
+      <emphasis>after</emphasis> the change that you'd like to see
+      disappear, your options are further reduced. Mercurial doesn't
+      provide a way to <quote>punch a hole</quote> in history, leaving
+      changesets intact.</para>
+
+    <sect2>
+      <title>Backing out a merge</title>
+
+      <para id="x_6ba">Since merges are often complicated, it is not unheard of
+	for a merge to be mangled badly, but committed erroneously.
+	Mercurial provides an important safeguard against bad merges
+	by refusing to commit unresolved files, but human ingenuity
+	guarantees that it is still possible to mess a merge up and
+	commit it.</para>
+
+      <para id="x_6bb">Given a bad merge that has been committed, usually the
+	best way to approach it is to simply try to repair the damage
+	by hand.  A complete disaster that cannot be easily fixed up
+	by hand ought to be very rare, but the <command role="hg-cmd" moreinfo="none">hg backout</command> command may help in
+	making the cleanup easier. It offers a <option role="hg-opt-backout">--parent</option> option, which lets
+	you specify which parent to revert to when backing out a
+	merge.</para>
+
+      <figure id="fig:undo:bad-merge-1" float="0">
+	<title>A bad merge</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_6bc">Suppose we have a revision graph like that in <xref linkend="fig:undo:bad-merge-1"/>.  What we'd like is to
+	<emphasis>redo</emphasis> the merge of revisions 2 and
+	3.</para>
+
+      <para id="x_6bd">One way to do so would be as follows.</para>
+
+      <orderedlist inheritnum="ignore" continuation="restarts">
+	<listitem>
+	  <para id="x_6be">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
+	      --parent=2</command>.  This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
+	    4, which is the bad merge, and to when deciding which
+	    revision to prefer, to choose parent 2, one of the parents
+	    of the merge.  The effect can be seen in <xref linkend="fig:undo:bad-merge-2"/>.</para>
+	  <figure id="fig:undo:bad-merge-2" float="0">
+	    <title>Backing out the merge, favoring one parent</title>
+	    <mediaobject>
+	      <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject>
+	      <textobject><phrase>XXX add text</phrase></textobject>
+	    </mediaobject>
+	  </figure>
+	</listitem>
+
+	<listitem>
+	  <para id="x_6bf">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
+	      --parent=3</command>.  This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
+	    4 again, but this time to choose parent 3, the other
+	    parent of the merge.  The result is visible in <xref linkend="fig:undo:bad-merge-3"/>, in which the repository
+	    now contains three heads.</para>
+	  <figure id="fig:undo:bad-merge-3" float="0">
+	    <title>Backing out the merge, favoring the other
+	      parent</title>
+	    <mediaobject>
+	      <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject>
+	      <textobject><phrase>XXX add text</phrase></textobject>
+	    </mediaobject>
+	  </figure>
+	</listitem>
+
+	<listitem>
+	  <para id="x_6c0">Redo the bad merge by merging the two backout heads,
+	    which reduces the number of heads in the repository to
+	    two, as can be seen in <xref linkend="fig:undo:bad-merge-4"/>.</para>
+	  <figure id="fig:undo:bad-merge-4" float="0">
+	    <title>Merging the backouts</title>
+	    <mediaobject>
+	      <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject>
+	      <textobject><phrase>XXX add text</phrase></textobject>
+	    </mediaobject>
+	  </figure>
+	</listitem>
+
+	<listitem>
+	  <para id="x_6c1">Merge with the commit that was made after the bad
+	    merge, as shown in <xref linkend="fig:undo:bad-merge-5"/>.</para>
+	  <figure id="fig:undo:bad-merge-5" float="0">
+	    <title>Merging the backouts</title>
+	    <mediaobject>
+	      <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject>
+	      <textobject><phrase>XXX add text</phrase></textobject>
+	    </mediaobject>
+	  </figure>
+	</listitem>
+      </orderedlist>
+    </sect2>
+
+    <sect2>
+      <title>Protect yourself from <quote>escaped</quote>
+	changes</title>
+
+      <para id="x_123">If you've committed some changes to your local repository
+	and they've been pushed or pulled somewhere else, this isn't
+	necessarily a disaster.  You can protect yourself ahead of
+	time against some classes of bad changeset.  This is
+	particularly easy if your team usually pulls changes from a
+	central repository.</para>
+
+      <para id="x_124">By configuring some hooks on that repository to validate
+	incoming changesets (see chapter <xref linkend="chap:hook"/>),
+	you can
+	automatically prevent some kinds of bad changeset from being
+	pushed to the central repository at all.  With such a
+	configuration in place, some kinds of bad changeset will
+	naturally tend to <quote>die out</quote> because they can't
+	propagate into the central repository.  Better yet, this
+	happens without any need for explicit intervention.</para>
+
+      <para id="x_125">For instance, an incoming change hook that
+	verifies that a changeset will actually compile can prevent
+	people from inadvertently <quote>breaking the
+	  build</quote>.</para>
+    </sect2>
+
+    <sect2>
+      <title>What to do about sensitive changes that escape</title>
+
+      <para id="x_6c2">Even a carefully run project can suffer an unfortunate
+	event such as the committing and uncontrolled propagation of a
+	file that contains important passwords.</para>
+
+      <para id="x_6c3">If something like this happens to you, and the information
+	that gets accidentally propagated is truly sensitive, your
+	first step should be to mitigate the effect of the leak
+	without trying to control the leak itself. If you are not 100%
+	certain that you know exactly who could have seen the changes,
+	you should immediately change passwords, cancel credit cards,
+	or find some other way to make sure that the information that
+	has leaked is no longer useful.  In other words, assume that
+	the change has propagated far and wide, and that there's
+	nothing more you can do.</para>
+
+      <para id="x_6c4">You might hope that there would be mechanisms you could
+	use to either figure out who has seen a change or to erase the
+	change permanently everywhere, but there are good reasons why
+	these are not possible.</para>
+
+      <para id="x_6c5">Mercurial does not provide an audit trail of who has
+	pulled changes from a repository, because it is usually either
+	impossible to record such information or trivial to spoof it.
+	In a multi-user or networked environment, you should thus be
+	extremely skeptical of yourself if you think that you have
+	identified every place that a sensitive changeset has
+	propagated to.  Don't forget that people can and will send
+	bundles by email, have their backup software save data
+	offsite, carry repositories on USB sticks, and find other
+	completely innocent ways to confound your attempts to track
+	down every copy of a problematic change.</para>
+
+      <para id="x_6c6">Mercurial also does not provide a way to make a file or
+	changeset completely disappear from history, because there is
+	no way to enforce its disappearance; someone could easily
+	modify their copy of Mercurial to ignore such directives. In
+	addition, even if Mercurial provided such a capability,
+	someone who simply hadn't pulled a <quote>make this file
+	  disappear</quote> changeset wouldn't be affected by it, nor
+	would web crawlers visiting at the wrong time, disk backups,
+	or other mechanisms.  Indeed, no distributed revision control
+	system can make data reliably vanish. Providing the illusion
+	of such control could easily give a false sense of security,
+	and be worse than not providing it at all.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:undo:bisect">
+    <title>Finding the source of a bug</title>
+
+    <para id="x_126">While it's all very well to be able to back out a changeset
+      that introduced a bug, this requires that you know which
+      changeset to back out.  Mercurial provides an invaluable
+      command, called <command role="hg-cmd" moreinfo="none">hg bisect</command>, that
+      helps you to automate this process and accomplish it very
+      efficiently.</para>
+
+    <para id="x_127">The idea behind the <command role="hg-cmd" moreinfo="none">hg
+	bisect</command> command is that a changeset has introduced
+      some change of behavior that you can identify with a simple
+      pass/fail test.  You don't know which piece of code introduced the
+      change, but you know how to test for the presence of the bug.
+      The <command role="hg-cmd" moreinfo="none">hg bisect</command> command uses your
+      test to direct its search for the changeset that introduced the
+      code that caused the bug.</para>
+
+    <para id="x_128">Here are a few scenarios to help you understand how you
+      might apply this command.</para>
+    <itemizedlist>
+      <listitem><para id="x_129">The most recent version of your software has a
+	  bug that you remember wasn't present a few weeks ago, but
+	  you don't know when it was introduced.  Here, your binary
+	  test checks for the presence of that bug.</para>
+      </listitem>
+      <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to
+	  close the entry in your team's bug database.  The bug
+	  database requires a changeset ID when you close an entry,
+	  but you don't remember which changeset you fixed the bug in.
+	  Once again, your binary test checks for the presence of the
+	  bug.</para>
+      </listitem>
+      <listitem><para id="x_12b">Your software works correctly, but runs 15%
+	  slower than the last time you measured it.  You want to know
+	  which changeset introduced the performance regression.  In
+	  this case, your binary test measures the performance of your
+	  software, to see whether it's <quote>fast</quote> or
+	  <quote>slow</quote>.</para>
+      </listitem>
+      <listitem><para id="x_12c">The sizes of the components of your project that
+	  you ship exploded recently, and you suspect that something
+	  changed in the way you build your project.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_12d">From these examples, it should be clear that the <command role="hg-cmd" moreinfo="none">hg bisect</command> command is not useful only
+      for finding the sources of bugs.  You can use it to find any
+      <quote>emergent property</quote> of a repository (anything that
+      you can't find from a simple text search of the files in the
+      tree) for which you can write a binary test.</para>
+
+    <para id="x_12e">We'll introduce a little bit of terminology here, just to
+      make it clear which parts of the search process are your
+      responsibility, and which are Mercurial's.  A
+      <emphasis>test</emphasis> is something that
+      <emphasis>you</emphasis> run when <command role="hg-cmd" moreinfo="none">hg
+	bisect</command> chooses a changeset.  A
+      <emphasis>probe</emphasis> is what <command role="hg-cmd" moreinfo="none">hg
+	bisect</command> runs to tell whether a revision is good.
+      Finally, we'll use the word <quote>bisect</quote>, as both a
+      noun and a verb, to stand in for the phrase <quote>search using
+	the <command role="hg-cmd" moreinfo="none">hg bisect</command>
+	command</quote>.</para>
+
+    <para id="x_12f">One simple way to automate the searching process would be
+      simply to probe every changeset.  However, this scales poorly.
+      If it took ten minutes to test a single changeset, and you had
+      10,000 changesets in your repository, the exhaustive approach
+      would take on average 35 <emphasis>days</emphasis> to find the
+      changeset that introduced a bug.  Even if you knew that the bug
+      was introduced by one of the last 500 changesets, and limited
+      your search to those, you'd still be looking at over 40 hours to
+      find the changeset that introduced your bug.</para>
+
+    <para id="x_130">What the <command role="hg-cmd" moreinfo="none">hg bisect</command> command
+      does is use its knowledge of the <quote>shape</quote> of your
+      project's revision history to perform a search in time
+      proportional to the <emphasis>logarithm</emphasis> of the number
+      of changesets to check (the kind of search it performs is called
+      a dichotomic search).  With this approach, searching through
+      10,000 changesets will take less than three hours, even at ten
+      minutes per test (the search will require about 14 tests).
+      Limit your search to the last hundred changesets, and it will
+      take only about an hour (roughly seven tests).</para>
+
+    <para id="x_131">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command is
+      aware of the <quote>branchy</quote> nature of a Mercurial
+      project's revision history, so it has no problems dealing with
+      branches, merges, or multiple heads in a repository.  It can
+      prune entire branches of history with a single probe, which is
+      how it operates so efficiently.</para>
+
+    <sect2>
+      <title>Using the <command role="hg-cmd" moreinfo="none">hg bisect</command>
+	command</title>
+
+      <para id="x_132">Here's an example of <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> in action.</para>
+
+      <note>
+	<para id="x_133">  In versions 0.9.5 and earlier of Mercurial, <command role="hg-cmd" moreinfo="none">hg bisect</command> was not a core command:
+	  it was distributed with Mercurial as an extension. This
+	  section describes the built-in command, not the old
+	  extension.</para>
+      </note>
+
+      <para id="x_134">Now let's create a repository, so that we can try out the
+	<command role="hg-cmd" moreinfo="none">hg bisect</command> command in
+	isolation.</para>
+
+      <!-- BEGIN bisect.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mybug</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mybug</userinput>
+</screen>
+<!-- END bisect.init -->
+
+
+      <para id="x_135">We'll simulate a project that has a bug in it in a
+	simple-minded way: create trivial changes in a loop, and
+	nominate one specific change that will have the
+	<quote>bug</quote>.  This loop creates 35 changesets, each
+	adding a single file to the repository. We'll represent our
+	<quote>bug</quote> with a file that contains the text <quote>i
+	  have a gub</quote>.</para>
+
+      <!-- BEGIN bisect.commits -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">buggy_change=22</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">for (( i = 0; i &lt; 35; i++ )); do</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  if [[ $i = $buggy_change ]]; then</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    echo 'i have a gub' &gt; myfile$i</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    hg commit -q -A -m 'buggy changeset'</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  else</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    echo 'nothing to see here, move along' &gt; myfile$i</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    hg commit -q -A -m 'normal changeset'</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  fi</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">done</userinput>
+</screen>
+<!-- END bisect.commits -->
+
+
+      <para id="x_136">The next thing that we'd like to do is figure out how to
+	use the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.
+	We can use Mercurial's normal built-in help mechanism for
+	this.</para>
+
+      <!-- BEGIN bisect.help -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help bisect</userinput>
+hg bisect [-gbsr] [-c CMD] [REV]
+
+subdivision search of changesets
+
+    This command helps to find changesets which introduce problems.
+    To use, mark the earliest changeset you know exhibits the problem
+    as bad, then mark the latest changeset which is free from the
+    problem as good. Bisect will update your working directory to a
+    revision for testing (unless the --noupdate option is specified).
+    Once you have performed tests, mark the working directory as bad
+    or good and bisect will either update to another candidate changeset
+    or announce that it has found the bad revision.
+
+    As a shortcut, you can also use the revision argument to mark a
+    revision as good or bad without checking it out first.
+
+    If you supply a command it will be used for automatic bisection. Its exit
+    status will be used as flag to mark revision as bad or good. In case exit
+    status is 0 the revision is marked as good, 125 - skipped, 127 (command not
+    found) - bisection will be aborted; any other status bigger than 0 will
+    mark revision as bad.
+
+options:
+
+ -r --reset     reset bisect state
+ -g --good      mark changeset good
+ -b --bad       mark changeset bad
+ -s --skip      skip testing changeset
+ -c --command   use command to check changeset state
+ -U --noupdate  do not update to target
+
+use "hg -v help bisect" to show global options
+</screen>
+<!-- END bisect.help -->
+
+
+      <para id="x_137">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
+	works in steps.  Each step proceeds as follows.</para>
+      <orderedlist inheritnum="ignore" continuation="restarts">
+	<listitem><para id="x_138">You run your binary test.</para>
+	  <itemizedlist>
+	    <listitem><para id="x_139">If the test succeeded, you tell <command role="hg-cmd" moreinfo="none">hg bisect</command> by running the
+		<command role="hg-cmd" moreinfo="none">hg bisect --good</command>
+		command.</para>
+	    </listitem>
+	    <listitem><para id="x_13a">If it failed, run the <command role="hg-cmd" moreinfo="none">hg bisect --bad</command>
+		command.</para></listitem></itemizedlist>
+	</listitem>
+	<listitem><para id="x_13b">The command uses your information to decide
+	    which changeset to test next.</para>
+	</listitem>
+	<listitem><para id="x_13c">It updates the working directory to that
+	    changeset, and the process begins again.</para>
+	</listitem></orderedlist>
+      <para id="x_13d">The process ends when <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> identifies a unique changeset that marks
+	the point where your test transitioned from
+	<quote>succeeding</quote> to <quote>failing</quote>.</para>
+
+      <para id="x_13e">To start the search, we must run the <command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command.</para>
+
+      <!-- BEGIN bisect.search.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
+</screen>
+<!-- END bisect.search.init -->
+
+
+      <para id="x_13f">In our case, the binary test we use is simple: we check to
+	see if any file in the repository contains the string <quote>i
+	  have a gub</quote>.  If it does, this changeset contains the
+	change that <quote>caused the bug</quote>.  By convention, a
+	changeset that has the property we're searching for is
+	<quote>bad</quote>, while one that doesn't is
+	<quote>good</quote>.</para>
+
+      <para id="x_140">Most of the time, the revision to which the working
+	directory is synced (usually the tip) already exhibits the
+	problem introduced by the buggy change, so we'll mark it as
+	<quote>bad</quote>.</para>
+
+      <!-- BEGIN bisect.search.bad-init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --bad</userinput>
+</screen>
+<!-- END bisect.search.bad-init -->
+
+
+      <para id="x_141">Our next task is to nominate a changeset that we know
+	<emphasis>doesn't</emphasis> have the bug; the <command role="hg-cmd" moreinfo="none">hg bisect</command> command will
+	<quote>bracket</quote> its search between the first pair of
+	good and bad changesets.  In our case, we know that revision
+	10 didn't have the bug.  (I'll have more words about choosing
+	the first <quote>good</quote> changeset later.)</para>
+
+      <!-- BEGIN bisect.search.good-init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --good 10</userinput>
+Testing changeset 22:69f52b967ab8 (24 changesets remaining, ~4 tests)
+0 files updated, 0 files merged, 12 files removed, 0 files unresolved
+</screen>
+<!-- END bisect.search.good-init -->
+
+
+      <para id="x_142">Notice that this command printed some output.</para>
+      <itemizedlist>
+	<listitem><para id="x_143">It told us how many changesets it must
+	    consider before it can identify the one that introduced
+	    the bug, and how many tests that will require.</para>
+	</listitem>
+	<listitem><para id="x_144">It updated the working directory to the next
+	    changeset to test, and told us which changeset it's
+	    testing.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_145">We now run our test in the working directory.  We use the
+	<command moreinfo="none">grep</command> command to see if our
+	<quote>bad</quote> file is present in the working directory.
+	If it is, this revision is bad; if not, this revision is good.
+	<!-- BEGIN bisect.search.step1 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">if grep -q 'i have a gub' *</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">then</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  result=bad</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">else</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  result=good</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">fi</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo this revision is $result</userinput>
+this revision is bad
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --$result</userinput>
+Testing changeset 16:f1dd8bc690ae (12 changesets remaining, ~3 tests)
+0 files updated, 0 files merged, 6 files removed, 0 files unresolved
+</screen>
+<!-- END bisect.search.step1 -->
+</para>
+
+      <para id="x_146">This test looks like a perfect candidate for automation,
+	so let's turn it into a shell function.</para>
+      <!-- BEGIN bisect.search.mytest -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest() {</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  if grep -q 'i have a gub' *</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  then</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    result=bad</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  else</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    result=good</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  fi</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  echo this revision is $result</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  hg bisect --$result</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">}</userinput>
+</screen>
+<!-- END bisect.search.mytest -->
+
+
+      <para id="x_147">We can now run an entire test step with a single command,
+	<literal moreinfo="none">mytest</literal>.</para>
+
+      <!-- BEGIN bisect.search.step2 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
+this revision is good
+Testing changeset 19:88d99d97058a (6 changesets remaining, ~2 tests)
+3 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END bisect.search.step2 -->
+
+
+      <para id="x_148">A few more invocations of our canned test step command,
+	and we're done.</para>
+
+      <!-- BEGIN bisect.search.rest -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
+this revision is good
+Testing changeset 20:32a195a31d51 (3 changesets remaining, ~1 tests)
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
+this revision is good
+Testing changeset 21:a2efe8e4f624 (2 changesets remaining, ~1 tests)
+1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
+this revision is good
+The first bad revision is:
+changeset:   22:69f52b967ab8
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:04:39 2009 +0000
+summary:     buggy changeset
+
+</screen>
+<!-- END bisect.search.rest -->
+
+
+      <para id="x_149">Even though we had 40 changesets to search through, the
+	<command role="hg-cmd" moreinfo="none">hg bisect</command> command let us find
+	the changeset that introduced our <quote>bug</quote> with only
+	five tests.  Because the number of tests that the <command role="hg-cmd" moreinfo="none">hg bisect</command> command performs grows
+	logarithmically with the number of changesets to search, the
+	advantage that it has over the <quote>brute force</quote>
+	search approach increases with every changeset you add.</para>
+
+    </sect2>
+    <sect2>
+      <title>Cleaning up after your search</title>
+
+      <para id="x_14a">When you're finished using the <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> command in a repository, you can use the
+	<command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command to
+	drop the information it was using to drive your search.  The
+	command doesn't use much space, so it doesn't matter if you
+	forget to run this command.  However, <command role="hg-cmd" moreinfo="none">hg bisect</command> won't let you start a new
+	search in that repository until you do a <command role="hg-cmd" moreinfo="none">hg bisect --reset</command>.</para>
+
+      <!-- BEGIN bisect.search.reset -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
+</screen>
+<!-- END bisect.search.reset -->
+
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Tips for finding bugs effectively</title>
+
+    <sect2>
+      <title>Give consistent input</title>
+
+      <para id="x_14b">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
+	requires that you correctly report the result of every test
+	you perform.  If you tell it that a test failed when it really
+	succeeded, it <emphasis>might</emphasis> be able to detect the
+	inconsistency.  If it can identify an inconsistency in your
+	reports, it will tell you that a particular changeset is both
+	good and bad. However, it can't do this perfectly; it's about
+	as likely to report the wrong changeset as the source of the
+	bug.</para>
+
+    </sect2>
+    <sect2>
+      <title>Automate as much as possible</title>
+
+      <para id="x_14c">When I started using the <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> command, I tried a few times to run my
+	tests by hand, on the command line.  This is an approach that
+	I, at least, am not suited to.  After a few tries, I found
+	that I was making enough mistakes that I was having to restart
+	my searches several times before finally getting correct
+	results.</para>
+
+      <para id="x_14d">My initial problems with driving the <command role="hg-cmd" moreinfo="none">hg bisect</command> command by hand occurred
+	even with simple searches on small repositories; if the
+	problem you're looking for is more subtle, or the number of
+	tests that <command role="hg-cmd" moreinfo="none">hg bisect</command> must
+	perform increases, the likelihood of operator error ruining
+	the search is much higher.  Once I started automating my
+	tests, I had much better results.</para>
+
+      <para id="x_14e">The key to automated testing is twofold:</para>
+      <itemizedlist>
+	<listitem><para id="x_14f">always test for the same symptom, and</para>
+	</listitem>
+	<listitem><para id="x_150">always feed consistent input to the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.</para>
+	</listitem></itemizedlist>
+      <para id="x_151">In my tutorial example above, the <command moreinfo="none">grep</command>
+	command tests for the symptom, and the <literal moreinfo="none">if</literal>
+	statement takes the result of this check and ensures that we
+	always feed the same input to the <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> command.  The <literal moreinfo="none">mytest</literal>
+	function marries these together in a reproducible way, so that
+	every test is uniform and consistent.</para>
+
+    </sect2>
+    <sect2>
+      <title>Check your results</title>
+
+      <para id="x_152">Because the output of a <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> search is only as good as the input you
+	give it, don't take the changeset it reports as the absolute
+	truth.  A simple way to cross-check its report is to manually
+	run your test at each of the following changesets:</para>
+      <itemizedlist>
+	<listitem><para id="x_153">The changeset that it reports as the first bad
+	    revision.  Your test should still report this as
+	    bad.</para>
+	</listitem>
+	<listitem><para id="x_154">The parent of that changeset (either parent,
+	    if it's a merge). Your test should report this changeset
+	    as good.</para>
+	</listitem>
+	<listitem><para id="x_155">A child of that changeset.  Your test should
+	    report this changeset as bad.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title>Beware interference between bugs</title>
+
+      <para id="x_156">It's possible that your search for one bug could be
+	disrupted by the presence of another.  For example, let's say
+	your software crashes at revision 100, and worked correctly at
+	revision 50.  Unknown to you, someone else introduced a
+	different crashing bug at revision 60, and fixed it at
+	revision 80.  This could distort your results in one of
+	several ways.</para>
+
+      <para id="x_157">It is possible that this other bug completely
+	<quote>masks</quote> yours, which is to say that it occurs
+	before your bug has a chance to manifest itself.  If you can't
+	avoid that other bug (for example, it prevents your project
+	from building), and so can't tell whether your bug is present
+	in a particular changeset, the <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> command cannot help you directly.  Instead,
+	you can mark a changeset as untested by running <command role="hg-cmd" moreinfo="none">hg bisect --skip</command>.</para>
+
+      <para id="x_158">A different problem could arise if your test for a bug's
+	presence is not specific enough.  If you check for <quote>my
+	  program crashes</quote>, then both your crashing bug and an
+	unrelated crashing bug that masks it will look like the same
+	thing, and mislead <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command>.</para>
+
+      <para id="x_159">Another useful situation in which to use <command role="hg-cmd" moreinfo="none">hg bisect --skip</command> is if you can't
+	test a revision because your project was in a broken and hence
+	untestable state at that revision, perhaps because someone
+	checked in a change that prevented the project from
+	building.</para>
+
+    </sect2>
+    <sect2>
+      <title>Bracket your search lazily</title>
+
+      <para id="x_15a">Choosing the first <quote>good</quote> and
+	<quote>bad</quote> changesets that will mark the end points of
+	your search is often easy, but it bears a little discussion
+	nevertheless.  From the perspective of <command role="hg-cmd" moreinfo="none">hg bisect</command>, the <quote>newest</quote>
+	changeset is conventionally <quote>bad</quote>, and the older
+	changeset is <quote>good</quote>.</para>
+
+      <para id="x_15b">If you're having trouble remembering when a suitable
+	<quote>good</quote> change was, so that you can tell <command role="hg-cmd" moreinfo="none">hg bisect</command>, you could do worse than
+	testing changesets at random.  Just remember to eliminate
+	contenders that can't possibly exhibit the bug (perhaps
+	because the feature with the bug isn't present yet) and those
+	where another problem masks the bug (as I discussed
+	above).</para>
+
+      <para id="x_15c">Even if you end up <quote>early</quote> by thousands of
+	changesets or months of history, you will only add a handful
+	of tests to the total number that <command role="hg-cmd" moreinfo="none">hg
+	  bisect</command> must perform, thanks to its logarithmic
+	behavior.</para>
+
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch10 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:hook">
+  <?dbhtml filename="handling-repository-events-with-hooks.html"?>
+  <title>Handling repository events with hooks</title>
+
+  <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
+    automated actions in response to events that occur in a
+    repository.  In some cases, you can even control Mercurial's
+    response to those events.</para>
+
+  <para id="x_1e7">The name Mercurial uses for one of these actions is a
+    <emphasis>hook</emphasis>. Hooks are called
+    <quote>triggers</quote> in some revision control systems, but the
+    two names refer to the same idea.</para>
+
+  <sect1>
+    <title>An overview of hooks in Mercurial</title>
+
+    <para id="x_1e8">Here is a brief list of the hooks that Mercurial
+      supports. We will revisit each of these hooks in more detail
+      later, in <xref linkend="sec:hook:ref"/>.</para>
+
+    <para id="x_1f6">Each of the hooks whose description begins with the word
+      <quote>Controlling</quote> has the ability to determine whether
+      an activity can proceed.  If the hook succeeds, the activity may
+      proceed; if it fails, the activity is either not permitted or
+      undone, depending on the hook.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_1e9"><literal role="hook" moreinfo="none">changegroup</literal>: This
+	  is run after a group of changesets has been brought into the
+	  repository from elsewhere.</para>
+      </listitem>
+      <listitem><para id="x_1ea"><literal role="hook" moreinfo="none">commit</literal>: This is
+	  run after a new changeset has been created in the local
+	  repository.</para>
+      </listitem>
+      <listitem><para id="x_1eb"><literal role="hook" moreinfo="none">incoming</literal>: This is
+	  run once for each new changeset that is brought into the
+	  repository from elsewhere.  Notice the difference from
+	  <literal role="hook" moreinfo="none">changegroup</literal>, which is run
+	  once per <emphasis>group</emphasis> of changesets brought
+	  in.</para>
+      </listitem>
+      <listitem><para id="x_1ec"><literal role="hook" moreinfo="none">outgoing</literal>: This is
+	  run after a group of changesets has been transmitted from
+	  this repository.</para>
+      </listitem>
+      <listitem><para id="x_1ed"><literal role="hook" moreinfo="none">prechangegroup</literal>:
+	  This is run before starting to bring a group of changesets
+	  into the repository.
+	</para>
+      </listitem>
+      <listitem><para id="x_1ee"><literal role="hook" moreinfo="none">precommit</literal>:
+	  Controlling. This is run before starting a commit.
+	</para>
+      </listitem>
+      <listitem><para id="x_1ef"><literal role="hook" moreinfo="none">preoutgoing</literal>:
+	  Controlling. This is run before starting to transmit a group
+	  of changesets from this repository.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f0"><literal role="hook" moreinfo="none">pretag</literal>:
+	  Controlling. This is run before creating a tag.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f1"><literal role="hook" moreinfo="none">pretxnchangegroup</literal>: Controlling. This
+	  is run after a group of changesets has been brought into the
+	  local repository from another, but before the transaction
+	  completes that will make the changes permanent in the
+	  repository.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f2"><literal role="hook" moreinfo="none">pretxncommit</literal>:
+	  Controlling. This is run after a new changeset has been
+	  created in the local repository, but before the transaction
+	  completes that will make it permanent.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f3"><literal role="hook" moreinfo="none">preupdate</literal>:
+	  Controlling. This is run before starting an update or merge
+	  of the working directory.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f4"><literal role="hook" moreinfo="none">tag</literal>: This is run
+	  after a tag is created.
+	</para>
+      </listitem>
+      <listitem><para id="x_1f5"><literal role="hook" moreinfo="none">update</literal>: This is
+	  run after an update or merge of the working directory has
+	  finished.
+	</para>
+      </listitem></itemizedlist>
+
+  </sect1>
+  <sect1>
+    <title>Hooks and security</title>
+
+    <sect2>
+      <title>Hooks are run with your privileges</title>
+
+      <para id="x_1f7">When you run a Mercurial command in a repository, and the
+	command causes a hook to run, that hook runs on
+	<emphasis>your</emphasis> system, under
+	<emphasis>your</emphasis> user account, with
+	<emphasis>your</emphasis> privilege level.  Since hooks are
+	arbitrary pieces of executable code, you should treat them
+	with an appropriate level of suspicion.  Do not install a hook
+	unless you are confident that you know who created it and what
+	it does.
+      </para>
+
+      <para id="x_1f8">In some cases, you may be exposed to hooks that you did
+	not install yourself.  If you work with Mercurial on an
+	unfamiliar system, Mercurial will run hooks defined in that
+	system's global <filename role="special" moreinfo="none">~/.hgrc</filename>
+	file.
+      </para>
+
+      <para id="x_1f9">If you are working with a repository owned by another
+	user, Mercurial can run hooks defined in that user's
+	repository, but it will still run them as <quote>you</quote>.
+	For example, if you <command role="hg-cmd" moreinfo="none">hg pull</command>
+	from that repository, and its <filename role="special" moreinfo="none">.hg/hgrc</filename> defines a local <literal role="hook" moreinfo="none">outgoing</literal> hook, that hook will run
+	under your user account, even though you don't own that
+	repository.
+      </para>
+
+      <note>
+	<para id="x_1fa">  This only applies if you are pulling from a repository
+	  on a local or network filesystem.  If you're pulling over
+	  http or ssh, any <literal role="hook" moreinfo="none">outgoing</literal>
+	  hook will run under whatever account is executing the server
+	  process, on the server.
+	</para>
+      </note>
+
+      <para id="x_1fb">To see what hooks are defined in a repository,
+	use the <command role="hg-cmd" moreinfo="none">hg showconfig hooks</command>
+	command.  If you are working in one repository, but talking to
+	another that you do not own (e.g. using <command role="hg-cmd" moreinfo="none">hg pull</command> or <command role="hg-cmd" moreinfo="none">hg
+	  incoming</command>), remember that it is the other
+	repository's hooks you should be checking, not your own.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Hooks do not propagate</title>
+
+      <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
+	not propagate when you clone, or pull from, a repository.  The
+	reason for this is simple: a hook is a completely arbitrary
+	piece of executable code.  It runs under your user identity,
+	with your privilege level, on your machine.
+      </para>
+
+      <para id="x_1fd">It would be extremely reckless for any distributed
+	revision control system to implement revision-controlled
+	hooks, as this would offer an easily exploitable way to
+	subvert the accounts of users of the revision control system.
+      </para>
+
+      <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
+	collaborating with other people on a common project, you
+	should not assume that they are using the same Mercurial hooks
+	as you are, or that theirs are correctly configured.  You
+	should document the hooks you expect people to use.
+      </para>
+
+      <para id="x_1ff">In a corporate intranet, this is somewhat easier to
+	control, as you can for example provide a
+	<quote>standard</quote> installation of Mercurial on an NFS
+	filesystem, and use a site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file to define hooks that all users will
+	see.  However, this too has its limits; see below.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Hooks can be overridden</title>
+
+      <para id="x_200">Mercurial allows you to override a hook definition by
+	redefining the hook.  You can disable it by setting its value
+	to the empty string, or change its behavior as you wish.
+      </para>
+
+      <para id="x_201">If you deploy a system- or site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file that defines some
+	hooks, you should thus understand that your users can disable
+	or override those hooks.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Ensuring that critical hooks are run</title>
+
+      <para id="x_202">Sometimes you may want to enforce a policy that you do not
+	want others to be able to work around.  For example, you may
+	have a requirement that every changeset must pass a rigorous
+	set of tests.  Defining this requirement via a hook in a
+	site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> won't
+	work for remote users on laptops, and of course local users
+	can subvert it at will by overriding the hook.
+      </para>
+
+      <para id="x_203">Instead, you can set up your policies for use of Mercurial
+	so that people are expected to propagate changes through a
+	well-known <quote>canonical</quote> server that you have
+	locked down and configured appropriately.
+      </para>
+
+      <para id="x_204">One way to do this is via a combination of social
+	engineering and technology.  Set up a restricted-access
+	account; users can push changes over the network to
+	repositories managed by this account, but they cannot log into
+	the account and run normal shell commands.  In this scenario,
+	a user can commit a changeset that contains any old garbage
+	they want.
+      </para>
+
+      <para id="x_205">When someone pushes a changeset to the server that
+	everyone pulls from, the server will test the changeset before
+	it accepts it as permanent, and reject it if it fails to pass
+	the test suite.  If people only pull changes from this
+	filtering server, it will serve to ensure that all changes
+	that people pull have been automatically vetted.
+      </para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:hook:simple">
+    <title>A short tutorial on using hooks</title>
+
+    <para id="x_212">It is easy to write a Mercurial hook.  Let's start with a
+      hook that runs when you finish a <command role="hg-cmd" moreinfo="none">hg
+	commit</command>, and simply prints the hash of the changeset
+      you just created.  The hook is called <literal role="hook" moreinfo="none">commit</literal>.
+    </para>
+
+    <para id="x_213">All hooks follow the pattern in this example.</para>
+
+<!-- BEGIN hook.simple.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hook-test</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hook-test</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '[hooks]' &gt;&gt; .hg/hgrc</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit = echo committed $HG_NODE' &gt;&gt; .hg/hgrc</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
+[hooks]
+commit = echo committed $HG_NODE
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'testing commit hook'</userinput>
+committed 13a334d1e5ca83fea465aa779110eec3c5ddd6b1
+</screen>
+<!-- END hook.simple.init -->
+
+
+    <para id="x_214">You add an entry to the <literal role="rc-hooks" moreinfo="none">hooks</literal> section of your <filename role="special" moreinfo="none">~/.hgrc</filename>.  On the left is the name of
+      the event to trigger on; on the right is the action to take.  As
+      you can see, you can run an arbitrary shell command in a hook.
+      Mercurial passes extra information to the hook using environment
+      variables (look for <envar>HG_NODE</envar> in the example).
+    </para>
+
+    <sect2>
+      <title>Performing multiple actions per event</title>
+
+      <para id="x_215">Quite often, you will want to define more than one hook
+	for a particular kind of event, as shown below.</para>
+
+<!-- BEGIN hook.simple.ext -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit.when = echo -n "date of commit: "; date' &gt;&gt; .hg/hgrc</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt;&gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i have two hooks'</userinput>
+committed 3be6e2778fb853cbc7e5138d0b9c29386504670b
+date of commit: Sun Aug 16 14:05:05 GMT 2009
+</screen>
+<!-- END hook.simple.ext -->
+
+
+      <para id="x_216">Mercurial lets you do this by adding an
+	<emphasis>extension</emphasis> to the end of a hook's name.
+	You extend a hook's name by giving the name of the hook,
+	followed by a full stop (the
+	<quote><literal moreinfo="none">.</literal></quote> character), followed by
+	some more text of your choosing.  For example, Mercurial will
+	run both <literal moreinfo="none">commit.foo</literal> and
+	<literal moreinfo="none">commit.bar</literal> when the
+	<literal moreinfo="none">commit</literal> event occurs.
+      </para>
+
+      <para id="x_217">To give a well-defined order of execution when there are
+	multiple hooks defined for an event, Mercurial sorts hooks by
+	extension, and executes the hook commands in this sorted
+	order.  In the above example, it will execute
+	<literal moreinfo="none">commit.bar</literal> before
+	<literal moreinfo="none">commit.foo</literal>, and <literal moreinfo="none">commit</literal>
+	before both.
+      </para>
+
+      <para id="x_218">It is a good idea to use a somewhat descriptive
+	extension when you define a new hook.  This will help you to
+	remember what the hook was for.  If the hook fails, you'll get
+	an error message that contains the hook name and extension, so
+	using a descriptive extension could give you an immediate hint
+	as to why the hook failed (see <xref linkend="sec:hook:perm"/> for an example).
+      </para>
+
+    </sect2>
+    <sect2 id="sec:hook:perm">
+      <title>Controlling whether an activity can proceed</title>
+
+      <para id="x_219">In our earlier examples, we used the <literal role="hook" moreinfo="none">commit</literal> hook, which is run after a
+	commit has completed.  This is one of several Mercurial hooks
+	that run after an activity finishes.  Such hooks have no way
+	of influencing the activity itself.
+      </para>
+
+      <para id="x_21a">Mercurial defines a number of events that occur before an
+	activity starts; or after it starts, but before it finishes.
+	Hooks that trigger on these events have the added ability to
+	choose whether the activity can continue, or will abort.
+      </para>
+
+      <para id="x_21b">The <literal role="hook" moreinfo="none">pretxncommit</literal> hook runs
+	after a commit has all but completed.  In other words, the
+	metadata representing the changeset has been written out to
+	disk, but the transaction has not yet been allowed to
+	complete.  The <literal role="hook" moreinfo="none">pretxncommit</literal>
+	hook has the ability to decide whether the transaction can
+	complete, or must be rolled back.
+      </para>
+
+      <para id="x_21c">If the <literal role="hook" moreinfo="none">pretxncommit</literal> hook
+	exits with a status code of zero, the transaction is allowed
+	to complete; the commit finishes; and the <literal role="hook" moreinfo="none">commit</literal> hook is run.  If the <literal role="hook" moreinfo="none">pretxncommit</literal> hook exits with a
+	non-zero status code, the transaction is rolled back; the
+	metadata representing the changeset is erased; and the
+	<literal role="hook" moreinfo="none">commit</literal> hook is not run.
+      </para>
+
+<!-- BEGIN hook.simple.pretxncommit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat check_bug_id</userinput>
+#!/bin/sh
+# check that a commit comment mentions a numeric bug id
+hg log -r $1 --template {desc} | grep -q "\&lt;bug *[0-9]"
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'pretxncommit.bug_id_required = ./check_bug_id $HG_NODE' &gt;&gt; .hg/hgrc</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt;&gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i am not mentioning a bug id'</userinput>
+transaction abort!
+rollback completed
+abort: pretxncommit.bug_id_required hook exited with status 1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i refer you to bug 666'</userinput>
+committed 1a52be73a1ca4fa05e269f99003ed00912e8e836
+date of commit: Sun Aug 16 14:05:05 GMT 2009
+</screen>
+<!-- END hook.simple.pretxncommit -->
+
+
+      <para id="x_21d">The hook in the example above checks that a commit comment
+	contains a bug ID.  If it does, the commit can complete.  If
+	not, the commit is rolled back.
+      </para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Writing your own hooks</title>
+
+    <para id="x_21e">When you are writing a hook, you might find it useful to run
+      Mercurial either with the <option role="hg-opt-global">-v</option> option, or the <envar role="rc-item-ui">verbose</envar> config item set to
+      <quote>true</quote>.  When you do so, Mercurial will print a
+      message before it calls each hook.
+    </para>
+
+    <sect2 id="sec:hook:lang">
+      <title>Choosing how your hook should run</title>
+
+      <para id="x_21f">You can write a hook either as a normal
+	program—typically a shell script—or as a Python
+	function that is executed within the Mercurial process.
+      </para>
+
+      <para id="x_220">Writing a hook as an external program has the advantage
+	that it requires no knowledge of Mercurial's internals.  You
+	can call normal Mercurial commands to get any added
+	information you need.  The trade-off is that external hooks
+	are slower than in-process hooks.
+      </para>
+
+      <para id="x_221">An in-process Python hook has complete access to the
+	Mercurial API, and does not <quote>shell out</quote> to
+	another process, so it is inherently faster than an external
+	hook.  It is also easier to obtain much of the information
+	that a hook requires by using the Mercurial API than by
+	running Mercurial commands.
+      </para>
+
+      <para id="x_222">If you are comfortable with Python, or require high
+	performance, writing your hooks in Python may be a good
+	choice.  However, when you have a straightforward hook to
+	write and you don't need to care about performance (probably
+	the majority of hooks), a shell script is perfectly fine.
+      </para>
+
+    </sect2>
+    <sect2 id="sec:hook:param">
+      <title>Hook parameters</title>
+
+      <para id="x_223">Mercurial calls each hook with a set of well-defined
+	parameters.  In Python, a parameter is passed as a keyword
+	argument to your hook function.  For an external program, a
+	parameter is passed as an environment variable.
+      </para>
+
+      <para id="x_224">Whether your hook is written in Python or as a shell
+	script, the hook-specific parameter names and values will be
+	the same.  A boolean parameter will be represented as a
+	boolean value in Python, but as the number 1 (for
+	<quote>true</quote>) or 0 (for <quote>false</quote>) as an
+	environment variable for an external hook.  If a hook
+	parameter is named <literal moreinfo="none">foo</literal>, the keyword
+	argument for a Python hook will also be named
+	<literal moreinfo="none">foo</literal>, while the environment variable for an
+	external hook will be named <literal moreinfo="none">HG_FOO</literal>.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Hook return values and activity control</title>
+
+      <para id="x_225">A hook that executes successfully must exit with a status
+	of zero if external, or return boolean <quote>false</quote> if
+	in-process.  Failure is indicated with a non-zero exit status
+	from an external hook, or an in-process hook returning boolean
+	<quote>true</quote>.  If an in-process hook raises an
+	exception, the hook is considered to have failed.
+      </para>
+
+      <para id="x_226">For a hook that controls whether an activity can proceed,
+	zero/false means <quote>allow</quote>, while
+	non-zero/true/exception means <quote>deny</quote>.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Writing an external hook</title>
+
+      <para id="x_227">When you define an external hook in your <filename role="special" moreinfo="none">~/.hgrc</filename> and the hook is run, its
+	value is passed to your shell, which interprets it.  This
+	means that you can use normal shell constructs in the body of
+	the hook.
+      </para>
+
+      <para id="x_228">An executable hook is always run with its current
+	directory set to a repository's root directory.
+      </para>
+
+      <para id="x_229">Each hook parameter is passed in as an environment
+	variable; the name is upper-cased, and prefixed with the
+	string <quote><literal moreinfo="none">HG_</literal></quote>.
+      </para>
+
+      <para id="x_22a">With the exception of hook parameters, Mercurial does not
+	set or modify any environment variables when running a hook.
+	This is useful to remember if you are writing a site-wide hook
+	that may be run by a number of different users with differing
+	environment variables set. In multi-user situations, you
+	should not rely on environment variables being set to the
+	values you have in your environment when testing the hook.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Telling Mercurial to use an in-process hook</title>
+
+      <para id="x_22b">The <filename role="special" moreinfo="none">~/.hgrc</filename> syntax
+	for defining an in-process hook is slightly different than for
+	an executable hook.  The value of the hook must start with the
+	text <quote><literal moreinfo="none">python:</literal></quote>, and continue
+	with the fully-qualified name of a callable object to use as
+	the hook's value.
+      </para>
+
+      <para id="x_22c">The module in which a hook lives is automatically imported
+	when a hook is run.  So long as you have the module name and
+	<envar>PYTHONPATH</envar> right, it should <quote>just
+	  work</quote>.
+      </para>
+
+      <para id="x_22d">The following <filename role="special" moreinfo="none">~/.hgrc</filename>
+	example snippet illustrates the syntax and meaning of the
+	notions we just described.
+      </para>
+      <programlisting format="linespecific">[hooks]
+commit.example = python:mymodule.submodule.myhook</programlisting>
+      <para id="x_22e">When Mercurial runs the <literal moreinfo="none">commit.example</literal>
+	hook, it imports <literal moreinfo="none">mymodule.submodule</literal>, looks
+	for the callable object named <literal moreinfo="none">myhook</literal>, and
+	calls it.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Writing an in-process hook</title>
+
+      <para id="x_22f">The simplest in-process hook does nothing, but illustrates
+	the basic shape of the hook API:
+      </para>
+      <programlisting format="linespecific">def myhook(ui, repo, **kwargs):
+    pass</programlisting>
+      <para id="x_230">The first argument to a Python hook is always a <literal role="py-mod-mercurial.ui" moreinfo="none">ui</literal> object.  The second
+	is a repository object; at the moment, it is always an
+	instance of <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>.
+	Following these two arguments are other keyword arguments.
+	Which ones are passed in depends on the hook being called, but
+	a hook can ignore arguments it doesn't care about by dropping
+	them into a keyword argument dict, as with
+	<literal moreinfo="none">**kwargs</literal> above.
+      </para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Some hook examples</title>
+
+    <sect2>
+      <title>Writing meaningful commit messages</title>
+
+      <para id="x_231">It's hard to imagine a useful commit message being very
+	short. The simple <literal role="hook" moreinfo="none">pretxncommit</literal>
+	hook of the example below will prevent you from committing a
+	changeset with a message that is less than ten bytes long.
+      </para>
+
+<!-- BEGIN hook.msglen.go -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
+[hooks]
+pretxncommit.msglen = test `hg tip --template {desc} | wc -c` -ge 10
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'too short'</userinput>
+transaction abort!
+rollback completed
+abort: pretxncommit.msglen hook exited with status 1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'long enough'</userinput>
+</screen>
+<!-- END hook.msglen.go -->
+
+    </sect2>
+
+    <sect2>
+      <title>Checking for trailing whitespace</title>
+
+      <para id="x_232">An interesting use of a commit-related hook is to help you
+	to write cleaner code.  A simple example of <quote>cleaner
+	  code</quote> is the dictum that a change should not add any
+	new lines of text that contain <quote>trailing
+	  whitespace</quote>.  Trailing whitespace is a series of
+	space and tab characters at the end of a line of text.  In
+	most cases, trailing whitespace is unnecessary, invisible
+	noise, but it is occasionally problematic, and people often
+	prefer to get rid of it.
+      </para>
+
+      <para id="x_233">You can use either the <literal role="hook" moreinfo="none">precommit</literal> or <literal role="hook" moreinfo="none">pretxncommit</literal> hook to tell whether you
+	have a trailing whitespace problem.  If you use the <literal role="hook" moreinfo="none">precommit</literal> hook, the hook will not know
+	which files you are committing, so it will have to check every
+	modified file in the repository for trailing white space.  If
+	you want to commit a change to just the file
+	<filename moreinfo="none">foo</filename>, but the file
+	<filename moreinfo="none">bar</filename> contains trailing whitespace, doing a
+	check in the <literal role="hook" moreinfo="none">precommit</literal> hook
+	will prevent you from committing <filename moreinfo="none">foo</filename> due
+	to the problem with <filename moreinfo="none">bar</filename>.  This doesn't
+	seem right.
+      </para>
+
+      <para id="x_234">Should you choose the <literal role="hook" moreinfo="none">pretxncommit</literal> hook, the check won't
+	occur until just before the transaction for the commit
+	completes.  This will allow you to check for problems only the
+	exact files that are being committed.  However, if you entered
+	the commit message interactively and the hook fails, the
+	transaction will roll back; you'll have to re-enter the commit
+	message after you fix the trailing whitespace and run <command role="hg-cmd" moreinfo="none">hg commit</command> again.
+      </para>
+
+      <!-- BEGIN ch09/hook.ws.simple -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
+[hooks]
+pretxncommit.whitespace = hg export tip | (! egrep -q '^\+.*[ \t]$')
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'test with trailing whitespace'</userinput>
+adding a
+transaction abort!
+rollback completed
+abort: pretxncommit.whitespace hook exited with status 1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a' &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'drop trailing whitespace and try again'</userinput>
+</screen>
+<!-- END ch09/hook.ws.simple -->
+
+
+      <para id="x_235">In this example, we introduce a simple <literal role="hook" moreinfo="none">pretxncommit</literal> hook that checks for
+	trailing whitespace.  This hook is short, but not very
+	helpful.  It exits with an error status if a change adds a
+	line with trailing whitespace to any file, but does not print
+	any information that might help us to identify the offending
+	file or line.  It also has the nice property of not paying
+	attention to unmodified lines; only lines that introduce new
+	trailing whitespace cause problems.
+      </para>
+
+      <!-- BEGIN ch09/check_whitespace.py.lst -->
+<programlisting format="linespecific">#!/usr/bin/env python
+#
+# save as .hg/check_whitespace.py and make executable
+
+import re
+
+def trailing_whitespace(difflines):
+    # 
+    linenum, header = 0, False
+
+    for line in difflines:
+        if header:
+            # remember the name of the file that this diff affects
+            m = re.match(r'(?:---|\+\+\+) ([^\t]+)', line)
+            if m and m.group(1) != '/dev/null':
+                filename = m.group(1).split('/', 1)[-1]
+            if line.startswith('+++ '):
+                header = False
+            continue
+        if line.startswith('diff '):
+            header = True
+            continue
+        # hunk header - save the line number
+        m = re.match(r'@@ -\d+,\d+ \+(\d+),', line)
+        if m:
+            linenum = int(m.group(1))
+            continue
+        # hunk body - check for an added line with trailing whitespace
+        m = re.match(r'\+.*\s$', line)
+        if m:
+            yield filename, linenum
+        if line and line[0] in ' +':
+            linenum += 1
+
+if __name__ == '__main__':
+    import os, sys
+    
+    added = 0
+    for filename, linenum in trailing_whitespace(os.popen('hg export tip')):
+        print &gt;&gt; sys.stderr, ('%s, line %d: trailing whitespace added' %
+                              (filename, linenum))
+        added += 1
+    if added:
+        # save the commit message so we don't need to retype it
+        os.system('hg tip --template "{desc}" &gt; .hg/commit.save')
+        print &gt;&gt; sys.stderr, 'commit message saved to .hg/commit.save'
+        sys.exit(1)</programlisting>
+<!-- END ch09/check_whitespace.py.lst -->
+
+
+      <para id="x_236">The above version is much more complex, but also more
+	useful.  It parses a unified diff to see if any lines add
+	trailing whitespace, and prints the name of the file and the
+	line number of each such occurrence.  Even better, if the
+	change adds trailing whitespace, this hook saves the commit
+	comment and prints the name of the save file before exiting
+	and telling Mercurial to roll the transaction back, so you can
+	use the <option role="hg-opt-commit">-l filename</option>
+	option to <command role="hg-cmd" moreinfo="none">hg commit</command> to reuse
+	the saved commit message once you've corrected the problem.
+      </para>
+
+      <!-- BEGIN ch09/hook.ws.better -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
+[hooks]
+pretxncommit.whitespace = .hg/check_whitespace.py
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' &gt;&gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'add new line with trailing whitespace'</userinput>
+a, line 2: trailing whitespace added
+commit message saved to .hg/commit.save
+transaction abort!
+rollback completed
+abort: pretxncommit.whitespace hook exited with status 1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">sed -i 's, *$,,' a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'trimmed trailing whitespace'</userinput>
+a, line 2: trailing whitespace added
+commit message saved to .hg/commit.save
+transaction abort!
+rollback completed
+abort: pretxncommit.whitespace hook exited with status 1
+</screen>
+<!-- END ch09/hook.ws.better -->
+
+
+      <para id="x_237">As a final aside, note in the example above the
+	use of <command moreinfo="none">sed</command>'s in-place editing feature to
+	get rid of trailing whitespace from a file.  This is concise
+	and useful enough that I will reproduce it here (using
+	<command moreinfo="none">perl</command> for good measure).</para>
+      <programlisting format="linespecific">perl -pi -e 's,\s+$,,' filename</programlisting>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Bundled hooks</title>
+
+    <para id="x_238">Mercurial ships with several bundled hooks.  You can find
+      them in the <filename class="directory" moreinfo="none">hgext</filename>
+      directory of a Mercurial source tree.  If you are using a
+      Mercurial binary package, the hooks will be located in the
+      <filename class="directory" moreinfo="none">hgext</filename> directory of
+      wherever your package installer put Mercurial.
+    </para>
+
+    <sect2>
+      <title><literal role="hg-ext" moreinfo="none">acl</literal>—access
+	control for parts of a repository</title>
+
+      <para id="x_239">The <literal role="hg-ext" moreinfo="none">acl</literal> extension lets
+	you control which remote users are allowed to push changesets
+	to a networked server.  You can protect any portion of a
+	repository (including the entire repo), so that a specific
+	remote user can push changes that do not affect the protected
+	portion.
+      </para>
+
+      <para id="x_23a">This extension implements access control based on the
+	identity of the user performing a push,
+	<emphasis>not</emphasis> on who committed the changesets
+	they're pushing.  It makes sense to use this hook only if you
+	have a locked-down server environment that authenticates
+	remote users, and you want to be sure that only specific users
+	are allowed to push changes to that server.
+      </para>
+
+      <sect3>
+	<title>Configuring the <literal role="hook" moreinfo="none">acl</literal>
+	  hook</title>
+
+	<para id="x_23b">In order to manage incoming changesets, the <literal role="hg-ext" moreinfo="none">acl</literal> hook must be used as a
+	  <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook.  This
+	  lets it see which files are modified by each incoming
+	  changeset, and roll back a group of changesets if they
+	  modify <quote>forbidden</quote> files.  Example:
+	</para>
+	<programlisting format="linespecific">[hooks]
+pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
+
+	<para id="x_23c">The <literal role="hg-ext" moreinfo="none">acl</literal> extension is
+	  configured using three sections.
+	</para>
+
+	<para id="x_23d">The <literal role="rc-acl" moreinfo="none">acl</literal> section has
+	  only one entry, <envar role="rc-item-acl">sources</envar>,
+	  which lists the sources of incoming changesets that the hook
+	  should pay attention to.  You don't normally need to
+	  configure this section.
+	</para>
+	<itemizedlist>
+	  <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
+	      Control incoming changesets that are arriving from a
+	      remote repository over http or ssh.  This is the default
+	      value of <envar role="rc-item-acl">sources</envar>, and
+	      usually the only setting you'll need for this
+	      configuration item.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
+	      Control incoming changesets that are arriving via a pull
+	      from a local repository.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
+	      Control incoming changesets that are arriving via a push
+	      from a local repository.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
+	      Control incoming changesets that are arriving from
+	      another repository via a bundle.
+	    </para>
+	  </listitem></itemizedlist>
+
+	<para id="x_242">The <literal role="rc-acl.allow" moreinfo="none">acl.allow</literal>
+	  section controls the users that are allowed to add
+	  changesets to the repository.  If this section is not
+	  present, all users that are not explicitly denied are
+	  allowed.  If this section is present, all users that are not
+	  explicitly allowed are denied (so an empty section means
+	  that all users are denied).
+	</para>
+
+	<para id="x_243">The <literal role="rc-acl.deny" moreinfo="none">acl.deny</literal>
+	  section determines which users are denied from adding
+	  changesets to the repository.  If this section is not
+	  present or is empty, no users are denied.
+	</para>
+
+	<para id="x_244">The syntaxes for the <literal role="rc-acl.allow" moreinfo="none">acl.allow</literal> and <literal role="rc-acl.deny" moreinfo="none">acl.deny</literal> sections are
+	  identical.  On the left of each entry is a glob pattern that
+	  matches files or directories, relative to the root of the
+	  repository; on the right, a user name.
+	</para>
+
+	<para id="x_245">In the following example, the user
+	  <literal moreinfo="none">docwriter</literal> can only push changes to the
+	  <filename class="directory" moreinfo="none">docs</filename> subtree of the
+	  repository, while <literal moreinfo="none">intern</literal> can push changes
+	  to any file or directory except <filename class="directory" moreinfo="none">source/sensitive</filename>.
+	</para>
+	<programlisting format="linespecific">[acl.allow]
+docs/** = docwriter
+[acl.deny]
+source/sensitive/** = intern</programlisting>
+
+      </sect3>
+      <sect3>
+	<title>Testing and troubleshooting</title>
+
+	<para id="x_246">If you want to test the <literal role="hg-ext" moreinfo="none">acl</literal> hook, run it with Mercurial's
+	  debugging output enabled.  Since you'll probably be running
+	  it on a server where it's not convenient (or sometimes
+	  possible) to pass in the <option role="hg-opt-global">--debug</option> option, don't forget
+	  that you can enable debugging output in your <filename role="special" moreinfo="none">~/.hgrc</filename>:
+	</para>
+	<programlisting format="linespecific">[ui]
+debug = true</programlisting>
+	<para id="x_247">With this enabled, the <literal role="hg-ext" moreinfo="none">acl</literal> hook will print enough
+	  information to let you figure out why it is allowing or
+	  forbidding pushes from specific users.
+	</para>
+
+      </sect3>    </sect2>
+
+    <sect2>
+      <title><literal role="hg-ext" moreinfo="none">bugzilla</literal>—integration with
+	Bugzilla</title>
+
+      <para id="x_248">The <literal role="hg-ext" moreinfo="none">bugzilla</literal> extension
+	adds a comment to a Bugzilla bug whenever it finds a reference
+	to that bug ID in a commit comment.  You can install this hook
+	on a shared server, so that any time a remote user pushes
+	changes to this server, the hook gets run.
+      </para>
+
+      <para id="x_249">It adds a comment to the bug that looks like this (you can
+	configure the contents of the comment—see below):
+      </para>
+      <programlisting format="linespecific">Changeset aad8b264143a, made by Joe User
+	&lt;joe.user@domain.com&gt; in the frobnitz repository, refers
+	to this bug. For complete details, see
+	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
+	Changeset description: Fix bug 10483 by guarding against some
+	NULL pointers</programlisting>
+      <para id="x_24a">The value of this hook is that it automates the process of
+	updating a bug any time a changeset refers to it.  If you
+	configure the hook properly, it makes it easy for people to
+	browse straight from a Bugzilla bug to a changeset that refers
+	to that bug.
+      </para>
+
+      <para id="x_24b">You can use the code in this hook as a starting point for
+	some more exotic Bugzilla integration recipes.  Here are a few
+	possibilities:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_24c">Require that every changeset pushed to the
+	    server have a valid bug ID in its commit comment.  In this
+	    case, you'd want to configure the hook as a <literal role="hook" moreinfo="none">pretxncommit</literal> hook.  This would
+	    allow the hook to reject changes that didn't contain bug
+	    IDs.
+	  </para>
+	</listitem>
+	<listitem><para id="x_24d">Allow incoming changesets to automatically
+	    modify the <emphasis>state</emphasis> of a bug, as well as
+	    simply adding a comment.  For example, the hook could
+	    recognise the string <quote>fixed bug 31337</quote> as
+	    indicating that it should update the state of bug 31337 to
+	    <quote>requires testing</quote>.
+	  </para>
+	</listitem></itemizedlist>
+
+      <sect3 id="sec:hook:bugzilla:config">
+	<title>Configuring the <literal role="hook" moreinfo="none">bugzilla</literal>
+	  hook</title>
+
+	<para id="x_24e">You should configure this hook in your server's
+	  <filename role="special" moreinfo="none">~/.hgrc</filename> as an <literal role="hook" moreinfo="none">incoming</literal> hook, for example as
+	  follows:
+	</para>
+	<programlisting format="linespecific">[hooks]
+incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
+
+	<para id="x_24f">Because of the specialised nature of this hook, and
+	  because Bugzilla was not written with this kind of
+	  integration in mind, configuring this hook is a somewhat
+	  involved process.
+	</para>
+
+	<para id="x_250">Before you begin, you must install the MySQL bindings
+	  for Python on the host(s) where you'll be running the hook.
+	  If this is not available as a binary package for your
+	  system, you can download it from
+	  <citation>web:mysql-python</citation>.
+	</para>
+
+	<para id="x_251">Configuration information for this hook lives in the
+	  <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal> section of
+	  your <filename role="special" moreinfo="none">~/.hgrc</filename>.
+	</para>
+	<itemizedlist>
+	  <listitem><para id="x_252"><envar role="rc-item-bugzilla">version</envar>: The version
+	      of Bugzilla installed on the server.  The database
+	      schema that Bugzilla uses changes occasionally, so this
+	      hook has to know exactly which schema to use.</para>
+	  </listitem>
+	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
+	      The hostname of the MySQL server that stores your
+	      Bugzilla data.  The database must be configured to allow
+	      connections from whatever host you are running the
+	      <literal role="hook" moreinfo="none">bugzilla</literal> hook on.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
+	      The username with which to connect to the MySQL server.
+	      The database must be configured to allow this user to
+	      connect from whatever host you are running the <literal role="hook" moreinfo="none">bugzilla</literal> hook on.  This user
+	      must be able to access and modify Bugzilla tables.  The
+	      default value of this item is <literal moreinfo="none">bugs</literal>,
+	      which is the standard name of the Bugzilla user in a
+	      MySQL database.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_255"><envar role="rc-item-bugzilla">password</envar>: The MySQL
+	      password for the user you configured above.  This is
+	      stored as plain text, so you should make sure that
+	      unauthorised users cannot read the <filename role="special" moreinfo="none">~/.hgrc</filename> file where you
+	      store this information.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
+	      The name of the Bugzilla database on the MySQL server.
+	      The default value of this item is
+	      <literal moreinfo="none">bugs</literal>, which is the standard name of
+	      the MySQL database where Bugzilla stores its data.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_257"><envar role="rc-item-bugzilla">notify</envar>: If you want
+	      Bugzilla to send out a notification email to subscribers
+	      after this hook has added a comment to a bug, you will
+	      need this hook to run a command whenever it updates the
+	      database.  The command to run depends on where you have
+	      installed Bugzilla, but it will typically look something
+	      like this, if you have Bugzilla installed in <filename class="directory" moreinfo="none">/var/www/html/bugzilla</filename>:
+	    </para>
+	    <programlisting format="linespecific">cd /var/www/html/bugzilla &amp;&amp;
+	      ./processmail %s nobody@nowhere.com</programlisting>
+	  </listitem>
+	  <listitem><para id="x_258">  The Bugzilla
+	      <literal moreinfo="none">processmail</literal> program expects to be
+	      given a bug ID (the hook replaces
+	      <quote><literal moreinfo="none">%s</literal></quote> with the bug ID)
+	      and an email address.  It also expects to be able to
+	      write to some files in the directory that it runs in.
+	      If Bugzilla and this hook are not installed on the same
+	      machine, you will need to find a way to run
+	      <literal moreinfo="none">processmail</literal> on the server where
+	      Bugzilla is installed.
+	    </para>
+	  </listitem></itemizedlist>
+
+      </sect3>
+      <sect3>
+	<title>Mapping committer names to Bugzilla user names</title>
+
+	<para id="x_259">By default, the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook tries to use the
+	  email address of a changeset's committer as the Bugzilla
+	  user name with which to update a bug.  If this does not suit
+	  your needs, you can map committer email addresses to
+	  Bugzilla user names using a <literal role="rc-usermap" moreinfo="none">usermap</literal> section.
+	</para>
+
+	<para id="x_25a">Each item in the <literal role="rc-usermap" moreinfo="none">usermap</literal> section contains an
+	  email address on the left, and a Bugzilla user name on the
+	  right.
+	</para>
+	<programlisting format="linespecific">[usermap]
+jane.user@example.com = jane</programlisting>
+	<para id="x_25b">You can either keep the <literal role="rc-usermap" moreinfo="none">usermap</literal> data in a normal
+	  <filename role="special" moreinfo="none">~/.hgrc</filename>, or tell the
+	  <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook to read the
+	  information from an external <filename moreinfo="none">usermap</filename>
+	  file.  In the latter case, you can store
+	  <filename moreinfo="none">usermap</filename> data by itself in (for example)
+	  a user-modifiable repository.  This makes it possible to let
+	  your users maintain their own <envar role="rc-item-bugzilla">usermap</envar> entries.  The main
+	  <filename role="special" moreinfo="none">~/.hgrc</filename> file might look
+	  like this:
+	</para>
+	<programlisting format="linespecific"># regular hgrc file refers to external usermap file
+[bugzilla]
+usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
+	<para id="x_25c">While the <filename moreinfo="none">usermap</filename> file that it
+	  refers to might look like this:
+	</para>
+	<programlisting format="linespecific"># bugzilla-usermap.conf - inside a hg repository
+[usermap] stephanie@example.com = steph</programlisting>
+
+      </sect3>
+      <sect3>
+	<title>Configuring the text that gets added to a bug</title>
+
+	<para id="x_25d">You can configure the text that this hook adds as a
+	  comment; you specify it in the form of a Mercurial template.
+	  Several <filename role="special" moreinfo="none">~/.hgrc</filename> entries
+	  (still in the <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal>
+	  section) control this behavior.
+	</para>
+	<itemizedlist>
+	  <listitem><para id="x_25e"><literal moreinfo="none">strip</literal>: The number of
+	      leading path elements to strip from a repository's path
+	      name to construct a partial path for a URL. For example,
+	      if the repositories on your server live under <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and you
+	      have a repository whose path is <filename class="directory" moreinfo="none">/home/hg/repos/app/tests</filename>,
+	      then setting <literal moreinfo="none">strip</literal> to
+	      <literal moreinfo="none">4</literal> will give a partial path of
+	      <filename class="directory" moreinfo="none">app/tests</filename>.  The
+	      hook will make this partial path available when
+	      expanding a template, as <literal moreinfo="none">webroot</literal>.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_25f"><literal moreinfo="none">template</literal>: The text of the
+	      template to use.  In addition to the usual
+	      changeset-related variables, this template can use
+	      <literal moreinfo="none">hgweb</literal> (the value of the
+	      <literal moreinfo="none">hgweb</literal> configuration item above) and
+	      <literal moreinfo="none">webroot</literal> (the path constructed using
+	      <literal moreinfo="none">strip</literal> above).
+	    </para>
+	  </listitem></itemizedlist>
+
+	<para id="x_260">In addition, you can add a <envar role="rc-item-web">baseurl</envar> item to the <literal role="rc-web" moreinfo="none">web</literal> section of your <filename role="special" moreinfo="none">~/.hgrc</filename>.  The <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook will make this
+	  available when expanding a template, as the base string to
+	  use when constructing a URL that will let users browse from
+	  a Bugzilla comment to view a changeset.  Example:
+	</para>
+	<programlisting format="linespecific">[web]
+baseurl = http://hg.domain.com/</programlisting>
+
+	<para id="x_261">Here is an example set of <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook config information.
+	</para>
+
+	<!-- BEGIN ch10/bugzilla-config.lst -->
+<programlisting format="linespecific">[bugzilla]
+host = bugzilla.example.com
+password = mypassword version = 2.16
+# server-side repos live in /home/hg/repos, so strip 4 leading
+# separators
+strip = 4
+hgweb = http://hg.example.com/
+usermap = /home/hg/repos/notify/bugzilla.conf
+template = Changeset {node|short}, made by {author} in the {webroot}
+  repo, refers to this bug.\n
+  For complete details, see
+  {hgweb}{webroot}?cmd=changeset;node={node|short}\n
+  Changeset description:\n
+  \t{desc|tabindent}</programlisting>
+<!-- END ch10/bugzilla-config.lst -->
+
+
+      </sect3>
+      <sect3>
+	<title>Testing and troubleshooting</title>
+
+	<para id="x_262">The most common problems with configuring the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook relate to running
+	  Bugzilla's <filename moreinfo="none">processmail</filename> script and
+	  mapping committer names to user names.
+	</para>
+
+	<para id="x_263">Recall from <xref linkend="sec:hook:bugzilla:config"/> above that the user
+	  that runs the Mercurial process on the server is also the
+	  one that will run the <filename moreinfo="none">processmail</filename>
+	  script.  The <filename moreinfo="none">processmail</filename> script
+	  sometimes causes Bugzilla to write to files in its
+	  configuration directory, and Bugzilla's configuration files
+	  are usually owned by the user that your web server runs
+	  under.
+	</para>
+
+	<para id="x_264">You can cause <filename moreinfo="none">processmail</filename> to be run
+	  with the suitable user's identity using the
+	  <command moreinfo="none">sudo</command> command.  Here is an example entry
+	  for a <filename moreinfo="none">sudoers</filename> file.
+	</para>
+	<programlisting format="linespecific">hg_user = (httpd_user)
+NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
+	<para id="x_265">This allows the <literal moreinfo="none">hg_user</literal> user to run a
+	  <filename moreinfo="none">processmail-wrapper</filename> program under the
+	  identity of <literal moreinfo="none">httpd_user</literal>.
+	</para>
+
+	<para id="x_266">This indirection through a wrapper script is necessary,
+	  because <filename moreinfo="none">processmail</filename> expects to be run
+	  with its current directory set to wherever you installed
+	  Bugzilla; you can't specify that kind of constraint in a
+	  <filename moreinfo="none">sudoers</filename> file.  The contents of the
+	  wrapper script are simple:
+	</para>
+	<programlisting format="linespecific">#!/bin/sh
+cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
+	<para id="x_267">It doesn't seem to matter what email address you pass to
+	  <filename moreinfo="none">processmail</filename>.
+	</para>
+
+	<para id="x_268">If your <literal role="rc-usermap" moreinfo="none">usermap</literal> is
+	  not set up correctly, users will see an error message from
+	  the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook when they
+	  push changes to the server.  The error message will look
+	  like this:
+	</para>
+	<programlisting format="linespecific">cannot find bugzilla user id for john.q.public@example.com</programlisting>
+	<para id="x_269">What this means is that the committer's address,
+	  <literal moreinfo="none">john.q.public@example.com</literal>, is not a valid
+	  Bugzilla user name, nor does it have an entry in your
+	  <literal role="rc-usermap" moreinfo="none">usermap</literal> that maps it to
+	  a valid Bugzilla user name.
+	</para>
+
+      </sect3>    </sect2>
+
+    <sect2>
+      <title><literal role="hg-ext" moreinfo="none">notify</literal>—send email
+	notifications</title>
+
+      <para id="x_26a">Although Mercurial's built-in web server provides RSS
+	feeds of changes in every repository, many people prefer to
+	receive change notifications via email.  The <literal role="hg-ext" moreinfo="none">notify</literal> hook lets you send out
+	notifications to a set of email addresses whenever changesets
+	arrive that those subscribers are interested in.
+      </para>
+
+      <para id="x_26b">As with the <literal role="hg-ext" moreinfo="none">bugzilla</literal>
+	hook, the <literal role="hg-ext" moreinfo="none">notify</literal> hook is
+	template-driven, so you can customise the contents of the
+	notification messages that it sends.
+      </para>
+
+      <para id="x_26c">By default, the <literal role="hg-ext" moreinfo="none">notify</literal>
+	hook includes a diff of every changeset that it sends out; you
+	can limit the size of the diff, or turn this feature off
+	entirely.  It is useful for letting subscribers review changes
+	immediately, rather than clicking to follow a URL.
+      </para>
+
+      <sect3>
+	<title>Configuring the <literal role="hg-ext" moreinfo="none">notify</literal>
+	  hook</title>
+
+	<para id="x_26d">You can set up the <literal role="hg-ext" moreinfo="none">notify</literal> hook to send one email
+	  message per incoming changeset, or one per incoming group of
+	  changesets (all those that arrived in a single pull or
+	  push).
+	</para>
+	<programlisting format="linespecific">[hooks]
+# send one email per group of changes
+changegroup.notify = python:hgext.notify.hook
+# send one email per change
+incoming.notify = python:hgext.notify.hook</programlisting>
+
+	<para id="x_26e">Configuration information for this hook lives in the
+	  <literal role="rc-notify" moreinfo="none">notify</literal> section of a
+	  <filename role="special" moreinfo="none">~/.hgrc</filename> file.
+	</para>
+	<itemizedlist>
+	  <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
+	      By default, this hook does not send out email at all;
+	      instead, it prints the message that it
+	      <emphasis>would</emphasis> send.  Set this item to
+	      <literal moreinfo="none">false</literal> to allow email to be sent. The
+	      reason that sending of email is turned off by default is
+	      that it takes several tries to configure this extension
+	      exactly as you would like, and it would be bad form to
+	      spam subscribers with a number of <quote>broken</quote>
+	      notifications while you debug your configuration.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
+	      The path to a configuration file that contains
+	      subscription information.  This is kept separate from
+	      the main <filename role="special" moreinfo="none">~/.hgrc</filename> so
+	      that you can maintain it in a repository of its own.
+	      People can then clone that repository, update their
+	      subscriptions, and push the changes back to your server.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
+	      The number of leading path separator characters to strip
+	      from a repository's path, when deciding whether a
+	      repository has subscribers.  For example, if the
+	      repositories on your server live in <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and
+	      <literal role="hg-ext" moreinfo="none">notify</literal> is considering a
+	      repository named <filename class="directory" moreinfo="none">/home/hg/repos/shared/test</filename>, 
+	      setting <envar role="rc-item-notify">strip</envar> to
+	      <literal moreinfo="none">4</literal> will cause <literal role="hg-ext" moreinfo="none">notify</literal> to trim the path it
+	      considers down to <filename class="directory" moreinfo="none">shared/test</filename>, and it will
+	      match subscribers against that.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_272"><envar role="rc-item-notify">template</envar>: The template
+	      text to use when sending messages.  This specifies both
+	      the contents of the message header and its body.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_273"><envar role="rc-item-notify">maxdiff</envar>: The maximum
+	      number of lines of diff data to append to the end of a
+	      message.  If a diff is longer than this, it is
+	      truncated.  By default, this is set to 300.  Set this to
+	      <literal moreinfo="none">0</literal> to omit diffs from notification
+	      emails.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_274"><envar role="rc-item-notify">sources</envar>: A list of
+	      sources of changesets to consider.  This lets you limit
+	      <literal role="hg-ext" moreinfo="none">notify</literal> to only sending
+	      out email about changes that remote users pushed into
+	      this repository via a server, for example.  See 
+	      <xref linkend="sec:hook:sources"/> for the sources you
+	      can specify here.
+	    </para>
+	  </listitem></itemizedlist>
+
+	<para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
+	  item in the <literal role="rc-web" moreinfo="none">web</literal> section,
+	  you can use it in a template; it will be available as
+	  <literal moreinfo="none">webroot</literal>.
+	</para>
+
+	<para id="x_276">Here is an example set of <literal role="hg-ext" moreinfo="none">notify</literal> configuration information.
+	</para>
+
+	<!-- BEGIN ch10/notify-config.lst -->
+<programlisting format="linespecific">[notify]
+# really send email
+test = false
+# subscriber data lives in the notify repo
+config = /home/hg/repos/notify/notify.conf
+# repos live in /home/hg/repos on server, so strip 4 "/" chars
+strip = 4
+template = X-Hg-Repo: {webroot}\n
+  Subject: {webroot}: {desc|firstline|strip}\n
+  From: {author}
+  \n\n
+  changeset {node|short} in {root}
+  \n\ndetails:
+  {baseurl}{webroot}?cmd=changeset;node={node|short}
+  description: {desc|tabindent|strip}
+
+[web]
+baseurl =
+http://hg.example.com/</programlisting>
+<!-- END ch10/notify-config.lst -->
+
+
+	<para id="x_277">This will produce a message that looks like the
+	  following:
+	</para>
+
+	<!-- BEGIN ch10/notify-config-mail.lst -->
+<programlisting format="linespecific">X-Hg-Repo: tests/slave
+Subject: tests/slave: Handle error case when slave has no buffers
+Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
+
+changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
+
+details:
+http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 
+
+description: Handle error case when slave has no buffers
+
+diffs (54 lines):
+diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
+--- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
++++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
+@@ -212,6 +212,15 @@ static __inline__
+void test_headers(void *h)
+[...snip...]</programlisting>
+<!-- END ch10/notify-config-mail.lst -->
+
+
+      </sect3>
+      <sect3>
+	<title>Testing and troubleshooting</title>
+
+	<para id="x_278">Do not forget that by default, the <literal role="hg-ext" moreinfo="none">notify</literal> extension <emphasis>will not
+	  send any mail</emphasis> until you explicitly configure it to do so,
+	  by setting <envar role="rc-item-notify">test</envar> to
+	  <literal moreinfo="none">false</literal>.  Until you do that, it simply
+	  prints the message it <emphasis>would</emphasis> send.
+	</para>
+
+      </sect3>
+    </sect2>
+  </sect1>
+  <sect1 id="sec:hook:ref">
+    <title>Information for writers of hooks</title>
+
+    <sect2>
+      <title>In-process hook execution</title>
+
+      <para id="x_279">An in-process hook is called with arguments of the
+	following form:
+      </para>
+      <programlisting format="linespecific">def myhook(ui, repo, **kwargs): pass</programlisting>
+      <para id="x_27a">The <literal moreinfo="none">ui</literal> parameter is a <literal role="py-mod-mercurial.ui" moreinfo="none">ui</literal> object. The
+	<literal moreinfo="none">repo</literal> parameter is a <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>
+	object.  The names and values of the
+	<literal moreinfo="none">**kwargs</literal> parameters depend on the hook
+	being invoked, with the following common features:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_27b">If a parameter is named
+	    <literal moreinfo="none">node</literal> or <literal moreinfo="none">parentN</literal>, it
+	    will contain a hexadecimal changeset ID. The empty string
+	    is used to represent <quote>null changeset ID</quote>
+	    instead of a string of zeroes.
+	  </para>
+	</listitem>
+	<listitem><para id="x_27c">If a parameter is named
+	    <literal moreinfo="none">url</literal>, it will contain the URL of a
+	    remote repository, if that can be determined.
+	  </para>
+	</listitem>
+	<listitem><para id="x_27d">Boolean-valued parameters are represented as
+	    Python <literal moreinfo="none">bool</literal> objects.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_27e">An in-process hook is called without a change to the
+	process's working directory (unlike external hooks, which are
+	run in the root of the repository).  It must not change the
+	process's working directory, or it will cause any calls it
+	makes into the Mercurial API to fail.
+      </para>
+
+      <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
+	is considered to have succeeded.  If it returns a boolean
+	<quote>true</quote> value or raises an exception, it is
+	considered to have failed.  A useful way to think of the
+	calling convention is <quote>tell me if you fail</quote>.
+      </para>
+
+      <para id="x_280">Note that changeset IDs are passed into Python hooks as
+	hexadecimal strings, not the binary hashes that Mercurial's
+	APIs normally use.  To convert a hash from hex to binary, use
+	the <literal moreinfo="none">bin</literal> function.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>External hook execution</title>
+
+      <para id="x_281">An external hook is passed to the shell of the user
+	running Mercurial. Features of that shell, such as variable
+	substitution and command redirection, are available.  The hook
+	is run in the root directory of the repository (unlike
+	in-process hooks, which are run in the same directory that
+	Mercurial was run in).
+      </para>
+
+      <para id="x_282">Hook parameters are passed to the hook as environment
+	variables.  Each environment variable's name is converted in
+	upper case and prefixed with the string
+	<quote><literal moreinfo="none">HG_</literal></quote>.  For example, if the
+	name of a parameter is <quote><literal moreinfo="none">node</literal></quote>,
+	the name of the environment variable representing that
+	parameter will be <quote><literal moreinfo="none">HG_NODE</literal></quote>.
+      </para>
+
+      <para id="x_283">A boolean parameter is represented as the string
+	<quote><literal moreinfo="none">1</literal></quote> for <quote>true</quote>,
+	<quote><literal moreinfo="none">0</literal></quote> for <quote>false</quote>.
+	If an environment variable is named <envar>HG_NODE</envar>,
+	<envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
+	contains a changeset ID represented as a hexadecimal string.
+	The empty string is used to represent <quote>null changeset
+	  ID</quote> instead of a string of zeroes.  If an environment
+	variable is named <envar>HG_URL</envar>, it will contain the
+	URL of a remote repository, if that can be determined.
+      </para>
+
+      <para id="x_284">If a hook exits with a status of zero, it is considered to
+	have succeeded.  If it exits with a non-zero status, it is
+	considered to have failed.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Finding out where changesets come from</title>
+
+      <para id="x_285">A hook that involves the transfer of changesets between a
+	local repository and another may be able to find out
+	information about the <quote>far side</quote>.  Mercurial
+	knows <emphasis>how</emphasis> changes are being transferred,
+	and in many cases <emphasis>where</emphasis> they are being
+	transferred to or from.
+      </para>
+
+      <sect3 id="sec:hook:sources">
+	<title>Sources of changesets</title>
+
+	<para id="x_286">Mercurial will tell a hook what means are, or were, used
+	  to transfer changesets between repositories.  This is
+	  provided by Mercurial in a Python parameter named
+	  <literal moreinfo="none">source</literal>, or an environment variable named
+	  <envar>HG_SOURCE</envar>.
+	</para>
+
+	<itemizedlist>
+	  <listitem><para id="x_287"><literal moreinfo="none">serve</literal>: Changesets are
+	      transferred to or from a remote repository over http or
+	      ssh.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_288"><literal moreinfo="none">pull</literal>: Changesets are
+	      being transferred via a pull from one repository into
+	      another.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_289"><literal moreinfo="none">push</literal>: Changesets are
+	      being transferred via a push from one repository into
+	      another.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_28a"><literal moreinfo="none">bundle</literal>: Changesets are
+	      being transferred to or from a bundle.
+	    </para>
+	  </listitem></itemizedlist>
+      </sect3>
+
+      <sect3 id="sec:hook:url">
+	<title>Where changes are going—remote repository
+	  URLs</title>
+
+	<para id="x_28b">When possible, Mercurial will tell a hook the location
+	  of the <quote>far side</quote> of an activity that transfers
+	  changeset data between repositories.  This is provided by
+	  Mercurial in a Python parameter named
+	  <literal moreinfo="none">url</literal>, or an environment variable named
+	  <envar>HG_URL</envar>.
+	</para>
+
+	<para id="x_28c">This information is not always known.  If a hook is
+	  invoked in a repository that is being served via http or
+	  ssh, Mercurial cannot tell where the remote repository is,
+	  but it may know where the client is connecting from.  In
+	  such cases, the URL will take one of the following forms:
+	</para>
+	<itemizedlist>
+	  <listitem><para id="x_28d"><literal moreinfo="none">remote:ssh:1.2.3.4</literal>—remote 
+	      ssh client, at the IP address
+	      <literal moreinfo="none">1.2.3.4</literal>.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_28e"><literal moreinfo="none">remote:http:1.2.3.4</literal>—remote 
+	      http client, at the IP address
+	      <literal moreinfo="none">1.2.3.4</literal>.  If the client is using SSL,
+	      this will be of the form
+	      <literal moreinfo="none">remote:https:1.2.3.4</literal>.
+	    </para>
+	  </listitem>
+	  <listitem><para id="x_28f">Empty—no information could be
+	      discovered about the remote client.
+	    </para>
+	  </listitem></itemizedlist>
+      </sect3>
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Hook reference</title>
+
+    <sect2 id="sec:hook:changegroup">
+      <title><literal role="hook" moreinfo="none">changegroup</literal>—after
+	remote changesets added</title>
+
+      <para id="x_290">This hook is run after a group of pre-existing changesets
+	has been added to the repository, for example via a <command role="hg-cmd" moreinfo="none">hg pull</command> or <command role="hg-cmd" moreinfo="none">hg
+	  unbundle</command>.  This hook is run once per operation
+	that added one or more changesets.  This is in contrast to the
+	<literal role="hook" moreinfo="none">incoming</literal> hook, which is run
+	once per changeset, regardless of whether the changesets
+	arrive in a group.
+      </para>
+
+      <para id="x_291">Some possible uses for this hook include kicking off an
+	automated build or test of the added changesets, updating a
+	bug database, or notifying subscribers that a repository
+	contains new changes.
+      </para>
+
+      <para id="x_292">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_293"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    changeset ID of the first changeset in the group that was
+	    added.  All changesets between this and
+	    <literal role="tag" moreinfo="none">tip</literal>, inclusive, were added by a single
+	    <command role="hg-cmd" moreinfo="none">hg pull</command>, <command role="hg-cmd" moreinfo="none">hg push</command> or <command role="hg-cmd" moreinfo="none">hg unbundle</command>.
+	  </para>
+	</listitem>
+	<listitem><para id="x_294"><literal moreinfo="none">source</literal>: A
+	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
+	  </para>
+	</listitem>
+	<listitem><para id="x_295"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_296">See also: <literal role="hook" moreinfo="none">incoming</literal> (<xref linkend="sec:hook:incoming"/>), <literal role="hook" moreinfo="none">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>), <literal role="hook" moreinfo="none">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:commit">
+      <title><literal role="hook" moreinfo="none">commit</literal>—after a new
+	changeset is created</title>
+
+      <para id="x_297">This hook is run after a new changeset has been created.
+      </para>
+
+      <para id="x_298">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_299"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    changeset ID of the newly committed changeset.
+	  </para>
+	</listitem>
+	<listitem><para id="x_29a"><literal moreinfo="none">parent1</literal>: A changeset ID.
+	    The changeset ID of the first parent of the newly
+	    committed changeset.
+	  </para>
+	</listitem>
+	<listitem><para id="x_29b"><literal moreinfo="none">parent2</literal>: A changeset ID.
+	    The changeset ID of the second parent of the newly
+	    committed changeset.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_29c">See also: <literal role="hook" moreinfo="none">precommit</literal> (<xref linkend="sec:hook:precommit"/>), <literal role="hook" moreinfo="none">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:incoming">
+      <title><literal role="hook" moreinfo="none">incoming</literal>—after one
+	remote changeset is added</title>
+
+      <para id="x_29d">This hook is run after a pre-existing changeset has been
+	added to the repository, for example via a <command role="hg-cmd" moreinfo="none">hg push</command>.  If a group of changesets
+	was added in a single operation, this hook is called once for
+	each added changeset.
+      </para>
+
+      <para id="x_29e">You can use this hook for the same purposes as
+	the <literal role="hook" moreinfo="none">changegroup</literal> hook (<xref linkend="sec:hook:changegroup"/>); it's simply more
+	convenient sometimes to run a hook once per group of
+	changesets, while other times it's handier once per changeset.
+      </para>
+
+      <para id="x_29f">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2a0"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    ID of the newly added changeset.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2a1"><literal moreinfo="none">source</literal>: A
+	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2a2"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2a3">See also: <literal role="hook" moreinfo="none">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>) <literal role="hook" moreinfo="none">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>), <literal role="hook" moreinfo="none">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:outgoing">
+      <title><literal role="hook" moreinfo="none">outgoing</literal>—after
+	changesets are propagated</title>
+
+      <para id="x_2a4">This hook is run after a group of changesets has been
+	propagated out of this repository, for example by a <command role="hg-cmd" moreinfo="none">hg push</command> or <command role="hg-cmd" moreinfo="none">hg
+	  bundle</command> command.
+      </para>
+
+      <para id="x_2a5">One possible use for this hook is to notify administrators
+	that changes have been pulled.
+      </para>
+
+      <para id="x_2a6">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2a7"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    changeset ID of the first changeset of the group that was
+	    sent.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2a8"><literal moreinfo="none">source</literal>: A string.  The
+	    source of the of the operation (see <xref linkend="sec:hook:sources"/>).  If a remote
+	    client pulled changes from this repository,
+	    <literal moreinfo="none">source</literal> will be
+	    <literal moreinfo="none">serve</literal>.  If the client that obtained
+	    changes from this repository was local,
+	    <literal moreinfo="none">source</literal> will be
+	    <literal moreinfo="none">bundle</literal>, <literal moreinfo="none">pull</literal>, or
+	    <literal moreinfo="none">push</literal>, depending on the operation the
+	    client performed.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2a9"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2aa">See also: <literal role="hook" moreinfo="none">preoutgoing</literal> (<xref linkend="sec:hook:preoutgoing"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:prechangegroup">
+      <title><literal role="hook" moreinfo="none">prechangegroup</literal>—before starting
+	to add remote changesets</title>
+
+      <para id="x_2ab">This controlling hook is run before Mercurial begins to
+	add a group of changesets from another repository.
+      </para>
+
+      <para id="x_2ac">This hook does not have any information about the
+	changesets to be added, because it is run before transmission
+	of those changesets is allowed to begin.  If this hook fails,
+	the changesets will not be transmitted.
+      </para>
+
+      <para id="x_2ad">One use for this hook is to prevent external changes from
+	being added to a repository.  For example, you could use this
+	to <quote>freeze</quote> a server-hosted branch temporarily or
+	permanently so that users cannot push to it, while still
+	allowing a local administrator to modify the repository.
+      </para>
+
+      <para id="x_2ae">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2af"><literal moreinfo="none">source</literal>: A string.  The
+	    source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2b0"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2b1">See also: <literal role="hook" moreinfo="none">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>), <literal role="hook" moreinfo="none">incoming</literal> (<xref linkend="sec:hook:incoming"/>), <literal role="hook" moreinfo="none">pretxnchangegroup</literal> (<xref linkend="sec:hook:pretxnchangegroup"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:precommit">
+      <title><literal role="hook" moreinfo="none">precommit</literal>—before
+	starting to commit a changeset</title>
+
+      <para id="x_2b2">This hook is run before Mercurial begins to commit a new
+	changeset. It is run before Mercurial has any of the metadata
+	for the commit, such as the files to be committed, the commit
+	message, or the commit date.
+      </para>
+
+      <para id="x_2b3">One use for this hook is to disable the ability to commit
+	new changesets, while still allowing incoming changesets.
+	Another is to run a build or test, and only allow the commit
+	to begin if the build or test succeeds.
+      </para>
+
+      <para id="x_2b4">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2b5"><literal moreinfo="none">parent1</literal>: A changeset ID.
+	    The changeset ID of the first parent of the working
+	    directory.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2b6"><literal moreinfo="none">parent2</literal>: A changeset ID.
+	    The changeset ID of the second parent of the working
+	    directory.
+	  </para>
+	</listitem></itemizedlist>
+      <para id="x_2b7">If the commit proceeds, the parents of the working
+	directory will become the parents of the new changeset.
+      </para>
+
+      <para id="x_2b8">See also: <literal role="hook" moreinfo="none">commit</literal>
+	(<xref linkend="sec:hook:commit"/>), <literal role="hook" moreinfo="none">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:preoutgoing">
+      <title><literal role="hook" moreinfo="none">preoutgoing</literal>—before
+	starting to propagate changesets</title>
+
+      <para id="x_2b9">This hook is invoked before Mercurial knows the identities
+	of the changesets to be transmitted.
+      </para>
+
+      <para id="x_2ba">One use for this hook is to prevent changes from being
+	transmitted to another repository.
+      </para>
+
+      <para id="x_2bb">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2bc"><literal moreinfo="none">source</literal>: A
+	    string.  The source of the operation that is attempting to
+	    obtain changes from this repository (see <xref linkend="sec:hook:sources"/>).  See the documentation
+	    for the <literal moreinfo="none">source</literal> parameter to the
+	    <literal role="hook" moreinfo="none">outgoing</literal> hook, in
+	    <xref linkend="sec:hook:outgoing"/>, for possible values
+	    of this parameter.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2bd"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2be">See also: <literal role="hook" moreinfo="none">outgoing</literal> (<xref linkend="sec:hook:outgoing"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:pretag">
+      <title><literal role="hook" moreinfo="none">pretag</literal>—before
+	tagging a changeset</title>
+
+      <para id="x_2bf">This controlling hook is run before a tag is created.  If
+	the hook succeeds, creation of the tag proceeds.  If the hook
+	fails, the tag is not created.
+      </para>
+
+      <para id="x_2c0">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2c1"><literal moreinfo="none">local</literal>: A boolean.  Whether
+	    the tag is local to this repository instance (i.e. stored
+	    in <filename role="special" moreinfo="none">.hg/localtags</filename>) or
+	    managed by Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
+	  </para>
+	</listitem>
+	<listitem><para id="x_2c2"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    ID of the changeset to be tagged.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2c3"><literal moreinfo="none">tag</literal>: A string.  The name of
+	    the tag to be created.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2c4">If the tag to be created is
+	revision-controlled, the <literal role="hook" moreinfo="none">precommit</literal> and <literal role="hook" moreinfo="none">pretxncommit</literal> hooks (<xref linkend="sec:hook:commit"/> and <xref linkend="sec:hook:pretxncommit"/>) will also be run.
+      </para>
+
+      <para id="x_2c5">See also: <literal role="hook" moreinfo="none">tag</literal>
+	(<xref linkend="sec:hook:tag"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:pretxnchangegroup">
+      <title><literal role="hook" moreinfo="none">pretxnchangegroup</literal>—before
+	completing addition of remote changesets</title>
+
+      <para id="x_2c6">This controlling hook is run before a
+	transaction—that manages the addition of a group of new
+	changesets from outside the repository—completes.  If
+	the hook succeeds, the transaction completes, and all of the
+	changesets become permanent within this repository.  If the
+	hook fails, the transaction is rolled back, and the data for
+	the changesets is erased.
+      </para>
+
+      <para id="x_2c7">This hook can access the metadata associated with the
+	almost-added changesets, but it should not do anything
+	permanent with this data. It must also not modify the working
+	directory.
+      </para>
+
+      <para id="x_2c8">While this hook is running, if other Mercurial processes
+	access this repository, they will be able to see the
+	almost-added changesets as if they are permanent.  This may
+	lead to race conditions if you do not take steps to avoid
+	them.
+      </para>
+
+      <para id="x_2c9">This hook can be used to automatically vet a group of
+	changesets.  If the hook fails, all of the changesets are
+	<quote>rejected</quote> when the transaction rolls back.
+      </para>
+
+      <para id="x_2ca">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2cb"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    changeset ID of the first changeset in the group that was
+	    added.  All changesets between this and
+	    <literal role="tag" moreinfo="none">tip</literal>,
+	    inclusive, were added by a single <command role="hg-cmd" moreinfo="none">hg pull</command>, <command role="hg-cmd" moreinfo="none">hg push</command> or <command role="hg-cmd" moreinfo="none">hg unbundle</command>.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2cc"><literal moreinfo="none">source</literal>: A
+	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2cd"><literal moreinfo="none">url</literal>: A URL.  The
+	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2ce">See also: <literal role="hook" moreinfo="none">changegroup</literal> (<xref linkend="sec:hook:changegroup"/>), <literal role="hook" moreinfo="none">incoming</literal> (<xref linkend="sec:hook:incoming"/>), <literal role="hook" moreinfo="none">prechangegroup</literal> (<xref linkend="sec:hook:prechangegroup"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:pretxncommit">
+      <title><literal role="hook" moreinfo="none">pretxncommit</literal>—before
+	completing commit of new changeset</title>
+
+      <para id="x_2cf">This controlling hook is run before a
+	transaction—that manages a new commit—completes.
+	If the hook succeeds, the transaction completes and the
+	changeset becomes permanent within this repository.  If the
+	hook fails, the transaction is rolled back, and the commit
+	data is erased.
+      </para>
+
+      <para id="x_2d0">This hook can access the metadata associated with the
+	almost-new changeset, but it should not do anything permanent
+	with this data.  It must also not modify the working
+	directory.
+      </para>
+
+      <para id="x_2d1">While this hook is running, if other Mercurial processes
+	access this repository, they will be able to see the
+	almost-new changeset as if it is permanent.  This may lead to
+	race conditions if you do not take steps to avoid them.
+      </para>
+
+      <para id="x_2d2">Parameters to this hook:</para>
+
+      <itemizedlist>
+	<listitem><para id="x_2d3"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    changeset ID of the newly committed changeset.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2d4"><literal moreinfo="none">parent1</literal>: A changeset ID.
+	    The changeset ID of the first parent of the newly
+	    committed changeset.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2d5"><literal moreinfo="none">parent2</literal>: A changeset ID.
+	    The changeset ID of the second parent of the newly
+	    committed changeset.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2d6">See also: <literal role="hook" moreinfo="none">precommit</literal> (<xref linkend="sec:hook:precommit"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:preupdate">
+      <title><literal role="hook" moreinfo="none">preupdate</literal>—before
+	updating or merging working directory</title>
+
+      <para id="x_2d7">This controlling hook is run before an update
+	or merge of the working directory begins.  It is run only if
+	Mercurial's normal pre-update checks determine that the update
+	or merge can proceed.  If the hook succeeds, the update or
+	merge may proceed; if it fails, the update or merge does not
+	start.
+      </para>
+
+      <para id="x_2d8">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2d9"><literal moreinfo="none">parent1</literal>: A
+	    changeset ID. The ID of the parent that the working
+	    directory is to be updated to.  If the working directory
+	    is being merged, it will not change this parent.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2da"><literal moreinfo="none">parent2</literal>: A
+	    changeset ID. Only set if the working directory is being
+	    merged.  The ID of the revision that the working directory
+	    is being merged with.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2db">See also: <literal role="hook" moreinfo="none">update</literal>
+	(<xref linkend="sec:hook:update"/>)</para>
+    </sect2>
+
+    <sect2 id="sec:hook:tag">
+      <title><literal role="hook" moreinfo="none">tag</literal>—after tagging a
+	changeset</title>
+
+      <para id="x_2dc">This hook is run after a tag has been created.
+      </para>
+
+      <para id="x_2dd">Parameters to this hook:
+      </para>
+      <itemizedlist>
+	<listitem><para id="x_2de"><literal moreinfo="none">local</literal>: A boolean.  Whether
+	    the new tag is local to this repository instance (i.e.
+	    stored in <filename role="special" moreinfo="none">.hg/localtags</filename>) or managed by
+	    Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
+	  </para>
+	</listitem>
+	<listitem><para id="x_2df"><literal moreinfo="none">node</literal>: A changeset ID.  The
+	    ID of the changeset that was tagged.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2e0"><literal moreinfo="none">tag</literal>: A string.  The name of
+	    the tag that was created.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2e1">If the created tag is revision-controlled, the <literal role="hook" moreinfo="none">commit</literal> hook (section <xref linkend="sec:hook:commit"/>) is run before this hook.
+      </para>
+
+      <para id="x_2e2">See also: <literal role="hook" moreinfo="none">pretag</literal>
+	(<xref linkend="sec:hook:pretag"/>)
+      </para>
+    </sect2>
+
+    <sect2 id="sec:hook:update">
+      <title><literal role="hook" moreinfo="none">update</literal>—after
+	updating or merging working directory</title>
+
+      <para id="x_2e3">This hook is run after an update or merge of the working
+	directory completes.  Since a merge can fail (if the external
+	<command moreinfo="none">hgmerge</command> command fails to resolve conflicts
+	in a file), this hook communicates whether the update or merge
+	completed cleanly.
+      </para>
+
+      <itemizedlist>
+	<listitem><para id="x_2e4"><literal moreinfo="none">error</literal>: A boolean.
+	    Indicates whether the update or merge completed
+	    successfully.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2e5"><literal moreinfo="none">parent1</literal>: A changeset ID.
+	    The ID of the parent that the working directory was
+	    updated to.  If the working directory was merged, it will
+	    not have changed this parent.
+	  </para>
+	</listitem>
+	<listitem><para id="x_2e6"><literal moreinfo="none">parent2</literal>: A changeset ID.
+	    Only set if the working directory was merged.  The ID of
+	    the revision that the working directory was merged with.
+	  </para>
+	</listitem></itemizedlist>
+
+      <para id="x_2e7">See also: <literal role="hook" moreinfo="none">preupdate</literal>
+	(<xref linkend="sec:hook:preupdate"/>)
+      </para>
+
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch11 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:template">
+  <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
+  <title>Customizing the output of Mercurial</title>
+
+  <para id="x_578">Mercurial provides a powerful mechanism to let you control how
+    it displays information.  The mechanism is based on templates.
+    You can use templates to generate specific output for a single
+    command, or to customize the entire appearance of the built-in web
+    interface.</para>
+
+  <sect1 id="sec:style">
+    <title>Using precanned output styles</title>
+
+    <para id="x_579">Packaged with Mercurial are some output styles that you can
+      use immediately.  A style is simply a precanned template that
+      someone wrote and installed somewhere that Mercurial can
+      find.</para>
+
+    <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
+      review its normal output.</para>
+
+    <!-- BEGIN template.simple.normal -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
+changeset:   1:e3d2468ca47c
+tag:         mytag
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:17 2009 +0000
+summary:     added line to end of &lt;&lt;hello&gt;&gt; file.
+
+</screen>
+<!-- END template.simple.normal -->
+
+
+    <para id="x_57b">This is somewhat informative, but it takes up a lot of
+      space—five lines of output per changeset.  The
+      <literal moreinfo="none">compact</literal> style reduces this to three lines,
+      presented in a sparse manner.</para>
+
+    <!-- BEGIN template.simple.compact -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
+3[tip]   d3cc7424d32c   2009-08-16 14:05 +0000   bos
+  Added tag v0.1 for changeset a5dd5392119b
+
+2[v0.1]   a5dd5392119b   2009-08-16 14:05 +0000   bos
+  Added tag mytag for changeset e3d2468ca47c
+
+1[mytag]   e3d2468ca47c   2009-08-16 14:05 +0000   bos
+  added line to end of &lt;&lt;hello&gt;&gt; file.
+
+0   1cf727e9fc61   2009-08-16 14:05 +0000   bos
+  added hello
+
+</screen>
+<!-- END template.simple.compact -->
+
+
+    <para id="x_57c">The <literal moreinfo="none">changelog</literal> style hints at the
+      expressive power of Mercurial's templating engine.  This style
+      attempts to follow the GNU Project's changelog
+      guidelines<citation>web:changelog</citation>.</para>
+
+    <!-- BEGIN template.simple.changelog -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style changelog</userinput>
+2009-08-16  Bryan O'Sullivan  &lt;bos@serpentine.com&gt;
+
+	* .hgtags:
+	Added tag v0.1 for changeset a5dd5392119b
+	[d3cc7424d32c] [tip]
+
+	* .hgtags:
+	Added tag mytag for changeset e3d2468ca47c
+	[a5dd5392119b] [v0.1]
+
+	* goodbye, hello:
+	added line to end of &lt;&lt;hello&gt;&gt; file.
+
+	in addition, added a file with the helpful name (at least i hope
+	that some might consider it so) of goodbye.
+	[e3d2468ca47c] [mytag]
+
+	* hello:
+	added hello
+	[1cf727e9fc61]
+
+</screen>
+<!-- END template.simple.changelog -->
+
+
+    <para id="x_57d">You will not be shocked to learn that Mercurial's default
+      output style is named <literal moreinfo="none">default</literal>.</para>
+
+    <sect2>
+      <title>Setting a default style</title>
+
+      <para id="x_57e">You can modify the output style that Mercurial will use
+	for every command by editing your <filename role="special" moreinfo="none">~/.hgrc</filename> file, naming the style
+	you would prefer to use.</para>
+
+      <programlisting format="linespecific">[ui]
+style = compact</programlisting>
+
+      <para id="x_57f">If you write a style of your own, you can use it by either
+	providing the path to your style file, or copying your style
+	file into a location where Mercurial can find it (typically
+	the <literal moreinfo="none">templates</literal> subdirectory of your
+	Mercurial install directory).</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Commands that support styles and templates</title>
+
+    <para id="x_580">All of Mercurial's
+      <quote><literal moreinfo="none">log</literal>-like</quote> commands let you use
+      styles and templates: <command role="hg-cmd" moreinfo="none">hg
+	incoming</command>, <command role="hg-cmd" moreinfo="none">hg log</command>,
+      <command role="hg-cmd" moreinfo="none">hg outgoing</command>, and <command role="hg-cmd" moreinfo="none">hg tip</command>.</para>
+
+    <para id="x_581">As I write this manual, these are so far the only commands
+      that support styles and templates.  Since these are the most
+      important commands that need customizable output, there has been
+      little pressure from the Mercurial user community to add style
+      and template support to other commands.</para>
+  </sect1>
+
+  <sect1>
+    <title>The basics of templating</title>
+
+    <para id="x_582">At its simplest, a Mercurial template is a piece of text.
+      Some of the text never changes, while other parts are
+      <emphasis>expanded</emphasis>, or replaced with new text, when
+      necessary.</para>
+
+    <para id="x_583">Before we continue, let's look again at a simple example of
+      Mercurial's normal output.</para>
+
+    <!-- BEGIN template.simple.normal -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
+changeset:   1:e3d2468ca47c
+tag:         mytag
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:17 2009 +0000
+summary:     added line to end of &lt;&lt;hello&gt;&gt; file.
+
+</screen>
+<!-- END template.simple.normal -->
+
+
+    <para id="x_584">Now, let's run the same command, but using a template to
+      change its output.</para>
+
+    <!-- BEGIN template.simple.simplest -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'i saw a changeset\n'</userinput>
+i saw a changeset
+</screen>
+<!-- END template.simple.simplest -->
+
+
+    <para id="x_585">The example above illustrates the simplest possible
+      template; it's just a piece of static text, printed once for
+      each changeset.  The <option role="hg-opt-log">--template</option> option to the <command role="hg-cmd" moreinfo="none">hg log</command> command tells Mercurial to use
+      the given text as the template when printing each
+      changeset.</para>
+
+    <para id="x_586">Notice that the template string above ends with the text
+      <quote><literal moreinfo="none">\n</literal></quote>.  This is an
+      <emphasis>escape sequence</emphasis>, telling Mercurial to print
+      a newline at the end of each template item.  If you omit this
+      newline, Mercurial will run each piece of output together.  See
+      <xref linkend="sec:template:escape"/> for more details
+      of escape sequences.</para>
+
+    <para id="x_587">A template that prints a fixed string of text all the time
+      isn't very useful; let's try something a bit more
+      complex.</para>
+
+    <!-- BEGIN template.simple.simplesub -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --template 'i saw a changeset: {desc}\n'</userinput>
+i saw a changeset: Added tag v0.1 for changeset a5dd5392119b
+i saw a changeset: Added tag mytag for changeset e3d2468ca47c
+i saw a changeset: added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
+i saw a changeset: added hello
+</screen>
+<!-- END template.simple.simplesub -->
+
+
+    <para id="x_588">As you can see, the string
+      <quote><literal moreinfo="none">{desc}</literal></quote> in the template has
+      been replaced in the output with the description of each
+      changeset.  Every time Mercurial finds text enclosed in curly
+      braces (<quote><literal moreinfo="none">{</literal></quote> and
+      <quote><literal moreinfo="none">}</literal></quote>), it will try to replace the
+      braces and text with the expansion of whatever is inside.  To
+      print a literal curly brace, you must escape it, as described in
+      <xref linkend="sec:template:escape"/>.</para>
+  </sect1>
+
+  <sect1 id="sec:template:keyword">
+    <title>Common template keywords</title>
+
+    <para id="x_589">You can start writing simple templates immediately using the
+      keywords below.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_58a"><literal role="template-keyword" moreinfo="none">author</literal>: String.  The
+	  unmodified author of the changeset.</para>
+      </listitem>
+      <listitem><para id="x_58b"><literal role="template-keyword" moreinfo="none">branches</literal>: String.  The
+	  name of the branch on which the changeset was committed.
+	  Will be empty if the branch name was
+	  <literal moreinfo="none">default</literal>.</para>
+      </listitem>
+      <listitem><para id="x_58c"><literal role="template-keyword" moreinfo="none">date</literal>:
+	  Date information.  The date when the changeset was
+	  committed.  This is <emphasis>not</emphasis> human-readable;
+	  you must pass it through a filter that will render it
+	  appropriately.  See <xref linkend="sec:template:filter"/> for more information
+	  on filters. The date is expressed as a pair of numbers.  The
+	  first number is a Unix UTC timestamp (seconds since January
+	  1, 1970); the second is the offset of the committer's
+	  timezone from UTC, in seconds.</para>
+      </listitem>
+      <listitem><para id="x_58d"><literal role="template-keyword" moreinfo="none">desc</literal>:
+	  String.  The text of the changeset description.</para>
+      </listitem>
+      <listitem><para id="x_58e"><literal role="template-keyword" moreinfo="none">files</literal>: List of strings.
+	  All files modified, added, or removed by this
+	  changeset.</para>
+      </listitem>
+      <listitem><para id="x_58f"><literal role="template-keyword" moreinfo="none">file_adds</literal>: List of
+	  strings.  Files added by this changeset.</para>
+      </listitem>
+      <listitem><para id="x_590"><literal role="template-keyword" moreinfo="none">file_dels</literal>: List of
+	  strings.  Files removed by this changeset.</para>
+      </listitem>
+      <listitem><para id="x_591"><literal role="template-keyword" moreinfo="none">node</literal>:
+	  String.  The changeset identification hash, as a
+	  40-character hexadecimal string.</para>
+      </listitem>
+      <listitem><para id="x_592"><literal role="template-keyword" moreinfo="none">parents</literal>: List of
+	  strings.  The parents of the changeset.</para>
+      </listitem>
+      <listitem><para id="x_593"><literal role="template-keyword" moreinfo="none">rev</literal>:
+	  Integer.  The repository-local changeset revision
+	  number.</para>
+      </listitem>
+      <listitem><para id="x_594"><literal role="template-keyword" moreinfo="none">tags</literal>:
+	  List of strings.  Any tags associated with the
+	  changeset.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_595">A few simple experiments will show us what to expect when we
+      use these keywords; you can see the results below.</para>
+
+    <!-- BEGIN template.simple.keywords -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'author: {author}\n'</userinput>
+author: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'desc:\n{desc}\n'</userinput>
+desc:
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'files: {files}\n'</userinput>
+files: goodbye hello
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_adds: {file_adds}\n'</userinput>
+file_adds: goodbye
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_dels: {file_dels}\n'</userinput>
+file_dels: 
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'node: {node}\n'</userinput>
+node: e3d2468ca47c10bdfbbb41b367a0c84509862197
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'parents: {parents}\n'</userinput>
+parents: 
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'rev: {rev}\n'</userinput>
+rev: 1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'tags: {tags}\n'</userinput>
+tags: mytag
+</screen>
+<!-- END template.simple.keywords -->
+
+
+    <para id="x_596">As we noted above, the date keyword does not produce
+      human-readable output, so we must treat it specially.  This
+      involves using a <emphasis>filter</emphasis>, about which more
+      in <xref linkend="sec:template:filter"/>.</para>
+
+    <!-- BEGIN template.simple.datekeyword -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date}\n'</userinput>
+date: 1250431517.00
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date|isodate}\n'</userinput>
+date: 2009-08-16 14:05 +0000
+</screen>
+<!-- END template.simple.datekeyword -->
+
+  </sect1>
+
+  <sect1 id="sec:template:escape">
+    <title>Escape sequences</title>
+
+    <para id="x_597">Mercurial's templating engine recognises the most commonly
+      used escape sequences in strings.  When it sees a backslash
+      (<quote><literal moreinfo="none">\</literal></quote>) character, it looks at the
+      following character and substitutes the two characters with a
+      single replacement, as described below.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_598"><literal moreinfo="none">\</literal>:
+	  Backslash, <quote><literal moreinfo="none">\</literal></quote>, ASCII
+	  134.</para>
+      </listitem>
+      <listitem><para id="x_599"><literal moreinfo="none">\n</literal>: Newline,
+	  ASCII 12.</para>
+      </listitem>
+      <listitem><para id="x_59a"><literal moreinfo="none">\r</literal>: Carriage
+	  return, ASCII 15.</para>
+      </listitem>
+      <listitem><para id="x_59b"><literal moreinfo="none">\t</literal>: Tab, ASCII
+	  11.</para>
+      </listitem>
+      <listitem><para id="x_59c"><literal moreinfo="none">\v</literal>: Vertical
+	  tab, ASCII 13.</para>
+      </listitem>
+      <listitem><para id="x_59d"><literal moreinfo="none">\{</literal>: Open curly
+	  brace, <quote><literal moreinfo="none">{</literal></quote>, ASCII
+	  173.</para>
+      </listitem>
+      <listitem><para id="x_59e"><literal moreinfo="none">\}</literal>: Close curly
+	  brace, <quote><literal moreinfo="none">}</literal></quote>, ASCII
+	  175.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_59f">As indicated above, if you want the expansion of a template
+      to contain a literal <quote><literal moreinfo="none">\</literal></quote>,
+      <quote><literal moreinfo="none">{</literal></quote>, or
+      <quote><literal moreinfo="none">{</literal></quote> character, you must escape
+      it.</para>
+  </sect1>
+
+  <sect1 id="sec:template:filter">
+    <title>Filtering keywords to change their results</title>
+
+    <para id="x_5a0">Some of the results of template expansion are not
+      immediately easy to use.  Mercurial lets you specify an optional
+      chain of <emphasis>filters</emphasis> to modify the result of
+      expanding a keyword.  You have already seen a common filter,
+      <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>, in
+      action above, to make a date readable.</para>
+
+    <para id="x_5a1">Below is a list of the most commonly used filters that
+      Mercurial supports.  While some filters can be applied to any
+      text, others can only be used in specific circumstances.  The
+      name of each filter is followed first by an indication of where
+      it can be used, then a description of its effect.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_5a2"><literal role="template-filter" moreinfo="none">addbreaks</literal>: Any text. Add
+	  an XHTML <quote><literal moreinfo="none">&lt;br/&gt;</literal></quote> tag
+	  before the end of every line except the last.  For example,
+	  <quote><literal moreinfo="none">foo\nbar</literal></quote> becomes
+	  <quote><literal moreinfo="none">foo&lt;br/&gt;\nbar</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a3"><literal role="template-kw-filt-date" moreinfo="none">age</literal>: <literal role="template-keyword" moreinfo="none">date</literal> keyword.  Render
+	  the age of the date, relative to the current time.  Yields a
+	  string like <quote><literal moreinfo="none">10
+	      minutes</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a4"><literal role="template-filter" moreinfo="none">basename</literal>: Any text, but
+	  most useful for the <literal role="template-keyword" moreinfo="none">files</literal> keyword and its
+	  relatives.  Treat the text as a path, and return the
+	  basename. For example,
+	  <quote><literal moreinfo="none">foo/bar/baz</literal></quote> becomes
+	  <quote><literal moreinfo="none">baz</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a5"><literal role="template-kw-filt-date" moreinfo="none">date</literal>: <literal role="template-keyword" moreinfo="none">date</literal> keyword.  Render a
+	  date in a similar format to the Unix <literal role="template-keyword" moreinfo="none">date</literal> command, but with
+	  timezone included.  Yields a string like <quote><literal moreinfo="none">Mon
+	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a6"><literal role="template-kw-filt-author" moreinfo="none">domain</literal>: Any text,
+	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Finds
+	  the first string that looks like an email address, and
+	  extract just the domain component.  For example,
+	  <quote><literal moreinfo="none">Bryan O'Sullivan
+	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
+	  <quote><literal moreinfo="none">serpentine.com</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a7"><literal role="template-kw-filt-author" moreinfo="none">email</literal>: Any text,
+	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Extract
+	  the first string that looks like an email address.  For
+	  example, <quote><literal moreinfo="none">Bryan O'Sullivan
+	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
+	  <quote><literal moreinfo="none">bos@serpentine.com</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5a8"><literal role="template-filter" moreinfo="none">escape</literal>: Any text.
+	  Replace the special XML/XHTML characters
+	  <quote><literal moreinfo="none">&amp;</literal></quote>,
+	  <quote><literal moreinfo="none">&lt;</literal></quote> and
+	  <quote><literal moreinfo="none">&gt;</literal></quote> with XML
+	  entities.</para>
+      </listitem>
+      <listitem><para id="x_5a9"><literal role="template-filter" moreinfo="none">fill68</literal>: Any text.  Wrap
+	  the text to fit in 68 columns.  This is useful before you
+	  pass text through the <literal role="template-filter" moreinfo="none">tabindent</literal> filter, and
+	  still want it to fit in an 80-column fixed-font
+	  window.</para>
+      </listitem>
+      <listitem><para id="x_5aa"><literal role="template-filter" moreinfo="none">fill76</literal>: Any text.  Wrap
+	  the text to fit in 76 columns.</para>
+      </listitem>
+      <listitem><para id="x_5ab"><literal role="template-filter" moreinfo="none">firstline</literal>: Any text.
+	  Yield the first line of text, without any trailing
+	  newlines.</para>
+      </listitem>
+      <listitem><para id="x_5ac"><literal role="template-kw-filt-date" moreinfo="none">hgdate</literal>: <literal role="template-keyword" moreinfo="none">date</literal> keyword.  Render
+	  the date as a pair of readable numbers.  Yields a string
+	  like <quote><literal moreinfo="none">1157407993
+	      25200</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5ad"><literal role="template-kw-filt-date" moreinfo="none">isodate</literal>: <literal role="template-keyword" moreinfo="none">date</literal> keyword.  Render
+	  the date as a text string in ISO 8601 format.  Yields a
+	  string like <quote><literal moreinfo="none">2006-09-04 15:13:13
+	      -0700</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5ae"><literal role="template-filter" moreinfo="none">obfuscate</literal>: Any text, but
+	  most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Yield
+	  the input text rendered as a sequence of XML entities.  This
+	  helps to defeat some particularly stupid screen-scraping
+	  email harvesting spambots.</para>
+      </listitem>
+      <listitem><para id="x_5af"><literal role="template-kw-filt-author" moreinfo="none">person</literal>: Any text,
+	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Yield
+	  the text before an email address. For example,
+	  <quote><literal moreinfo="none">Bryan O'Sullivan
+	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
+	  <quote><literal moreinfo="none">Bryan O'Sullivan</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5b0"><literal role="template-kw-filt-date" moreinfo="none">rfc822date</literal>:
+	  <literal role="template-keyword" moreinfo="none">date</literal> keyword.
+	  Render a date using the same format used in email headers.
+	  Yields a string like <quote><literal moreinfo="none">Mon, 04 Sep 2006
+	      15:13:13 -0700</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5b1"><literal role="template-kw-filt-node" moreinfo="none">short</literal>: Changeset
+	  hash.  Yield the short form of a changeset hash, i.e. a
+	  12-character hexadecimal string.</para>
+      </listitem>
+      <listitem><para id="x_5b2"><literal role="template-kw-filt-date" moreinfo="none">shortdate</literal>: <literal role="template-keyword" moreinfo="none">date</literal> keyword.  Render
+	  the year, month, and day of the date.  Yields a string like
+	  <quote><literal moreinfo="none">2006-09-04</literal></quote>.</para>
+      </listitem>
+      <listitem><para id="x_5b3"><literal role="template-filter" moreinfo="none">strip</literal>:
+	  Any text.  Strip all leading and trailing whitespace from
+	  the string.</para>
+      </listitem>
+      <listitem><para id="x_5b4"><literal role="template-filter" moreinfo="none">tabindent</literal>: Any text.
+	  Yield the text, with every line except the first starting
+	  with a tab character.</para>
+      </listitem>
+      <listitem><para id="x_5b5"><literal role="template-filter" moreinfo="none">urlescape</literal>: Any text.
+	  Escape all characters that are considered
+	  <quote>special</quote> by URL parsers.  For example,
+	  <literal moreinfo="none">foo bar</literal> becomes
+	  <literal moreinfo="none">foo%20bar</literal>.</para>
+      </listitem>
+      <listitem><para id="x_5b6"><literal role="template-kw-filt-author" moreinfo="none">user</literal>: Any text,
+	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Return
+	  the <quote>user</quote> portion of an email address.  For
+	  example, <quote><literal moreinfo="none">Bryan O'Sullivan
+	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
+	  <quote><literal moreinfo="none">bos</literal></quote>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <!-- BEGIN template.simple.manyfilters -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author}\n'</userinput>
+Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|domain}\n'</userinput>
+serpentine.com
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|email}\n'</userinput>
+bos@serpentine.com
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|obfuscate}\n' | cut -c-76</userinput>
+&amp;#66;&amp;#114;&amp;#121;&amp;#97;&amp;#110;&amp;#32;&amp;#79;&amp;#39;&amp;#83;&amp;#117;&amp;#108;&amp;#108;&amp;#105;&amp;#11
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|person}\n'</userinput>
+Bryan O'Sullivan
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|user}\n'</userinput>
+bos
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'looks almost right, but actually garbage: {date}\n'</userinput>
+looks almost right, but actually garbage: 1250431517.00
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|age}\n'</userinput>
+3 seconds
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|date}\n'</userinput>
+Sun Aug 16 14:05:17 2009 +0000
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|hgdate}\n'</userinput>
+1250431517 0
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|isodate}\n'</userinput>
+2009-08-16 14:05 +0000
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|rfc822date}\n'</userinput>
+Sun, 16 Aug 2009 14:05:17 +0000
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|shortdate}\n'</userinput>
+2009-08-16
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc}\n' | cut -c-76</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some m
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.&lt;br/&gt;
+&lt;br/&gt;
+in addition, added a file with the helpful name (at least i hope that some m
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|escape}\n' | cut -c-76</userinput>
+added line to end of &amp;lt;&amp;lt;hello&amp;gt;&amp;gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some m
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill68}\n'</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope
+that some might consider it so) of goodbye.
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill76}\n'</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some
+might consider it so) of goodbye.
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|firstline}\n'</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|strip}\n' | cut -c-76</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+in addition, added a file with the helpful name (at least i hope that some m
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76</userinput>
+added line to end of &lt;&lt;hello&gt;&gt; file.
+
+        in addition, added a file with the helpful name (at least i hope tha
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node}\n'</userinput>
+e3d2468ca47c10bdfbbb41b367a0c84509862197
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node|short}\n'</userinput>
+e3d2468ca47c
+</screen>
+<!-- END template.simple.manyfilters -->
+
+
+    <note>
+      <para id="x_5b7">  If you try to apply a filter to a piece of data that it
+	cannot process, Mercurial will fail and print a Python
+	exception.  For example, trying to run the output of the
+	<literal role="template-keyword" moreinfo="none">desc</literal> keyword into
+	the <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>
+	filter is not a good idea.</para>
+    </note>
+
+    <sect2>
+      <title>Combining filters</title>
+
+      <para id="x_5b8">It is easy to combine filters to yield output in the form
+	you would like.  The following chain of filters tidies up a
+	description, then makes sure that it fits cleanly into 68
+	columns, then indents it by a further 8 characters (at least
+	on Unix-like systems, where a tab is conventionally 8
+	characters wide).</para>
+
+      <!-- BEGIN template.simple.combine -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'</userinput>
+description:
+	added line to end of &lt;&lt;hello&gt;&gt; file.
+
+	in addition, added a file with the helpful name (at least i hope
+	that some might consider it so) of goodbye.
+</screen>
+<!-- END template.simple.combine -->
+
+
+      <para id="x_5b9">Note the use of <quote><literal moreinfo="none">\t</literal></quote> (a
+	tab character) in the template to force the first line to be
+	indented; this is necessary since <literal role="template-keyword" moreinfo="none">tabindent</literal> indents all
+	lines <emphasis>except</emphasis> the first.</para>
+
+      <para id="x_5ba">Keep in mind that the order of filters in a chain is
+	significant.  The first filter is applied to the result of the
+	keyword; the second to the result of the first filter; and so
+	on.  For example, using <literal moreinfo="none">fill68|tabindent</literal>
+	gives very different results from
+	<literal moreinfo="none">tabindent|fill68</literal>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>From templates to styles</title>
+
+    <para id="x_5bb">A command line template provides a quick and simple way to
+      format some output.  Templates can become verbose, though, and
+      it's useful to be able to give a template a name.  A style file
+      is a template with a name, stored in a file.</para>
+
+    <para id="x_5bc">More than that, using a style file unlocks the power of
+      Mercurial's templating engine in ways that are not possible
+      using the command line <option role="hg-opt-log">--template</option> option.</para>
+
+    <sect2>
+      <title>The simplest of style files</title>
+
+      <para id="x_5bd">Our simple style file contains just one line:</para>
+
+      <!-- BEGIN template.simple.rev -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'changeset = "rev: {rev}\n"' &gt; rev</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -l1 --style ./rev</userinput>
+rev: 3
+</screen>
+<!-- END template.simple.rev -->
+
+
+      <para id="x_5be">This tells Mercurial, <quote>if you're printing a
+	  changeset, use the text on the right as the
+	  template</quote>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Style file syntax</title>
+
+      <para id="x_5bf">The syntax rules for a style file are simple.</para>
+
+      <itemizedlist>
+	<listitem><para id="x_5c0">The file is processed one line at a
+	    time.</para>
+	</listitem>
+	<listitem><para id="x_5c1">Leading and trailing white space are
+	    ignored.</para>
+	</listitem>
+	<listitem><para id="x_5c2">Empty lines are skipped.</para>
+	</listitem>
+	<listitem><para id="x_5c3">If a line starts with either of the characters
+	    <quote><literal moreinfo="none">#</literal></quote> or
+	    <quote><literal moreinfo="none">;</literal></quote>, the entire line is
+	    treated as a comment, and skipped as if empty.</para>
+	</listitem>
+	<listitem><para id="x_5c4">A line starts with a keyword.  This must start
+	    with an alphabetic character or underscore, and can
+	    subsequently contain any alphanumeric character or
+	    underscore.  (In regexp notation, a keyword must match
+	    <literal moreinfo="none">[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
+	</listitem>
+	<listitem><para id="x_5c5">The next element must be an
+	    <quote><literal moreinfo="none">=</literal></quote> character, which can
+	    be preceded or followed by an arbitrary amount of white
+	    space.</para>
+	</listitem>
+	<listitem><para id="x_5c6">If the rest of the line starts and ends with
+	    matching quote characters (either single or double quote),
+	    it is treated as a template body.</para>
+	</listitem>
+	<listitem><para id="x_5c7">If the rest of the line <emphasis>does
+	      not</emphasis> start with a quote character, it is
+	    treated as the name of a file; the contents of this file
+	    will be read and used as a template body.</para>
+	</listitem></itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Style files by example</title>
+
+    <para id="x_5c8">To illustrate how to write a style file, we will construct a
+      few by example.  Rather than provide a complete style file and
+      walk through it, we'll mirror the usual process of developing a
+      style file by starting with something very simple, and walking
+      through a series of successively more complete examples.</para>
+
+    <sect2>
+      <title>Identifying mistakes in style files</title>
+
+      <para id="x_5c9">If Mercurial encounters a problem in a style file you are
+	working on, it prints a terse error message that, once you
+	figure out what it means, is actually quite useful.</para>
+
+<!-- BEGIN template.svnstyle.syntax.input -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat broken.style</userinput>
+changeset =
+</screen>
+<!-- END template.svnstyle.syntax.input -->
+
+
+      <para id="x_5ca">Notice that <filename moreinfo="none">broken.style</filename> attempts to
+	define a <literal moreinfo="none">changeset</literal> keyword, but forgets to
+	give any content for it. When instructed to use this style
+	file, Mercurial promptly complains.</para>
+
+      <!-- BEGIN template.svnstyle.syntax.error -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --style broken.style</userinput>
+abort: broken.style:1: parse error
+</screen>
+<!-- END template.svnstyle.syntax.error -->
+
+
+      <para id="x_5cb">This error message looks intimidating, but it is not too
+	hard to follow.</para>
+
+      <itemizedlist>
+	<listitem><para id="x_5cc">The first component is simply Mercurial's way
+	    of saying <quote>I am giving up</quote>.</para>
+	  <programlisting format="linespecific">___abort___: broken.style:1: parse error</programlisting>
+	</listitem>
+	<listitem><para id="x_5cd">Next comes the name of the style file that
+	    contains the error.</para>
+	  <programlisting format="linespecific">abort: ___broken.style___:1: parse error</programlisting>
+	</listitem>
+	<listitem><para id="x_5ce">Following the file name is the line number
+	    where the error was encountered.</para>
+	  <programlisting format="linespecific">abort: broken.style:___1___: parse error</programlisting>
+	</listitem>
+	<listitem><para id="x_5cf">Finally, a description of what went
+	    wrong.</para>
+	  <programlisting format="linespecific">abort: broken.style:1: ___parse error___</programlisting>
+	</listitem>
+	<listitem><para id="x_5d0">The description of the problem is not always
+	    clear (as in this case), but even when it is cryptic, it
+	    is almost always trivial to visually inspect the offending
+	    line in the style file and see what is wrong.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Uniquely identifying a repository</title>
+
+      <para id="x_5d1">If you would like to be able to identify a Mercurial
+	repository <quote>fairly uniquely</quote> using a short string
+	as an identifier, you can use the first revision in the
+	repository.</para>
+
+      <!-- BEGIN template.svnstyle.id -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r0 --template '{node}'</userinput>
+02b4f9d8a52a6da645e20fa7df0accc8aa33b650</screen>
+<!-- END template.svnstyle.id -->
+
+
+      <para id="x_5d2">This is likely to be unique, and so it is
+	useful in many cases.  There are a few caveats.</para>
+      <itemizedlist>
+	<listitem><para id="x_5d3">It will not work in a completely empty
+	    repository, because such a repository does not have a
+	    revision zero.</para>
+	</listitem>
+	<listitem><para id="x_5d4">Neither will it work in the (extremely rare)
+	    case where a repository is a merge of two or more formerly
+	    independent repositories, and you still have those
+	    repositories around.</para>
+	</listitem></itemizedlist>
+      <para id="x_5d5">Here are some uses to which you could put this
+	identifier:</para>
+      <itemizedlist>
+	<listitem><para id="x_5d6">As a key into a table for a database that
+	    manages repositories on a server.</para>
+	</listitem>
+	<listitem><para id="x_5d7">As half of a {<emphasis>repository
+	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
+	    Save this information away when you run an automated build
+	    or other activity, so that you can <quote>replay</quote>
+	    the build later if necessary.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Listing files on multiple lines</title>
+
+      <para id="x_714">Suppose we want to list the files changed by a changeset,
+	one per line, with a little indentation before each file
+	name.</para>
+
+      <!-- BEGIN ch10/multiline.go -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; multiline &lt;&lt; EOF</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">changeset = "Changed in {node|short}:\n{files}"</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">file = "  {file}\n"</userinput>
+<prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style multiline</userinput>
+Changed in badb58085712:
+  .bashrc
+  .hgrc
+  test.c
+</screen>
+<!-- END ch10/multiline.go -->
+
+    </sect2>
+
+    <sect2>
+      <title>Mimicking Subversion's output</title>
+
+      <para id="x_5d8">Let's try to emulate the default output format used by
+	another revision control tool, Subversion.</para>
+
+      <!-- BEGIN template.svnstyle.short -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svn log -r9653</userinput>
+------------------------------------------------------------------------
+r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
+
+On reporting a route error, also include the status for the error,
+rather than indicating a status of 0 when an error has occurred.
+
+Signed-off-by: Sean Hefty &lt;sean.hefty@intel.com&gt;
+
+------------------------------------------------------------------------
+</screen>
+<!-- END template.svnstyle.short -->
+
+
+      <para id="x_5d9">Since Subversion's output style is fairly simple, it is
+	easy to copy-and-paste a hunk of its output into a file, and
+	replace the text produced above by Subversion with the
+	template values we'd like to see expanded.</para>
+
+      <!-- BEGIN template.svnstyle.template -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.template</userinput>
+r{rev} | {author|user} | {date|isodate} ({date|rfc822date})
+
+{desc|strip|fill76}
+
+------------------------------------------------------------------------
+</screen>
+<!-- END template.svnstyle.template -->
+
+
+      <para id="x_5da">There are a few small ways in which this template deviates
+	from the output produced by Subversion.</para>
+      <itemizedlist>
+	<listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
+	    date (the <quote><literal moreinfo="none">Wed, 27 Sep 2006</literal></quote> in the
+	    example output above) in parentheses.  Mercurial's
+	    templating engine does not provide a way to display a date
+	    in this format without also printing the time and time
+	    zone.</para>
+	</listitem>
+	<listitem><para id="x_5dc">We emulate Subversion's printing of
+	    <quote>separator</quote> lines full of
+	    <quote><literal moreinfo="none">-</literal></quote> characters by ending
+	    the template with such a line. We use the templating
+	    engine's <literal role="template-keyword" moreinfo="none">header</literal>
+	    keyword to print a separator line as the first line of
+	    output (see below), thus achieving similar output to
+	    Subversion.</para>
+	</listitem>
+	<listitem><para id="x_5dd">Subversion's output includes a count in the
+	    header of the number of lines in the commit message.  We
+	    cannot replicate this in Mercurial; the templating engine
+	    does not currently provide a filter that counts the number
+	    of lines the template generates.</para>
+	</listitem></itemizedlist>
+      <para id="x_5de">It took me no more than a minute or two of work to replace
+	literal text from an example of Subversion's output with some
+	keywords and filters to give the template above.  The style
+	file simply refers to the template.</para>
+
+      <!-- BEGIN template.svnstyle.style -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.style</userinput>
+header = '------------------------------------------------------------------------\n\n'
+changeset = svn.template
+</screen>
+<!-- END template.svnstyle.style -->
+
+
+      <para id="x_5df">We could have included the text of the template file
+	directly in the style file by enclosing it in quotes and
+	replacing the newlines with
+	<quote><literal moreinfo="none">\n</literal></quote> sequences, but it would
+	have made the style file too difficult to read.  Readability
+	is a good guide when you're trying to decide whether some text
+	belongs in a style file, or in a template file that the style
+	file points to.  If the style file will look too big or
+	cluttered if you insert a literal piece of text, drop it into
+	a template instead.</para>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch12 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:mq">
+  <?dbhtml filename="managing-change-with-mercurial-queues.html"?>
+  <title>Managing change with Mercurial Queues</title>
+
+  <sect1 id="sec:mq:patch-mgmt">
+    <title>The patch management problem</title>
+
+    <para id="x_3ac">Here is a common scenario: you need to install a software
+      package from source, but you find a bug that you must fix in the
+      source before you can start using the package.  You make your
+      changes, forget about the package for a while, and a few months
+      later you need to upgrade to a newer version of the package.  If
+      the newer version of the package still has the bug, you must
+      extract your fix from the older source tree and apply it against
+      the newer version.  This is a tedious task, and it's easy to
+      make mistakes.</para>
+
+    <para id="x_3ad">This is a simple case of the <quote>patch management</quote>
+      problem.  You have an <quote>upstream</quote> source tree that
+      you can't change; you need to make some local changes on top of
+      the upstream tree; and you'd like to be able to keep those
+      changes separate, so that you can apply them to newer versions
+      of the upstream source.</para>
+
+    <para id="x_3ae">The patch management problem arises in many situations.
+      Probably the most visible is that a user of an open source
+      software project will contribute a bug fix or new feature to the
+      project's maintainers in the form of a patch.</para>
+
+    <para id="x_3af">Distributors of operating systems that include open source
+      software often need to make changes to the packages they
+      distribute so that they will build properly in their
+      environments.</para>
+
+    <para id="x_3b0">When you have few changes to maintain, it is easy to manage
+      a single patch using the standard <command moreinfo="none">diff</command> and
+      <command moreinfo="none">patch</command> programs (see <xref linkend="sec:mq:patch"/> for a discussion of these
+      tools). Once the number of changes grows, it starts to make
+      sense to maintain patches as discrete <quote>chunks of
+	work,</quote> so that for example a single patch will contain
+      only one bug fix (the patch might modify several files, but it's
+      doing <quote>only one thing</quote>), and you may have a number
+      of such patches for different bugs you need fixed and local
+      changes you require.  In this situation, if you submit a bug fix
+      patch to the upstream maintainers of a package and they include
+      your fix in a subsequent release, you can simply drop that
+      single patch when you're updating to the newer release.</para>
+
+    <para id="x_3b1">Maintaining a single patch against an upstream tree is a
+      little tedious and error-prone, but not difficult.  However, the
+      complexity of the problem grows rapidly as the number of patches
+      you have to maintain increases.  With more than a tiny number of
+      patches in hand, understanding which ones you have applied and
+      maintaining them moves from messy to overwhelming.</para>
+
+    <para id="x_3b2">Fortunately, Mercurial includes a powerful extension,
+      Mercurial Queues (or simply <quote>MQ</quote>), that massively
+      simplifies the patch management problem.</para>
+
+  </sect1>
+  <sect1 id="sec:mq:history">
+    <title>The prehistory of Mercurial Queues</title>
+
+    <para id="x_3b3">During the late 1990s, several Linux kernel developers
+      started to maintain <quote>patch series</quote> that modified
+      the behavior of the Linux kernel.  Some of these series were
+      focused on stability, some on feature coverage, and others were
+      more speculative.</para>
+
+    <para id="x_3b4">The sizes of these patch series grew rapidly.  In 2002,
+      Andrew Morton published some shell scripts he had been using to
+      automate the task of managing his patch queues.  Andrew was
+      successfully using these scripts to manage hundreds (sometimes
+      thousands) of patches on top of the Linux kernel.</para>
+
+    <sect2 id="sec:mq:quilt">
+      <title>A patchwork quilt</title>
+
+      <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson
+	borrowed the approach of Andrew's scripts and published a tool
+	called <quote>patchwork quilt</quote>
+	<citation>web:quilt</citation>, or simply <quote>quilt</quote>
+	(see <citation>gruenbacher:2005</citation> for a paper
+	describing it).  Because quilt substantially automated patch
+	management, it rapidly gained a large following among open
+	source software developers.</para>
+
+      <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on
+	top of a directory tree. To begin, you tell quilt to manage a
+	directory tree, and tell it which files you want to manage; it
+	stores away the names and contents of those files.  To fix a
+	bug, you create a new patch (using a single command), edit the
+	files you need to fix, then <quote>refresh</quote> the
+	patch.</para>
+
+      <para id="x_3b7">The refresh step causes quilt to scan the directory tree;
+	it updates the patch with all of the changes you have made.
+	You can create another patch on top of the first, which will
+	track the changes required to modify the tree from <quote>tree
+	  with one patch applied</quote> to <quote>tree with two
+	  patches applied</quote>.</para>
+
+      <para id="x_3b8">You can <emphasis>change</emphasis> which patches are
+	applied to the tree.  If you <quote>pop</quote> a patch, the
+	changes made by that patch will vanish from the directory
+	tree.  Quilt remembers which patches you have popped, though,
+	so you can <quote>push</quote> a popped patch again, and the
+	directory tree will be restored to contain the modifications
+	in the patch.  Most importantly, you can run the
+	<quote>refresh</quote> command at any time, and the topmost
+	applied patch will be updated.  This means that you can, at
+	any time, change both which patches are applied and what
+	modifications those patches make.</para>
+
+      <para id="x_3b9">Quilt knows nothing about revision control tools, so it
+	works equally well on top of an unpacked tarball or a
+	Subversion working copy.</para>
+    </sect2>
+
+    <sect2 id="sec:mq:quilt-mq">
+      <title>From patchwork quilt to Mercurial Queues</title>
+
+      <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
+	wrote an extension that he called Mercurial Queues, which
+	added quilt-like behavior to Mercurial.</para>
+
+      <para id="x_3bb">The key difference between quilt and MQ is that quilt
+	knows nothing about revision control systems, while MQ is
+	<emphasis>integrated</emphasis> into Mercurial.  Each patch
+	that you push is represented as a Mercurial changeset.  Pop a
+	patch, and the changeset goes away.</para>
+
+      <para id="x_3bc">Because quilt does not care about revision control tools,
+	it is still a tremendously useful piece of software to know
+	about for situations where you cannot use Mercurial and
+	MQ.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>The huge advantage of MQ</title>
+
+    <para id="x_3bd">I cannot overstate the value that MQ offers through the
+      unification of patches and revision control.</para>
+
+    <para id="x_3be">A major reason that patches have persisted in the free
+      software and open source world—in spite of the
+      availability of increasingly capable revision control tools over
+      the years—is the <emphasis>agility</emphasis> they
+      offer.</para>
+
+    <para id="x_3bf">Traditional revision control tools make a permanent,
+      irreversible record of everything that you do.  While this has
+      great value, it's also somewhat stifling.  If you want to
+      perform a wild-eyed experiment, you have to be careful in how
+      you go about it, or you risk leaving unneeded—or worse,
+      misleading or destabilising—traces of your missteps and
+      errors in the permanent revision record.</para>
+
+    <para id="x_3c0">By contrast, MQ's marriage of distributed revision control
+      with patches makes it much easier to isolate your work.  Your
+      patches live on top of normal revision history, and you can make
+      them disappear or reappear at will.  If you don't like a patch,
+      you can drop it.  If a patch isn't quite as you want it to be,
+      simply fix it—as many times as you need to, until you
+      have refined it into the form you desire.</para>
+
+    <para id="x_3c1">As an example, the integration of patches with revision
+      control makes understanding patches and debugging their
+      effects—and their interplay with the code they're based
+      on—<emphasis>enormously</emphasis> easier. Since every
+      applied patch has an associated changeset, you can give <command role="hg-cmd" moreinfo="none">hg log</command> a file name to see which
+      changesets and patches affected the file.  You can use the
+      <command role="hg-cmd" moreinfo="none">hg bisect</command> command to
+      binary-search through all changesets and applied patches to see
+      where a bug got introduced or fixed.  You can use the <command role="hg-cmd" moreinfo="none">hg annotate</command> command to see which
+      changeset or patch modified a particular line of a source file.
+      And so on.</para>
+  </sect1>
+
+  <sect1 id="sec:mq:patch">
+    <title>Understanding patches</title>
+
+    <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
+      helpful to understand what patches are, and a little about the
+      tools that work with them.</para>
+
+    <para id="x_3c3">The traditional Unix <command moreinfo="none">diff</command> command
+      compares two files, and prints a list of differences between
+      them. The <command moreinfo="none">patch</command> command understands these
+      differences as <emphasis>modifications</emphasis> to make to a
+      file.  Take a look below for a simple example of these commands
+      in action.</para>
+
+      <!-- BEGIN mq.dodiff.diff -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'this is my original thought' &gt; oldfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'i have changed my mind' &gt; newfile</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diff -u oldfile newfile &gt; tiny.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat tiny.patch</userinput>
+--- oldfile	2009-08-16 14:05:06.000000000 +0000
++++ newfile	2009-08-16 14:05:06.000000000 +0000
+@@ -1 +1 @@
+-this is my original thought
++i have changed my mind
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">patch &lt; tiny.patch</userinput>
+patching file oldfile
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat oldfile</userinput>
+i have changed my mind
+</screen>
+<!-- END mq.dodiff.diff -->
+
+
+    <para id="x_3c4">The type of file that <command moreinfo="none">diff</command> generates (and
+      <command moreinfo="none">patch</command> takes as input) is called a
+      <quote>patch</quote> or a <quote>diff</quote>; there is no
+      difference between a patch and a diff.  (We'll use the term
+      <quote>patch</quote>, since it's more commonly used.)</para>
+
+    <para id="x_3c5">A patch file can start with arbitrary text; the
+      <command moreinfo="none">patch</command> command ignores this text, but MQ uses
+      it as the commit message when creating changesets.  To find the
+      beginning of the patch content, <command moreinfo="none">patch</command>
+      searches for the first line that starts with the string
+      <quote><literal moreinfo="none">diff -</literal></quote>.</para>
+
+    <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs
+      (<command moreinfo="none">patch</command> can accept several other diff formats,
+      but MQ doesn't).  A unified diff contains two kinds of header.
+      The <emphasis>file header</emphasis> describes the file being
+      modified; it contains the name of the file to modify.  When
+      <command moreinfo="none">patch</command> sees a new file header, it looks for a
+      file with that name to start modifying.</para>
+
+    <para id="x_3c7">After the file header comes a series of
+      <emphasis>hunks</emphasis>.  Each hunk starts with a header;
+      this identifies the range of line numbers within the file that
+      the hunk should modify.  Following the header, a hunk starts and
+      ends with a few (usually three) lines of text from the
+      unmodified file; these are called the
+      <emphasis>context</emphasis> for the hunk.  If there's only a
+      small amount of context between successive hunks,
+      <command moreinfo="none">diff</command> doesn't print a new hunk header; it just
+      runs the hunks together, with a few lines of context between
+      modifications.</para>
+
+    <para id="x_3c8">Each line of context begins with a space character.  Within
+      the hunk, a line that begins with
+      <quote><literal moreinfo="none">-</literal></quote> means <quote>remove this
+	line,</quote> while a line that begins with
+      <quote><literal moreinfo="none">+</literal></quote> means <quote>insert this
+	line.</quote>  For example, a line that is modified is
+      represented by one deletion and one insertion.</para>
+
+    <para id="x_3c9">We will return to some of the more subtle aspects of patches
+      later (in <xref linkend="sec:mq:adv-patch"/>), but you
+      should have
+      enough information now to use MQ.</para>
+  </sect1>
+
+  <sect1 id="sec:mq:start">
+    <title>Getting started with Mercurial Queues</title>
+
+    <para id="x_3ca">Because MQ is implemented as an extension, you must
+      explicitly enable before you can use it.  (You don't need to
+      download anything; MQ ships with the standard Mercurial
+      distribution.)  To enable MQ, edit your <filename role="home" moreinfo="none">~/.hgrc</filename> file, and add the lines
+      below.</para>
+
+    <programlisting format="linespecific">[extensions]
+hgext.mq =</programlisting>
+
+    <para id="x_3cb">Once the extension is enabled, it will make a number of new
+      commands available.  To verify that the extension is working,
+      you can use <command role="hg-cmd" moreinfo="none">hg help</command> to see if
+      the <command role="hg-ext-mq" moreinfo="none">qinit</command> command is now
+      available.</para>
+
+    <!-- BEGIN mq.qinit-help.help -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help qinit</userinput>
+hg qinit [-c]
+
+init a new queue repository
+
+    The queue repository is unversioned by default. If -c is
+    specified, qinit will create a separate nested repository
+    for patches (qinit -c may also be run later to convert
+    an unversioned patch repository into a versioned one).
+    You can use qcommit to commit changes to this queue repository.
+
+options:
+
+ -c --create-repo  create queue repository
+
+use "hg -v help qinit" to show global options
+</screen>
+<!-- END mq.qinit-help.help -->
+
+
+    <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
+      repository, and its commands only operate within that
+      repository.  To get started, simply prepare the repository using
+      the <command role="hg-ext-mq" moreinfo="none">qinit</command> command.</para>
+
+    <!-- BEGIN mq.tutorial.qinit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mq-sandbox</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mq-sandbox</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 1' &gt; file1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'another line 1' &gt; file2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file1 file2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m'first change'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
+</screen>
+<!-- END mq.tutorial.qinit -->
+
+
+    <para id="x_3cd">This command creates an empty directory called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>, where
+      MQ will keep its metadata.  As with many Mercurial commands, the
+      <command role="hg-ext-mq" moreinfo="none">qinit</command> command prints nothing
+      if it succeeds.</para>
+
+    <sect2>
+      <title>Creating a new patch</title>
+
+      <para id="x_3ce">To begin work on a new patch, use the <command role="hg-ext-mq" moreinfo="none">qnew</command> command.  This command takes
+	one argument, the name of the patch to create.</para>
+
+      <para id="x_3cf">MQ will use this as the name of an actual file in the
+	<filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory, as you
+	can see below.</para>
+
+      <!-- BEGIN mq.tutorial.qnew -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   0:5d84c303994b
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:11 2009 +0000
+summary:     first change
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew first.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
+changeset:   1:ba4d7a3f2149
+tag:         qtip
+tag:         first.patch
+tag:         tip
+tag:         qbase
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:11 2009 +0000
+summary:     [mq]: first.patch
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls .hg/patches</userinput>
+first.patch  series  status
+</screen>
+<!-- END mq.tutorial.qnew -->
+
+
+      <para id="x_3d0">Also newly present in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory are two
+	other files, <filename role="special" moreinfo="none">series</filename> and
+	<filename role="special" moreinfo="none">status</filename>.  The <filename role="special" moreinfo="none">series</filename> file lists all of the
+	patches that MQ knows about for this repository, with one
+	patch per line.  Mercurial uses the <filename role="special" moreinfo="none">status</filename> file for internal
+	book-keeping; it tracks all of the patches that MQ has
+	<emphasis>applied</emphasis> in this repository.</para>
+
+      <note>
+	<para id="x_3d1">  You may sometimes want to edit the <filename role="special" moreinfo="none">series</filename> file by hand; for
+	  example, to change the sequence in which some patches are
+	  applied.  However, manually editing the <filename role="special" moreinfo="none">status</filename> file is almost always a
+	  bad idea, as it's easy to corrupt MQ's idea of what is
+	  happening.</para>
+      </note>
+
+      <para id="x_3d2">Once you have created your new patch, you can edit files
+	in the working directory as you usually would.  All of the
+	normal Mercurial commands, such as <command role="hg-cmd" moreinfo="none">hg
+	  diff</command> and <command role="hg-cmd" moreinfo="none">hg
+	  annotate</command>, work exactly as they did before.</para>
+    </sect2>
+
+    <sect2>
+      <title>Refreshing a patch</title>
+
+      <para id="x_3d3">When you reach a point where you want to save your work,
+	use the <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
+	to update the patch you are working on.</para>
+
+      <!-- BEGIN mq.tutorial.qrefresh -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 2' &gt;&gt; file1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+diff -r ba4d7a3f2149 file1
+--- a/file1	Sun Aug 16 14:05:11 2009 +0000
++++ b/file1	Sun Aug 16 14:05:11 2009 +0000
+@@ -1,1 +1,2 @@
+ line 1
++line 2
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
+1[qtip,first.patch,tip,qbase]   1aa236e17e55   2009-08-16 14:05 +0000   bos
+  [mq]: first.patch
+
+diff -r 5d84c303994b -r 1aa236e17e55 file1
+--- a/file1	Sun Aug 16 14:05:11 2009 +0000
++++ b/file1	Sun Aug 16 14:05:11 2009 +0000
+@@ -1,1 +1,2 @@
+ line 1
++line 2
+
+</screen>
+<!-- END mq.tutorial.qrefresh -->
+
+
+      <para id="x_3d4">This command folds the changes you have made in the
+	working directory into your patch, and updates its
+	corresponding changeset to contain those changes.</para>
+
+      <para id="x_3d5">You can run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
+	as often as you like, so it's a good way to
+	<quote>checkpoint</quote> your work.  Refresh your patch at an
+	opportune time; try an experiment; and if the experiment
+	doesn't work out, <command role="hg-cmd" moreinfo="none">hg revert</command>
+	your modifications back to the last time you refreshed.</para>
+
+      <!-- BEGIN mq.tutorial.qrefresh2 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 3' &gt;&gt; file1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
+M file1
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
+1[qtip,first.patch,tip,qbase]   ebec7ce95e11   2009-08-16 14:05 +0000   bos
+  [mq]: first.patch
+
+diff -r 5d84c303994b -r ebec7ce95e11 file1
+--- a/file1	Sun Aug 16 14:05:11 2009 +0000
++++ b/file1	Sun Aug 16 14:05:12 2009 +0000
+@@ -1,1 +1,3 @@
+ line 1
++line 2
++line 3
+
+</screen>
+<!-- END mq.tutorial.qrefresh2 -->
+
+    </sect2>
+
+    <sect2>
+      <title>Stacking and tracking patches</title>
+
+      <para id="x_3d6">Once you have finished working on a patch, or need to work
+	on another, you can use the <command role="hg-ext-mq" moreinfo="none">qnew</command> command again to create a
+	new patch. Mercurial will apply this patch on top of your
+	existing patch.</para>
+
+      <!-- BEGIN mq.tutorial.qnew2 -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew second.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style=compact --limit=2</userinput>
+2[qtip,second.patch,tip]   dffbc4265523   2009-08-16 14:05 +0000   bos
+  [mq]: second.patch
+
+1[first.patch,qbase]   ebec7ce95e11   2009-08-16 14:05 +0000   bos
+  [mq]: first.patch
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 4' &gt;&gt; file1</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
+2[qtip,second.patch,tip]   fdacb9b232ac   2009-08-16 14:05 +0000   bos
+  [mq]: second.patch
+
+diff -r ebec7ce95e11 -r fdacb9b232ac file1
+--- a/file1	Sun Aug 16 14:05:12 2009 +0000
++++ b/file1	Sun Aug 16 14:05:12 2009 +0000
+@@ -1,3 +1,4 @@
+ line 1
+ line 2
+ line 3
++line 4
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg annotate file1</userinput>
+0: line 1
+1: line 2
+1: line 3
+2: line 4
+</screen>
+<!-- END mq.tutorial.qnew2 -->
+
+
+      <para id="x_3d7">Notice that the patch contains the changes in our prior
+	patch as part of its context (you can see this more clearly in
+	the output of <command role="hg-cmd" moreinfo="none">hg
+	  annotate</command>).</para>
+
+      <para id="x_3d8">So far, with the exception of <command role="hg-ext-mq" moreinfo="none">qnew</command> and <command role="hg-ext-mq" moreinfo="none">qrefresh</command>, we've been careful to
+	only use regular Mercurial commands.  However, MQ provides
+	many commands that are easier to use when you are thinking
+	about patches, as illustrated below.</para>
+
+      <!-- BEGIN mq.tutorial.qseries -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
+first.patch
+second.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+first.patch
+second.patch
+</screen>
+<!-- END mq.tutorial.qseries -->
+
+
+      <itemizedlist>
+	<listitem><para id="x_3d9">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command lists every
+	    patch that MQ knows about in this repository, from oldest
+	    to newest (most recently
+	    <emphasis>created</emphasis>).</para>
+	</listitem>
+	<listitem><para id="x_3da">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command lists every
+	    patch that MQ has <emphasis>applied</emphasis> in this
+	    repository, again from oldest to newest (most recently
+	    applied).</para>
+	</listitem></itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Manipulating the patch stack</title>
+
+      <para id="x_3db">The previous discussion implied that there must be a
+	difference between <quote>known</quote> and
+	<quote>applied</quote> patches, and there is.  MQ can manage a
+	patch without it being applied in the repository.</para>
+
+      <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding
+	changeset in the repository, and the effects of the patch and
+	changeset are visible in the working directory.  You can undo
+	the application of a patch using the <command role="hg-ext-mq" moreinfo="none">qpop</command> command.  MQ still
+	<emphasis>knows about</emphasis>, or manages, a popped patch,
+	but the patch no longer has a corresponding changeset in the
+	repository, and the working directory does not contain the
+	changes made by the patch.  <xref linkend="fig:mq:stack"/> illustrates
+	the difference between applied and tracked patches.</para>
+
+      <figure id="fig:mq:stack" float="0">
+	<title>Applied and unapplied patches in the MQ patch
+	  stack</title>
+	<mediaobject>
+	  <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para id="x_3de">You can reapply an unapplied, or popped, patch using the
+	<command role="hg-ext-mq" moreinfo="none">qpush</command> command.  This
+	creates a new changeset to correspond to the patch, and the
+	patch's changes once again become present in the working
+	directory.  See below for examples of <command role="hg-ext-mq" moreinfo="none">qpop</command> and <command role="hg-ext-mq" moreinfo="none">qpush</command> in action.</para>
+
+      <!-- BEGIN mq.tutorial.qpop -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+first.patch
+second.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
+now at: first.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
+first.patch
+second.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+first.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
+line 1
+line 2
+line 3
+</screen>
+<!-- END mq.tutorial.qpop -->
+
+
+      <para id="x_3df">Notice that once we have popped a patch or two patches,
+	the output of <command role="hg-ext-mq" moreinfo="none">qseries</command>
+	remains the same, while that of <command role="hg-ext-mq" moreinfo="none">qapplied</command> has changed.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Pushing and popping many patches</title>
+
+      <para id="x_3e0">While <command role="hg-ext-mq" moreinfo="none">qpush</command> and
+	<command role="hg-ext-mq" moreinfo="none">qpop</command> each operate on a
+	single patch at a time by default, you can push and pop many
+	patches in one go.  The <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
+	<command role="hg-ext-mq" moreinfo="none">qpush</command> causes it to push
+	all unapplied patches, while the <option role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command role="hg-ext-mq" moreinfo="none">qpop</command> causes it to pop all applied
+	patches.  (For some more ways to push and pop many patches,
+	see <xref linkend="sec:mq:perf"/> below.)</para>
+
+      <!-- BEGIN mq.tutorial.qpush-a -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
+applying second.patch
+now at: second.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
+line 1
+line 2
+line 3
+line 4
+</screen>
+<!-- END mq.tutorial.qpush-a -->
+
+    </sect2>
+
+    <sect2>
+      <title>Safety checks, and overriding them</title>
+
+      <para id="x_3e1">Several MQ commands check the working directory before
+	they do anything, and fail if they find any modifications.
+	They do this to ensure that you won't lose any changes that
+	you have made, but not yet incorporated into a patch.  The
+	example below illustrates this; the <command role="hg-ext-mq" moreinfo="none">qnew</command> command will not create a
+	new patch if there are outstanding changes, caused in this
+	case by the <command role="hg-cmd" moreinfo="none">hg add</command> of
+	<filename moreinfo="none">file3</filename>.</para>
+
+      <!-- BEGIN mq.tutorial.add -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'file 3, line 1' &gt;&gt; file3</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew add-file3.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -f add-file3.patch</userinput>
+abort: patch "add-file3.patch" already exists
+</screen>
+<!-- END mq.tutorial.add -->
+
+
+      <para id="x_3e2">Commands that check the working directory all take an
+	<quote>I know what I'm doing</quote> option, which is always
+	named <option>-f</option>.  The exact meaning of
+	<option>-f</option> depends on the command.  For example,
+	<command role="hg-cmd" moreinfo="none">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
+	will incorporate any outstanding changes into the new patch it
+	creates, but <command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
+	will revert modifications to any files affected by the patch
+	that it is popping.  Be sure to read the documentation for a
+	command's <option>-f</option> option before you use it!</para>
+    </sect2>
+
+    <sect2>
+      <title>Working on several patches at once</title>
+
+      <para id="x_3e3">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
+	always refreshes the <emphasis>topmost</emphasis> applied
+	patch.  This means that you can suspend work on one patch (by
+	refreshing it), pop or push to make a different patch the top,
+	and work on <emphasis>that</emphasis> patch for a
+	while.</para>
+
+      <para id="x_3e4">Here's an example that illustrates how you can use this
+	ability. Let's say you're developing a new feature as two
+	patches.  The first is a change to the core of your software,
+	and the second—layered on top of the
+	first—changes the user interface to use the code you
+	just added to the core.  If you notice a bug in the core while
+	you're working on the UI patch, it's easy to fix the core.
+	Simply <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the UI
+	patch to save your in-progress changes, and <command role="hg-ext-mq" moreinfo="none">qpop</command> down to the core patch.  Fix
+	the core bug, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
+	core patch, and <command role="hg-ext-mq" moreinfo="none">qpush</command> back
+	to the UI patch to continue where you left off.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:mq:adv-patch">
+    <title>More about patches</title>
+
+    <para id="x_3e5">MQ uses the GNU <command moreinfo="none">patch</command> command to apply
+      patches, so it's helpful to know a few more detailed aspects of
+      how <command moreinfo="none">patch</command> works, and about patches
+      themselves.</para>
+
+    <sect2>
+      <title>The strip count</title>
+
+      <para id="x_3e6">If you look at the file headers in a patch, you will
+	notice that the pathnames usually have an extra component on
+	the front that isn't present in the actual path name.  This is
+	a holdover from the way that people used to generate patches
+	(people still do this, but it's somewhat rare with modern
+	revision control tools).</para>
+
+      <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide
+	that she wanted to create a patch.  So she'd rename her
+	working directory, unpack the tarball again (hence the need
+	for the rename), and use the <option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to
+	<command moreinfo="none">diff</command> to recursively generate a patch
+	between the unmodified directory and the modified one.  The
+	result would be that the name of the unmodified directory
+	would be at the front of the left-hand path in every file
+	header, and the name of the modified directory would be at the
+	front of the right-hand path.</para>
+
+      <para id="x_3e8">Since someone receiving a patch from the Alices of the net
+	would be unlikely to have unmodified and modified directories
+	with exactly the same names, the <command moreinfo="none">patch</command>
+	command has a <option role="cmd-opt-patch">-p</option> option
+	that indicates the number of leading path name components to
+	strip when trying to apply a patch.  This number is called the
+	<emphasis>strip count</emphasis>.</para>
+
+      <para id="x_3e9">An option of <quote><literal moreinfo="none">-p1</literal></quote> means
+	<quote>use a strip count of one</quote>.  If
+	<command moreinfo="none">patch</command> sees a file name
+	<filename moreinfo="none">foo/bar/baz</filename> in a file header, it will
+	strip <filename moreinfo="none">foo</filename> and try to patch a file named
+	<filename moreinfo="none">bar/baz</filename>.  (Strictly speaking, the strip
+	count refers to the number of <emphasis>path
+	  separators</emphasis> (and the components that go with them
+	) to strip.  A strip count of one will turn
+	<filename moreinfo="none">foo/bar</filename> into <filename moreinfo="none">bar</filename>,
+	but <filename moreinfo="none">/foo/bar</filename> (notice the extra leading
+	slash) into <filename moreinfo="none">foo/bar</filename>.)</para>
+
+      <para id="x_3ea">The <quote>standard</quote> strip count for patches is
+	one; almost all patches contain one leading path name
+	component that needs to be stripped. Mercurial's <command role="hg-cmd" moreinfo="none">hg diff</command> command generates path names
+	in this form, and the <command role="hg-cmd" moreinfo="none">hg
+	  import</command> command and MQ expect patches to have a
+	strip count of one.</para>
+
+      <para id="x_3eb">If you receive a patch from someone that you want to add
+	to your patch queue, and the patch needs a strip count other
+	than one, you cannot just <command role="hg-ext-mq" moreinfo="none">qimport</command> the patch, because
+	<command role="hg-ext-mq" moreinfo="none">qimport</command> does not yet have
+	a <literal moreinfo="none">-p</literal> option (see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
+	  311</ulink>).  Your best bet is to <command role="hg-ext-mq" moreinfo="none">qnew</command> a patch of your own, then
+	use <command moreinfo="none">patch -pN</command> to apply their patch,
+	followed by <command role="hg-cmd" moreinfo="none">hg addremove</command> to
+	pick up any files added or removed by the patch, followed by
+	<command role="hg-ext-mq" moreinfo="none">hg qrefresh</command>. This
+	complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
+	  311</ulink> for details.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Strategies for applying a patch</title>
+
+      <para id="x_3ec">When <command moreinfo="none">patch</command> applies a hunk, it tries a
+	handful of successively less accurate strategies to try to
+	make the hunk apply. This falling-back technique often makes
+	it possible to take a patch that was generated against an old
+	version of a file, and apply it against a newer version of
+	that file.</para>
+
+      <para id="x_3ed">First, <command moreinfo="none">patch</command> tries an exact match,
+	where the line numbers, the context, and the text to be
+	modified must apply exactly.  If it cannot make an exact
+	match, it tries to find an exact match for the context,
+	without honouring the line numbering information.  If this
+	succeeds, it prints a line of output saying that the hunk was
+	applied, but at some <emphasis>offset</emphasis> from the
+	original line number.</para>
+
+      <para id="x_3ee">If a context-only match fails, <command moreinfo="none">patch</command>
+	removes the first and last lines of the context, and tries a
+	<emphasis>reduced</emphasis> context-only match.  If the hunk
+	with reduced context succeeds, it prints a message saying that
+	it applied the hunk with a <emphasis>fuzz factor</emphasis>
+	(the number after the fuzz factor indicates how many lines of
+	context <command moreinfo="none">patch</command> had to trim before the patch
+	applied).</para>
+
+      <para id="x_3ef">When neither of these techniques works,
+	<command moreinfo="none">patch</command> prints a message saying that the hunk
+	in question was rejected.  It saves rejected hunks (also
+	simply called <quote>rejects</quote>) to a file with the same
+	name, and an added <filename role="special" moreinfo="none">.rej</filename>
+	extension.  It also saves an unmodified copy of the file with
+	a <filename role="special" moreinfo="none">.orig</filename> extension; the
+	copy of the file without any extensions will contain any
+	changes made by hunks that <emphasis>did</emphasis> apply
+	cleanly.  If you have a patch that modifies
+	<filename moreinfo="none">foo</filename> with six hunks, and one of them fails
+	to apply, you will have: an unmodified
+	<filename moreinfo="none">foo.orig</filename>, a <filename moreinfo="none">foo.rej</filename>
+	containing one hunk, and <filename moreinfo="none">foo</filename>, containing
+	the changes made by the five successful hunks.</para>
+    </sect2>
+
+    <sect2>
+      <title>Some quirks of patch representation</title>
+
+      <para id="x_3f0">There are a few useful things to know about how
+	<command moreinfo="none">patch</command> works with files.</para>
+      <itemizedlist>
+	<listitem><para id="x_3f1">This should already be obvious, but
+	    <command moreinfo="none">patch</command> cannot handle binary
+	    files.</para>
+	</listitem>
+	<listitem><para id="x_3f2">Neither does it care about the executable bit;
+	    it creates new files as readable, but not
+	    executable.</para>
+	</listitem>
+	<listitem><para id="x_3f3"><command moreinfo="none">patch</command> treats the removal of
+	    a file as a diff between the file to be removed and the
+	    empty file.  So your idea of <quote>I deleted this
+	      file</quote> looks like <quote>every line of this file
+	      was deleted</quote> in a patch.</para>
+	</listitem>
+	<listitem><para id="x_3f4">It treats the addition of a file as a diff
+	    between the empty file and the file to be added.  So in a
+	    patch, your idea of <quote>I added this file</quote> looks
+	    like <quote>every line of this file was
+	      added</quote>.</para>
+	</listitem>
+	<listitem><para id="x_3f5">It treats a renamed file as the removal of the
+	    old name, and the addition of the new name.  This means
+	    that renamed files have a big footprint in patches.  (Note
+	    also that Mercurial does not currently try to infer when
+	    files have been renamed or copied in a patch.)</para>
+	</listitem>
+	<listitem><para id="x_3f6"><command moreinfo="none">patch</command> cannot represent
+	    empty files, so you cannot use a patch to represent the
+	    notion <quote>I added this empty file to the
+	      tree</quote>.</para>
+	</listitem></itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Beware the fuzz</title>
+
+      <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
+	will often be completely successful, these inexact techniques
+	naturally leave open the possibility of corrupting the patched
+	file.  The most common cases typically involve applying a
+	patch twice, or at an incorrect location in the file.  If
+	<command moreinfo="none">patch</command> or <command role="hg-ext-mq" moreinfo="none">qpush</command> ever mentions an offset or
+	fuzz factor, you should make sure that the modified files are
+	correct afterwards.</para>
+
+      <para id="x_3f8">It's often a good idea to refresh a patch that has applied
+	with an offset or fuzz factor; refreshing the patch generates
+	new context information that will make it apply cleanly.  I
+	say <quote>often,</quote> not <quote>always,</quote> because
+	sometimes refreshing a patch will make it fail to apply
+	against a different revision of the underlying files.  In some
+	cases, such as when you're maintaining a patch that must sit
+	on top of multiple versions of a source tree, it's acceptable
+	to have a patch apply with some fuzz, provided you've verified
+	the results of the patching process in such cases.</para>
+    </sect2>
+
+    <sect2>
+      <title>Handling rejection</title>
+
+      <para id="x_3f9">If <command role="hg-ext-mq" moreinfo="none">qpush</command> fails to
+	apply a patch, it will print an error message and exit.  If it
+	has left <filename role="special" moreinfo="none">.rej</filename> files
+	behind, it is usually best to fix up the rejected hunks before
+	you push more patches or do any further work.</para>
+
+      <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
+	and no longer does because you've changed the underlying code
+	that your patches are based on, Mercurial Queues can help; see
+	<xref linkend="sec:mq:merge"/> for details.</para>
+
+      <para id="x_3fb">Unfortunately, there aren't any great techniques for
+	dealing with rejected hunks.  Most often, you'll need to view
+	the <filename role="special" moreinfo="none">.rej</filename> file and edit the
+	target file, applying the rejected hunks by hand.</para>
+
+      <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
+	of Mercurial Queues), wrote a tool called
+	<command moreinfo="none">mpatch</command> (<ulink url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 
+	which takes a simple approach to automating the application of
+	hunks rejected by <command moreinfo="none">patch</command>.  The
+	<command moreinfo="none">mpatch</command> command can help with four common
+	reasons that a hunk may be rejected:</para>
+
+      <itemizedlist>
+	<listitem><para id="x_3fe">The context in the middle of a hunk has
+	    changed.</para>
+	</listitem>
+	<listitem><para id="x_3ff">A hunk is missing some context at the
+	    beginning or end.</para>
+	</listitem>
+	<listitem><para id="x_400">A large hunk might apply better—either
+	    entirely or in part—if it was broken up into
+	    smaller hunks.</para>
+	</listitem>
+	<listitem><para id="x_401">A hunk removes lines with slightly different
+	    content than those currently present in the file.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_402">If you use <command moreinfo="none">mpatch</command>, you
+	should be doubly careful to check your results when you're
+	done.  In fact, <command moreinfo="none">mpatch</command> enforces this method
+	of double-checking the tool's output, by automatically
+	dropping you into a merge program when it has done its job, so
+	that you can verify its work and finish off any remaining
+	merges.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>More on patch management</title>
+
+    <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
+      to perform other kinds of patch management operations.</para>
+
+    <sect2>
+      <title>Deleting unwanted patches</title>
+
+      <para id="x_6dc">If you want to get rid of a patch, use the <command role="hg-ext-mq" moreinfo="none">hg qdelete</command> command to delete the
+	patch file and remove its entry from the patch series.  If you
+	try to delete a patch that is still applied, <command role="hg-ext-mq" moreinfo="none">hg qdelete</command> will refuse.</para>
+
+      <!-- BEGIN ch11/qdelete.go -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew bad.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
+abort: cannot delete applied patch bad.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
+patch queue now empty
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
+</screen>
+<!-- END ch11/qdelete.go -->
+
+    </sect2>
+
+    <sect2>
+      <title>Converting to and from permanent revisions</title>
+
+      <para id="x_6dd">Once you're done working on a patch and want to
+      turn it into a permanent changeset, use the <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command. Pass a revision
+      to the command to identify the patch that you want to turn into
+      a regular changeset; this patch must already be applied.</para>
+
+      <!-- BEGIN ch11/qdelete.convert -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew good.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh -m 'Good change'</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qfinish tip</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact</userinput>
+0[tip]   32fc5ce6b092   2009-08-16 14:04 +0000   bos
+  Good change
+
+</screen>
+<!-- END ch11/qdelete.convert -->
+
+
+      <para id="x_6e0">The <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command
+        accepts an <option>--all</option> or <option>-a</option>
+        option, which turns all applied patches into regular
+        changesets.</para>
+
+      <para id="x_6de">It is also possible to turn an existing changeset into a
+	patch, by passing the <option>-r</option> option to <command role="hg-ext-mq" moreinfo="none">hg qimport</command>.</para>
+
+      <!-- BEGIN ch11/qdelete.import -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qimport -r tip</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+0.diff
+</screen>
+<!-- END ch11/qdelete.import -->
+
+
+      <para id="x_6df">Note that it only makes sense to convert a changeset into
+	a patch if you have not propagated that changeset into any
+	other repositories.  The imported changeset's ID will change
+	every time you refresh the patch, which will make Mercurial
+	treat it as unrelated to the original changeset if you have
+	pushed it somewhere else.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec:mq:perf">
+    <title>Getting the best performance out of MQ</title>
+
+    <para id="x_403">MQ is very efficient at handling a large number
+      of patches. I ran some performance experiments in mid-2006 for a
+      talk that I gave at the 2006 EuroPython conference (on modern
+      hardware, you should expect better performance than you'll see
+      below).  I used as my data set the Linux 2.6.17-mm1 patch
+      series, which consists of 1,738 patches. I applied these on top
+      of a Linux kernel repository containing all 27,472 revisions
+      between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
+
+    <para id="x_404">On my old, slow laptop, I was able to <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all
+      1,738 patches in 3.5 minutes, and <command role="hg-cmd" moreinfo="none">hg qpop
+	<option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
+      them all in 30 seconds.  (On a newer laptop, the time to push
+      all patches dropped to two minutes.)  I could <command role="hg-ext-mq" moreinfo="none">qrefresh</command> one of the biggest patches
+      (which made 22,779 lines of changes to 287 files) in 6.6
+      seconds.</para>
+
+    <para id="x_405">Clearly, MQ is well suited to working in large trees, but
+      there are a few tricks you can use to get the best performance
+      of it.</para>
+
+    <para id="x_406">First of all, try to <quote>batch</quote> operations
+      together.  Every time you run <command role="hg-ext-mq" moreinfo="none">qpush</command> or <command role="hg-ext-mq" moreinfo="none">qpop</command>, these commands scan the
+      working directory once to make sure you haven't made some
+      changes and then forgotten to run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>.  On a small tree, the
+      time that this scan takes is unnoticeable.  However, on a
+      medium-sized tree (containing tens of thousands of files), it
+      can take a second or more.</para>
+
+    <para id="x_407">The <command role="hg-ext-mq" moreinfo="none">qpush</command> and <command role="hg-ext-mq" moreinfo="none">qpop</command> commands allow you to push and
+      pop multiple patches at a time.  You can identify the
+      <quote>destination patch</quote> that you want to end up at.
+      When you <command role="hg-ext-mq" moreinfo="none">qpush</command> with a
+      destination specified, it will push patches until that patch is
+      at the top of the applied stack.  When you <command role="hg-ext-mq" moreinfo="none">qpop</command> to a destination, MQ will pop
+      patches until the destination patch is at the top.</para>
+
+    <para id="x_408">You can identify a destination patch using either the name
+      of the patch, or by number.  If you use numeric addressing,
+      patches are counted from zero; this means that the first patch
+      is zero, the second is one, and so on.</para>
+  </sect1>
+
+  <sect1 id="sec:mq:merge">
+    <title>Updating your patches when the underlying code
+      changes</title>
+
+    <para id="x_409">It's common to have a stack of patches on top of an
+      underlying repository that you don't modify directly.  If you're
+      working on changes to third-party code, or on a feature that is
+      taking longer to develop than the rate of change of the code
+      beneath, you will often need to sync up with the underlying
+      code, and fix up any hunks in your patches that no longer apply.
+      This is called <emphasis>rebasing</emphasis> your patch
+      series.</para>
+
+    <para id="x_40a">The simplest way to do this is to <command role="hg-cmd" moreinfo="none">hg
+	qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
+	  -a</option></command> your patches, then <command role="hg-cmd" moreinfo="none">hg pull</command> changes into the underlying
+      repository, and finally <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
+      patches again.  MQ will stop pushing any time it runs across a
+      patch that fails to apply during conflicts, allowing you to fix
+      your conflicts, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
+      affected patch, and continue pushing until you have fixed your
+      entire stack.</para>
+
+    <para id="x_40b">This approach is easy to use and works well if you don't
+      expect changes to the underlying code to affect how well your
+      patches apply. If your patch stack touches code that is modified
+      frequently or invasively in the underlying repository, however,
+      fixing up rejected hunks by hand quickly becomes
+      tiresome.</para>
+
+    <para id="x_40c">It's possible to partially automate the rebasing process.
+      If your patches apply cleanly against some revision of the
+      underlying repo, MQ can use this information to help you to
+      resolve conflicts between your patches and a different
+      revision.</para>
+
+    <para id="x_40d">The process is a little involved.</para>
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_40e">To begin, <command role="hg-cmd" moreinfo="none">hg qpush
+	    -a</command> all of your patches on top of the revision
+	  where you know that they apply cleanly.</para>
+      </listitem>
+      <listitem><para id="x_40f">Save a backup copy of your patch directory using
+	  <command role="hg-cmd" moreinfo="none">hg qsave <option role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>.
+	  This prints the name of the directory that it has saved the
+	  patches in.  It will save the patches to a directory called
+	  <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>, where
+	  <literal moreinfo="none">N</literal> is a small integer.  It also commits a
+	  <quote>save changeset</quote> on top of your applied
+	  patches; this is for internal book-keeping, and records the
+	  states of the <filename role="special" moreinfo="none">series</filename> and
+	  <filename role="special" moreinfo="none">status</filename> files.</para>
+      </listitem>
+      <listitem><para id="x_410">Use <command role="hg-cmd" moreinfo="none">hg pull</command> to
+	  bring new changes into the underlying repository.  (Don't
+	  run <command role="hg-cmd" moreinfo="none">hg pull -u</command>; see below
+	  for why.)</para>
+      </listitem>
+      <listitem><para id="x_411">Update to the new tip revision, using <command role="hg-cmd" moreinfo="none">hg update <option role="hg-opt-update">-C</option></command> to override
+	  the patches you have pushed.</para>
+      </listitem>
+      <listitem><para id="x_412">Merge all patches using <command moreinfo="none">hg qpush -m
+	    -a</command>.  The <option role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
+	  <command role="hg-ext-mq" moreinfo="none">qpush</command> tells MQ to
+	  perform a three-way merge if the patch fails to
+	  apply.</para>
+      </listitem></orderedlist>
+
+    <para id="x_413">During the <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>,
+      each patch in the <filename role="special" moreinfo="none">series</filename>
+      file is applied normally.  If a patch applies with fuzz or
+      rejects, MQ looks at the queue you <command role="hg-ext-mq" moreinfo="none">qsave</command>d, and performs a three-way
+      merge with the corresponding changeset.  This merge uses
+      Mercurial's normal merge machinery, so it may pop up a GUI merge
+      tool to help you to resolve problems.</para>
+
+    <para id="x_414">When you finish resolving the effects of a patch, MQ
+      refreshes your patch based on the result of the merge.</para>
+
+    <para id="x_415">At the end of this process, your repository will have one
+      extra head from the old patch queue, and a copy of the old patch
+      queue will be in <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>. You can remove the
+      extra head using <command role="hg-cmd" moreinfo="none">hg qpop -a -n
+	patches.N</command> or <command role="hg-cmd" moreinfo="none">hg
+	strip</command>.  You can delete <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename> once you are sure
+      that you no longer need it as a backup.</para>
+  </sect1>
+
+  <sect1>
+    <title>Identifying patches</title>
+
+    <para id="x_416">MQ commands that work with patches let you refer to a patch
+      either by using its name or by a number.  By name is obvious
+      enough; pass the name <filename moreinfo="none">foo.patch</filename> to <command role="hg-ext-mq" moreinfo="none">qpush</command>, for example, and it will
+      push patches until <filename moreinfo="none">foo.patch</filename> is
+      applied.</para>
+
+    <para id="x_417">As a shortcut, you can refer to a patch using both a name
+      and a numeric offset; <literal moreinfo="none">foo.patch-2</literal> means
+      <quote>two patches before <literal moreinfo="none">foo.patch</literal></quote>,
+      while <literal moreinfo="none">bar.patch+4</literal> means <quote>four patches
+	after <literal moreinfo="none">bar.patch</literal></quote>.</para>
+
+    <para id="x_418">Referring to a patch by index isn't much different.  The
+      first patch printed in the output of <command role="hg-ext-mq" moreinfo="none">qseries</command> is patch zero (yes, it's
+      one of those start-at-zero counting systems); the second is
+      patch one; and so on.</para>
+
+    <para id="x_419">MQ also makes it easy to work with patches when you are
+      using normal Mercurial commands.  Every command that accepts a
+      changeset ID will also accept the name of an applied patch.  MQ
+      augments the tags normally in the repository with an eponymous
+      one for each applied patch.  In addition, the special tags
+      <literal role="tag" moreinfo="none">qbase</literal> and
+      <literal role="tag" moreinfo="none">qtip</literal> identify
+      the <quote>bottom-most</quote> and topmost applied patches,
+      respectively.</para>
+
+    <para id="x_41a">These additions to Mercurial's normal tagging capabilities
+      make dealing with patches even more of a breeze.</para>
+    <itemizedlist>
+      <listitem><para id="x_41b">Want to patchbomb a mailing list with your
+	  latest series of changes?</para>
+	<programlisting format="linespecific">hg email qbase:qtip</programlisting>
+	<para id="x_41c">  (Don't know what <quote>patchbombing</quote> is?  See
+	  <xref linkend="sec:hgext:patchbomb"/>.)</para>
+      </listitem>
+      <listitem><para id="x_41d">Need to see all of the patches since
+	  <literal moreinfo="none">foo.patch</literal> that have touched files in a
+	  subdirectory of your tree?</para>
+	<programlisting format="linespecific">hg log -r foo.patch:qtip subdir</programlisting>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_41e">Because MQ makes the names of patches available to the rest
+      of Mercurial through its normal internal tag machinery, you
+      don't need to type in the entire name of a patch when you want
+      to identify it by name.</para>
+
+    <para id="x_41f">Another nice consequence of representing patch names as tags
+      is that when you run the <command role="hg-cmd" moreinfo="none">hg log</command>
+      command, it will display a patch's name as a tag, simply as part
+      of its normal output.  This makes it easy to visually
+      distinguish applied patches from underlying
+      <quote>normal</quote> revisions.  The following example shows a
+      few normal Mercurial commands in use with applied
+      patches.</para>
+
+    <!-- BEGIN mq.id.output -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
+first.patch
+second.patch
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r qbase:qtip</userinput>
+changeset:   1:c3bcf3b7335a
+tag:         first.patch
+tag:         qbase
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:08 2009 +0000
+summary:     [mq]: first.patch
+
+changeset:   2:d189ba63b5f7
+tag:         qtip
+tag:         second.patch
+tag:         tip
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:09 2009 +0000
+summary:     [mq]: second.patch
+
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg export second.patch</userinput>
+# HG changeset patch
+# User Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+# Date 1250431509 0
+# Node ID d189ba63b5f7427f9644663c01fc16fe80399c65
+# Parent  c3bcf3b7335afc0a250e85c51a1266d35d43a545
+[mq]: second.patch
+
+diff -r c3bcf3b7335a -r d189ba63b5f7 other.c
+--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
++++ b/other.c	Sun Aug 16 14:05:09 2009 +0000
+@@ -0,0 +1,1 @@
++double u;
+</screen>
+<!-- END mq.id.output -->
+
+  </sect1>
+
+  <sect1>
+    <title>Useful things to know about</title>
+
+    <para id="x_420">There are a number of aspects of MQ usage that don't fit
+      tidily into sections of their own, but that are good to know.
+      Here they are, in one place.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_421">Normally, when you <command role="hg-ext-mq" moreinfo="none">qpop</command> a patch and <command role="hg-ext-mq" moreinfo="none">qpush</command> it again, the changeset
+	  that represents the patch after the pop/push will have a
+	  <emphasis>different identity</emphasis> than the changeset
+	  that represented the hash beforehand.  See <xref linkend="sec:mqref:cmd:qpush"/> for
+	  information as to why this is.</para>
+      </listitem>
+      <listitem><para id="x_422">It's not a good idea to <command role="hg-cmd" moreinfo="none">hg merge</command> changes from another
+	  branch with a patch changeset, at least if you want to
+	  maintain the <quote>patchiness</quote> of that changeset and
+	  changesets below it on the patch stack.  If you try to do
+	  this, it will appear to succeed, but MQ will become
+	  confused.</para>
+      </listitem></itemizedlist>
+  </sect1>
+
+  <sect1 id="sec:mq:repo">
+    <title>Managing patches in a repository</title>
+
+    <para id="x_423">Because MQ's <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory resides
+      outside a Mercurial repository's working directory, the
+      <quote>underlying</quote> Mercurial repository knows nothing
+      about the management or presence of patches.</para>
+
+    <para id="x_424">This presents the interesting possibility of managing the
+      contents of the patch directory as a Mercurial repository in its
+      own right.  This can be a useful way to work.  For example, you
+      can work on a patch for a while, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> it, then <command role="hg-cmd" moreinfo="none">hg commit</command> the current state of the
+      patch.  This lets you <quote>roll back</quote> to that version
+      of the patch later on.</para>
+
+    <para id="x_425">You can then share different versions of the same patch
+      stack among multiple underlying repositories.  I use this when I
+      am developing a Linux kernel feature.  I have a pristine copy of
+      my kernel sources for each of several CPU architectures, and a
+      cloned repository under each that contains the patches I am
+      working on.  When I want to test a change on a different
+      architecture, I push my current patches to the patch repository
+      associated with that kernel tree, pop and push all of my
+      patches, and build and test that kernel.</para>
+
+    <para id="x_426">Managing patches in a repository makes it possible for
+      multiple developers to work on the same patch series without
+      colliding with each other, all on top of an underlying source
+      base that they may or may not control.</para>
+
+    <sect2>
+      <title>MQ support for patch repositories</title>
+
+      <para id="x_427">MQ helps you to work with the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
+	repository; when you prepare a repository for working with
+	patches using <command role="hg-ext-mq" moreinfo="none">qinit</command>, you
+	can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
+	  -c</option> option to create the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
+	Mercurial repository.</para>
+
+      <note>
+	<para id="x_428">  If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
+	  can simply go into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory at any
+	  time and run <command role="hg-cmd" moreinfo="none">hg init</command>.
+	  Don't forget to add an entry for the <filename role="special" moreinfo="none">status</filename> file to the <filename role="special" moreinfo="none">.hgignore</filename> file, though</para>
+
+	<para id="x_429">  (<command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
+	  does this for you automatically); you
+	  <emphasis>really</emphasis> don't want to manage the
+	  <filename role="special" moreinfo="none">status</filename> file.</para>
+      </note>
+
+      <para id="x_42a">As a convenience, if MQ notices that the <filename class="directory" moreinfo="none">.hg/patches</filename> directory is a
+	repository, it will automatically <command role="hg-cmd" moreinfo="none">hg
+	  add</command> every patch that you create and import.</para>
+
+      <para id="x_42b">MQ provides a shortcut command, <command role="hg-ext-mq" moreinfo="none">qcommit</command>, that runs <command role="hg-cmd" moreinfo="none">hg commit</command> in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
+	directory.  This saves some bothersome typing.</para>
+
+      <para id="x_42c">Finally, as a convenience to manage the patch directory,
+	you can define the alias <command moreinfo="none">mq</command> on Unix
+	systems. For example, on Linux systems using the
+	<command moreinfo="none">bash</command> shell, you can include the following
+	snippet in your <filename role="home" moreinfo="none">~/.bashrc</filename>.</para>
+
+      <programlisting format="linespecific">alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
+
+      <para id="x_42d">You can then issue commands of the form <command moreinfo="none">mq
+	  pull</command> from the main repository.</para>
+    </sect2>
+
+    <sect2>
+      <title>A few things to watch out for</title>
+
+      <para id="x_42e">MQ's support for working with a repository full of patches
+	is limited in a few small respects.</para>
+
+      <para id="x_42f">MQ cannot automatically detect changes that you make to
+	the patch directory.  If you <command role="hg-cmd" moreinfo="none">hg
+	  pull</command>, manually edit, or <command role="hg-cmd" moreinfo="none">hg
+	  update</command> changes to patches or the <filename role="special" moreinfo="none">series</filename> file, you will have to
+	<command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
+	then <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
+	the underlying repository to see those changes show up there.
+	If you forget to do this, you can confuse MQ's idea of which
+	patches are applied.</para>
+
+    </sect2>
+  </sect1>
+  <sect1 id="sec:mq:tools">
+    <title>Third party tools for working with patches</title>
+
+    <para id="x_430">Once you've been working with patches for a while, you'll
+      find yourself hungry for tools that will help you to understand
+      and manipulate the patches you're dealing with.</para>
+
+    <para id="x_431">The <command moreinfo="none">diffstat</command> command
+      <citation>web:diffstat</citation> generates a histogram of the
+      modifications made to each file in a patch.  It provides a good
+      way to <quote>get a sense of</quote> a patch—which files
+      it affects, and how much change it introduces to each file and
+      as a whole.  (I find that it's a good idea to use
+      <command moreinfo="none">diffstat</command>'s <option role="cmd-opt-diffstat">-p</option> option as a matter of
+      course, as otherwise it will try to do clever things with
+      prefixes of file names that inevitably confuse at least
+      me.)</para>
+
+<!-- BEGIN mq.tools.tools -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diffstat -p1 remove-redundant-null-checks.patch</userinput>
+ drivers/char/agp/sgi-agp.c        |    5 ++---
+ drivers/char/hvcs.c               |   11 +++++------
+ drivers/message/fusion/mptfc.c    |    6 ++----
+ drivers/message/fusion/mptsas.c   |    3 +--
+ drivers/net/fs_enet/fs_enet-mii.c |    3 +--
+ drivers/net/wireless/ipw2200.c    |   22 ++++++----------------
+ drivers/scsi/libata-scsi.c        |    4 +---
+ drivers/video/au1100fb.c          |    3 +--
+ 8 files changed, 19 insertions(+), 38 deletions(-)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">filterdiff -i '*/video/*' remove-redundant-null-checks.patch</userinput>
+--- a/drivers/video/au1100fb.c~remove-redundant-null-checks-before-free-in-drivers
++++ a/drivers/video/au1100fb.c
+@@ -743,8 +743,7 @@ void __exit au1100fb_cleanup(void)
+ {
+ 	driver_unregister(&amp;au1100fb_driver);
+ 
+-	if (drv_info.opt_mode)
+-		kfree(drv_info.opt_mode);
++	kfree(drv_info.opt_mode);
+ }
+ 
+ module_init(au1100fb_init);
+</screen>
+<!-- END mq.tools.tools -->
+
+
+    <para id="x_432">The <literal role="package" moreinfo="none">patchutils</literal> package
+      <citation>web:patchutils</citation> is invaluable. It provides a
+      set of small utilities that follow the <quote>Unix
+	philosophy;</quote> each does one useful thing with a patch.
+      The <literal role="package" moreinfo="none">patchutils</literal> command I use
+      most is <command moreinfo="none">filterdiff</command>, which extracts subsets
+      from a patch file.  For example, given a patch that modifies
+      hundreds of files across dozens of directories, a single
+      invocation of <command moreinfo="none">filterdiff</command> can generate a
+      smaller patch that only touches files whose names match a
+      particular glob pattern.  See <xref linkend="mq-collab:tips:interdiff"/> for another
+      example.</para>
+
+  </sect1>
+  <sect1>
+    <title>Good ways to work with patches</title>
+
+    <para id="x_433">Whether you are working on a patch series to submit to a
+      free software or open source project, or a series that you
+      intend to treat as a sequence of regular changesets when you're
+      done, you can use some simple techniques to keep your work well
+      organized.</para>
+
+    <para id="x_434">Give your patches descriptive names.  A good name for a
+      patch might be <filename moreinfo="none">rework-device-alloc.patch</filename>,
+      because it will immediately give you a hint what the purpose of
+      the patch is.  Long names shouldn't be a problem; you won't be
+      typing the names often, but you <emphasis>will</emphasis> be
+      running commands like <command role="hg-ext-mq" moreinfo="none">qapplied</command> and <command role="hg-ext-mq" moreinfo="none">qtop</command> over and over. Good naming
+      becomes especially important when you have a number of patches
+      to work with, or if you are juggling a number of different tasks
+      and your patches only get a fraction of your attention.</para>
+
+    <para id="x_435">Be aware of what patch you're working on.  Use the <command role="hg-ext-mq" moreinfo="none">qtop</command> command and skim over the text
+      of your patches frequently—for example, using <command role="hg-cmd" moreinfo="none">hg tip <option role="hg-opt-tip">-p</option></command>)—to be sure
+      of where you stand.  I have several times worked on and <command role="hg-ext-mq" moreinfo="none">qrefresh</command>ed a patch other than the
+      one I intended, and it's often tricky to migrate changes into
+      the right patch after making them in the wrong one.</para>
+
+    <para id="x_436">For this reason, it is very much worth investing a little
+      time to learn how to use some of the third-party tools I
+      described in <xref linkend="sec:mq:tools"/>,
+      particularly
+      <command moreinfo="none">diffstat</command> and <command moreinfo="none">filterdiff</command>.
+      The former will give you a quick idea of what changes your patch
+      is making, while the latter makes it easy to splice hunks
+      selectively out of one patch and into another.</para>
+
+  </sect1>
+  <sect1>
+    <title>MQ cookbook</title>
+
+    <sect2>
+      <title>Manage <quote>trivial</quote> patches</title>
+
+      <para id="x_437">Because the overhead of dropping files into a new
+	Mercurial repository is so low, it makes a lot of sense to
+	manage patches this way even if you simply want to make a few
+	changes to a source tarball that you downloaded.</para>
+
+      <para id="x_438">Begin by downloading and unpacking the source tarball, and
+	turning it into a Mercurial repository.</para>
+
+      <!-- BEGIN mq.tarball.download -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.5.tar.bz2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.5.tar.bz2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.5</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -q --addremove --message netplug-1.2.5</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug</userinput>
+updating working directory
+18 files updated, 0 files merged, 0 files removed, 0 files unresolved
+</screen>
+<!-- END mq.tarball.download -->
+
+
+      <para id="x_439">Continue by creating a patch stack and making your
+	changes.</para>
+
+      <!-- BEGIN mq.tarball.qinit -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -m 'fix build problem with gcc 4' build-fix.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">perl -pi -e 's/int addr_len/socklen_t addr_len/' netlink.c</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -p</userinput>
+changeset:   1:eeab56666c54
+tag:         qtip
+tag:         build-fix.patch
+tag:         tip
+tag:         qbase
+user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
+date:        Sun Aug 16 14:05:10 2009 +0000
+summary:     fix build problem with gcc 4
+
+diff -r 1f6afe9a2d68 -r eeab56666c54 netlink.c
+--- a/netlink.c	Sun Aug 16 14:05:09 2009 +0000
++++ b/netlink.c	Sun Aug 16 14:05:10 2009 +0000
+@@ -275,7 +275,7 @@
+         exit(1);
+     }
+ 
+-    int addr_len = sizeof(addr);
++    socklen_t addr_len = sizeof(addr);
+ 
+     if (getsockname(fd, (struct sockaddr *) &amp;addr, &amp;addr_len) == -1) {
+         do_log(LOG_ERR, "Could not get socket details: %m");
+
+</screen>
+<!-- END mq.tarball.qinit -->
+
+
+      <para id="x_43a">Let's say a few weeks or months pass, and your package
+	author releases a new version.  First, bring their changes
+	into the repository.</para>
+
+      <!-- BEGIN mq.tarball.newsource -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
+patch queue now empty
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.8.tar.bz2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug-1.2.8</userinput>
+updating working directory
+18 files updated, 0 files merged, 0 files removed, 0 files unresolved
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg locate -0 | xargs -0 rm</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.8.tar.bz2</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit --addremove --message netplug-1.2.8</userinput>
+</screen>
+<!-- END mq.tarball.newsource -->
+
+
+      <para id="x_43b">The pipeline starting with <command role="hg-cmd" moreinfo="none">hg
+	  locate</command> above deletes all files in the working
+	directory, so that <command role="hg-cmd" moreinfo="none">hg
+	  commit</command>'s <option role="hg-opt-commit">--addremove</option> option can
+	actually tell which files have really been removed in the
+	newer version of the source.</para>
+
+      <para id="x_43c">Finally, you can apply your patches on top of the new
+	tree.</para>
+
+      <!-- BEGIN mq.tarball.repush -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../netplug</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../netplug-1.2.8</userinput>
+pulling from ../netplug-1.2.8
+searching for changes
+adding changesets
+adding manifests
+adding file changes
+added 1 changesets with 12 changes to 12 files
+(run 'hg update' to get a working copy)
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
+(working directory not at tip)
+applying build-fix.patch
+now at: build-fix.patch
+</screen>
+<!-- END mq.tarball.repush -->
+
+    </sect2>
+
+    <sect2 id="sec:mq:combine">
+      <title>Combining entire patches</title>
+
+      <para id="x_43d">MQ provides a command, <command role="hg-ext-mq" moreinfo="none">qfold</command> that lets you combine
+	entire patches.  This <quote>folds</quote> the patches you
+	name, in the order you name them, into the topmost applied
+	patch, and concatenates their descriptions onto the end of its
+	description.  The patches that you fold must be unapplied
+	before you fold them.</para>
+
+      <para id="x_43e">The order in which you fold patches matters.  If your
+	topmost applied patch is <literal moreinfo="none">foo</literal>, and you
+	<command role="hg-ext-mq" moreinfo="none">qfold</command>
+	<literal moreinfo="none">bar</literal> and <literal moreinfo="none">quux</literal> into it,
+	you will end up with a patch that has the same effect as if
+	you applied first <literal moreinfo="none">foo</literal>, then
+	<literal moreinfo="none">bar</literal>, followed by
+	<literal moreinfo="none">quux</literal>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Merging part of one patch into another</title>
+
+      <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
+	another is more difficult than combining entire
+	patches.</para>
+
+      <para id="x_440">If you want to move changes to entire files, you can use
+	<command moreinfo="none">filterdiff</command>'s <option role="cmd-opt-filterdiff">-i</option> and <option role="cmd-opt-filterdiff">-x</option> options to choose the
+	modifications to snip out of one patch, concatenating its
+	output onto the end of the patch you want to merge into.  You
+	usually won't need to modify the patch you've merged the
+	changes from.  Instead, MQ will report some rejected hunks
+	when you <command role="hg-ext-mq" moreinfo="none">qpush</command> it (from
+	the hunks you moved into the other patch), and you can simply
+	<command role="hg-ext-mq" moreinfo="none">qrefresh</command> the patch to drop
+	the duplicate hunks.</para>
+
+      <para id="x_441">If you have a patch that has multiple hunks modifying a
+	file, and you only want to move a few of those hunks, the job
+	becomes more messy, but you can still partly automate it.  Use
+	<command moreinfo="none">lsdiff -nvv</command> to print some metadata about
+	the patch.</para>
+
+      <!-- BEGIN mq.tools.lsdiff -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">lsdiff -nvv remove-redundant-null-checks.patch</userinput>
+22	File #1  	a/drivers/char/agp/sgi-agp.c
+	24	Hunk #1	static int __devinit agp_sgi_init(void)
+37	File #2  	a/drivers/char/hvcs.c
+	39	Hunk #1	static struct tty_operations hvcs_ops = 
+	53	Hunk #2	static int hvcs_alloc_index_list(int n)
+69	File #3  	a/drivers/message/fusion/mptfc.c
+	71	Hunk #1	mptfc_GetFcDevPage0(MPT_ADAPTER *ioc, in
+85	File #4  	a/drivers/message/fusion/mptsas.c
+	87	Hunk #1	mptsas_probe_hba_phys(MPT_ADAPTER *ioc)
+98	File #5  	a/drivers/net/fs_enet/fs_enet-mii.c
+	100	Hunk #1	static struct fs_enet_mii_bus *create_bu
+111	File #6  	a/drivers/net/wireless/ipw2200.c
+	113	Hunk #1	static struct ipw_fw_error *ipw_alloc_er
+	126	Hunk #2	static ssize_t clear_error(struct device
+	140	Hunk #3	static void ipw_irq_tasklet(struct ipw_p
+	150	Hunk #4	static void ipw_pci_remove(struct pci_de
+164	File #7  	a/drivers/scsi/libata-scsi.c
+	166	Hunk #1	int ata_cmd_ioctl(struct scsi_device *sc
+178	File #8  	a/drivers/video/au1100fb.c
+	180	Hunk #1	void __exit au1100fb_cleanup(void)
+</screen>
+<!-- END mq.tools.lsdiff -->
+
+
+      <para id="x_442">This command prints three different kinds of
+	number:</para>
+      <itemizedlist>
+	<listitem><para id="x_443">(in the first column) a <emphasis>file
+	      number</emphasis> to identify each file modified in the
+	    patch;</para>
+	</listitem>
+	<listitem><para id="x_444">(on the next line, indented) the line number
+	    within a modified file where a hunk starts; and</para>
+	</listitem>
+	<listitem><para id="x_445">(on the same line) a <emphasis>hunk
+	      number</emphasis> to identify that hunk.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_446">You'll have to use some visual inspection, and reading of
+	the patch, to identify the file and hunk numbers you'll want,
+	but you can then pass them to to
+	<command moreinfo="none">filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option> and <option role="cmd-opt-filterdiff">--hunks</option> options, to
+	select exactly the file and hunk you want to extract.</para>
+
+      <para id="x_447">Once you have this hunk, you can concatenate it onto the
+	end of your destination patch and continue with the remainder
+	of <xref linkend="sec:mq:combine"/>.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Differences between quilt and MQ</title>
+
+    <para id="x_448">If you are already familiar with quilt, MQ provides a
+      similar command set.  There are a few differences in the way
+      that it works.</para>
+
+    <para id="x_449">You will already have noticed that most quilt commands have
+      MQ counterparts that simply begin with a
+      <quote><literal moreinfo="none">q</literal></quote>.  The exceptions are quilt's
+      <literal moreinfo="none">add</literal> and <literal moreinfo="none">remove</literal> commands,
+      the counterparts for which are the normal Mercurial <command role="hg-cmd" moreinfo="none">hg add</command> and <command role="hg-cmd" moreinfo="none">hg
+	remove</command> commands.  There is no MQ equivalent of the
+      quilt <literal moreinfo="none">edit</literal> command.</para>
+
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch13 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:mq-collab">
+  <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?>
+  <title>Advanced uses of Mercurial Queues</title>
+
+  <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial
+    Queues, use of a little discipline and some of MQ's less
+    frequently used capabilities makes it possible to work in
+    complicated development environments.</para>
+
+  <para id="x_15e">In this chapter, I will use as an example a technique I have
+    used to manage the development of an Infiniband device driver for
+    the Linux kernel.  The driver in question is large (at least as
+    drivers go), with 25,000 lines of code spread across 35 source
+    files.  It is maintained by a small team of developers.</para>
+
+  <para id="x_15f">While much of the material in this chapter is specific to
+    Linux, the same principles apply to any code base for which you're
+    not the primary owner, and upon which you need to do a lot of
+    development.</para>
+
+  <sect1>
+    <title>The problem of many targets</title>
+
+    <para id="x_160">The Linux kernel changes rapidly, and has never been
+      internally stable; developers frequently make drastic changes
+      between releases. This means that a version of the driver that
+      works well with a particular released version of the kernel will
+      not even <emphasis>compile</emphasis> correctly against,
+      typically, any other version.</para>
+
+    <para id="x_161">To maintain a driver, we have to keep a number of distinct
+      versions of Linux in mind.</para>
+    <itemizedlist>
+      <listitem><para id="x_162">One target is the main Linux kernel development
+	  tree. Maintenance of the code is in this case partly shared
+	  by other developers in the kernel community, who make
+	  <quote>drive-by</quote> modifications to the driver as they
+	  develop and refine kernel subsystems.</para>
+      </listitem>
+      <listitem><para id="x_163">We also maintain a number of
+	  <quote>backports</quote> to older versions of the Linux
+	  kernel, to support the needs of customers who are running
+	  older Linux distributions that do not incorporate our
+	  drivers.  (To <emphasis>backport</emphasis> a piece of code
+	  is to modify it to work in an older version of its target
+	  environment than the version it was developed for.)</para>
+      </listitem>
+      <listitem><para id="x_164">Finally, we make software releases on a schedule
+	  that is necessarily not aligned with those used by Linux
+	  distributors and kernel developers, so that we can deliver
+	  new features to customers without forcing them to upgrade
+	  their entire kernels or distributions.</para>
+      </listitem></itemizedlist>
+
+    <sect2>
+      <title>Tempting approaches that don't work well</title>
+
+      <para id="x_165">There are two <quote>standard</quote> ways to maintain a
+	piece of software that has to target many different
+	environments.</para>
+
+      <para id="x_166">The first is to maintain a number of branches, each
+	intended for a single target.  The trouble with this approach
+	is that you must maintain iron discipline in the flow of
+	changes between repositories. A new feature or bug fix must
+	start life in a <quote>pristine</quote> repository, then
+	percolate out to every backport repository.  Backport changes
+	are more limited in the branches they should propagate to; a
+	backport change that is applied to a branch where it doesn't
+	belong will probably stop the driver from compiling.</para>
+
+      <para id="x_167">The second is to maintain a single source tree filled with
+	conditional statements that turn chunks of code on or off
+	depending on the intended target.  Because these
+	<quote>ifdefs</quote> are not allowed in the Linux kernel
+	tree, a manual or automatic process must be followed to strip
+	them out and yield a clean tree.  A code base maintained in
+	this fashion rapidly becomes a rat's nest of conditional
+	blocks that are difficult to understand and maintain.</para>
+
+      <para id="x_168">Neither of these approaches is well suited to a situation
+	where you don't <quote>own</quote> the canonical copy of a
+	source tree.  In the case of a Linux driver that is
+	distributed with the standard kernel, Linus's tree contains
+	the copy of the code that will be treated by the world as
+	canonical.  The upstream version of <quote>my</quote> driver
+	can be modified by people I don't know, without me even
+	finding out about it until after the changes show up in
+	Linus's tree.</para>
+
+      <para id="x_169">These approaches have the added weakness of making it
+	difficult to generate well-formed patches to submit
+	upstream.</para>
+
+      <para id="x_16a">In principle, Mercurial Queues seems like a good candidate
+	to manage a development scenario such as the above.  While
+	this is indeed the case, MQ contains a few added features that
+	make the job more pleasant.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Conditionally applying patches with guards</title>
+
+    <para id="x_16b">Perhaps the best way to maintain sanity with so many targets
+      is to be able to choose specific patches to apply for a given
+      situation.  MQ provides a feature called <quote>guards</quote>
+      (which originates with quilt's <literal moreinfo="none">guards</literal>
+      command) that does just this.  To start off, let's create a
+      simple repository for experimenting in.</para>
+
+    <!-- BEGIN mq.guards.init -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew hello.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello &gt; hello</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add hello</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew goodbye.patch</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye &gt; goodbye</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add goodbye</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
+</screen>
+<!-- END mq.guards.init -->
+
+
+    <para id="x_16c">This gives us a tiny repository that contains two patches
+      that don't have any dependencies on each other, because they
+      touch different files.</para>
+
+    <para id="x_16d">The idea behind conditional application is that you can
+      <quote>tag</quote> a patch with a <emphasis>guard</emphasis>,
+      which is simply a text string of your choosing, then tell MQ to
+      select specific guards to use when applying patches.  MQ will
+      then either apply, or skip over, a guarded patch, depending on
+      the guards that you have selected.</para>
+
+    <para id="x_16e">A patch can have an arbitrary number of guards; each one is
+      <emphasis>positive</emphasis> (<quote>apply this patch if this
+	guard is selected</quote>) or <emphasis>negative</emphasis>
+      (<quote>skip this patch if this guard is selected</quote>).  A
+      patch with no guards is always applied.</para>
+
+  </sect1>
+  <sect1>
+    <title>Controlling the guards on a patch</title>
+
+    <para id="x_16f">The <command role="hg-ext-mq" moreinfo="none">qguard</command> command lets
+      you determine which guards should apply to a patch, or display
+      the guards that are already in effect. Without any arguments, it
+      displays the guards on the current topmost patch.</para>
+
+      <!-- BEGIN mq.guards.qguard -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
+goodbye.patch: unguarded
+</screen>
+<!-- END mq.guards.qguard -->
+
+
+    <para id="x_170">To set a positive guard on a patch, prefix the name of the
+      guard with a <quote><literal moreinfo="none">+</literal></quote>.</para>
+
+      <!-- BEGIN mq.guards.qguard.pos -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard +foo</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
+goodbye.patch: +foo
+</screen>
+<!-- END mq.guards.qguard.pos -->
+
+
+    <para id="x_171">To set a negative guard
+      on a patch, prefix the name of the guard with a
+      <quote><literal moreinfo="none">-</literal></quote>.</para>
+
+    <!-- BEGIN mq.guards.qguard.neg -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard -- hello.patch -quux</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard hello.patch</userinput>
+hello.patch: -quux
+</screen>
+<!-- END mq.guards.qguard.neg -->
+
+
+    <para id="x_74a">Notice that we prefixed the arguments to the <command moreinfo="none">hg
+	qguard</command> command with a <literal moreinfo="none">--</literal> here, so
+      that Mercurial would not interpret the text
+      <literal moreinfo="none">-quux</literal> as an option.</para>
+
+    <note>
+      <title>Setting vs. modifying</title>
+
+      <para id="x_172">  The <command role="hg-ext-mq" moreinfo="none">qguard</command> command
+	<emphasis>sets</emphasis> the guards on a patch; it doesn't
+	<emphasis>modify</emphasis> them.  What this means is that if
+	you run <command role="hg-cmd" moreinfo="none">hg qguard +a +b</command> on a
+	patch, then <command role="hg-cmd" moreinfo="none">hg qguard +c</command> on
+	the same patch, the <emphasis>only</emphasis> guard that will
+	be set on it afterwards is <literal moreinfo="none">+c</literal>.</para>
+    </note>
+
+    <para id="x_173">Mercurial stores guards in the <filename role="special" moreinfo="none">series</filename> file; the form in which they
+      are stored is easy both to understand and to edit by hand. (In
+      other words, you don't have to use the <command role="hg-ext-mq" moreinfo="none">qguard</command> command if you don't want
+      to; it's okay to simply edit the <filename role="special" moreinfo="none">series</filename> file.)</para>
+
+    <!-- BEGIN mq.guards.series -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/series</userinput>
+hello.patch #-quux
+goodbye.patch #+foo
+</screen>
+<!-- END mq.guards.series -->
+
+
+  </sect1>
+  <sect1>
+    <title>Selecting the guards to use</title>
+
+    <para id="x_174">The <command role="hg-ext-mq" moreinfo="none">qselect</command> command
+      determines which guards are active at a given time.  The effect
+      of this is to determine which patches MQ will apply the next
+      time you run <command role="hg-ext-mq" moreinfo="none">qpush</command>.  It has
+      no other effect; in particular, it doesn't do anything to
+      patches that are already applied.</para>
+
+    <para id="x_175">With no arguments, the <command role="hg-ext-mq" moreinfo="none">qselect</command> command lists the guards
+      currently in effect, one per line of output.  Each argument is
+      treated as the name of a guard to apply.</para>
+
+      <!-- BEGIN mq.guards.qselect.foo -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
+patch queue now empty
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
+no active guards
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo</userinput>
+number of unguarded, unapplied patches has changed from 1 to 2
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
+foo
+</screen>
+<!-- END mq.guards.qselect.foo -->
+
+
+    <para id="x_176">In case you're interested, the currently selected guards are
+      stored in the <filename role="special" moreinfo="none">guards</filename> file.</para>
+
+    <!-- BEGIN mq.guards.qselect.cat -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/guards</userinput>
+foo
+</screen>
+<!-- END mq.guards.qselect.cat -->
+
+
+    <para id="x_177">We can see the effect the selected guards have when we run
+      <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
+
+    <!-- BEGIN mq.guards.qselect.qpush -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
+applying hello.patch
+applying goodbye.patch
+now at: goodbye.patch
+</screen>
+<!-- END mq.guards.qselect.qpush -->
+
+
+    <para id="x_178">A guard cannot start with a
+      <quote><literal moreinfo="none">+</literal></quote> or
+      <quote><literal moreinfo="none">-</literal></quote> character.  The name of a
+      guard must not contain white space, but most other characters
+      are acceptable.  If you try to use a guard with an invalid name,
+      MQ will complain:</para>
+
+    <!-- BEGIN mq.guards.qselect.error -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect +foo</userinput>
+abort: guard '+foo' starts with invalid character: '+'
+</screen>
+<!-- END mq.guards.qselect.error -->
+
+      
+    <para id="x_179">Changing the selected guards changes the patches that are
+      applied.</para>
+
+    <!-- BEGIN mq.guards.qselect.quux -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect quux</userinput>
+number of guarded, applied patches has changed from 0 to 2
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
+patch queue now empty
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
+patch series already fully applied
+</screen>
+<!-- END mq.guards.qselect.quux -->
+
+
+    <para id="x_17a">You can see in the example below that negative guards take
+      precedence over positive guards.</para>
+
+    <!-- BEGIN mq.guards.qselect.foobar -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo bar</userinput>
+number of unguarded, unapplied patches has changed from 0 to 2
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
+no patches applied
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
+applying hello.patch
+applying goodbye.patch
+now at: goodbye.patch
+</screen>
+<!-- END mq.guards.qselect.foobar -->
+
+
+  </sect1>
+  <sect1>
+    <title>MQ's rules for applying patches</title>
+
+    <para id="x_17b">The rules that MQ uses when deciding whether to apply a
+      patch are as follows.</para>
+    <itemizedlist>
+      <listitem><para id="x_17c">A patch that has no guards is always
+	  applied.</para>
+      </listitem>
+      <listitem><para id="x_17d">If the patch has any negative guard that matches
+	  any currently selected guard, the patch is skipped.</para>
+      </listitem>
+      <listitem><para id="x_17e">If the patch has any positive guard that matches
+	  any currently selected guard, the patch is applied.</para>
+      </listitem>
+      <listitem><para id="x_17f">If the patch has positive or negative guards,
+	  but none matches any currently selected guard, the patch is
+	  skipped.</para>
+      </listitem></itemizedlist>
+
+  </sect1>
+  <sect1>
+    <title>Trimming the work environment</title>
+
+    <para id="x_180">In working on the device driver I mentioned earlier, I don't
+      apply the patches to a normal Linux kernel tree.  Instead, I use
+      a repository that contains only a snapshot of the source files
+      and headers that are relevant to Infiniband development.  This
+      repository is 1% the size of a kernel repository, so it's easier
+      to work with.</para>
+
+    <para id="x_181">I then choose a <quote>base</quote> version on top of which
+      the patches are applied.  This is a snapshot of the Linux kernel
+      tree as of a revision of my choosing.  When I take the snapshot,
+      I record the changeset ID from the kernel repository in the
+      commit message.  Since the snapshot preserves the
+      <quote>shape</quote> and content of the relevant parts of the
+      kernel tree, I can apply my patches on top of either my tiny
+      repository or a normal kernel tree.</para>
+
+    <para id="x_182">Normally, the base tree atop which the patches apply should
+      be a snapshot of a very recent upstream tree.  This best
+      facilitates the development of patches that can easily be
+      submitted upstream with few or no modifications.</para>
+
+  </sect1>
+  <sect1>
+    <title>Dividing up the <filename role="special" moreinfo="none">series</filename>
+      file</title>
+
+    <para id="x_183">I categorise the patches in the <filename role="special" moreinfo="none">series</filename> file into a number of logical
+      groups.  Each section of like patches begins with a block of
+      comments that describes the purpose of the patches that
+      follow.</para>
+
+    <para id="x_184">The sequence of patch groups that I maintain follows.  The
+      ordering of these groups is important; I'll describe why after I
+      introduce the groups.</para>
+    <itemizedlist>
+      <listitem><para id="x_185">The <quote>accepted</quote> group.  Patches that
+	  the development team has submitted to the maintainer of the
+	  Infiniband subsystem, and which he has accepted, but which
+	  are not present in the snapshot that the tiny repository is
+	  based on.  These are <quote>read only</quote> patches,
+	  present only to transform the tree into a similar state as
+	  it is in the upstream maintainer's repository.</para>
+      </listitem>
+      <listitem><para id="x_186">The <quote>rework</quote> group.  Patches that I
+	  have submitted, but that the upstream maintainer has
+	  requested modifications to before he will accept
+	  them.</para>
+      </listitem>
+      <listitem><para id="x_187">The <quote>pending</quote> group.  Patches that
+	  I have not yet submitted to the upstream maintainer, but
+	  which we have finished working on. These will be <quote>read
+	    only</quote> for a while.  If the upstream maintainer
+	  accepts them upon submission, I'll move them to the end of
+	  the <quote>accepted</quote> group.  If he requests that I
+	  modify any, I'll move them to the beginning of the
+	  <quote>rework</quote> group.</para>
+      </listitem>
+      <listitem><para id="x_188">The <quote>in progress</quote> group.  Patches
+	  that are actively being developed, and should not be
+	  submitted anywhere yet.</para>
+      </listitem>
+      <listitem><para id="x_189">The <quote>backport</quote> group.  Patches that
+	  adapt the source tree to older versions of the kernel
+	  tree.</para>
+      </listitem>
+      <listitem><para id="x_18a">The <quote>do not ship</quote> group.  Patches
+	  that for some reason should never be submitted upstream.
+	  For example, one such patch might change embedded driver
+	  identification strings to make it easier to distinguish, in
+	  the field, between an out-of-tree version of the driver and
+	  a version shipped by a distribution vendor.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_18b">Now to return to the reasons for ordering groups of patches
+      in this way.  We would like the lowest patches in the stack to
+      be as stable as possible, so that we will not need to rework
+      higher patches due to changes in context.  Putting patches that
+      will never be changed first in the <filename role="special" moreinfo="none">series</filename> file serves this
+      purpose.</para>
+
+    <para id="x_18c">We would also like the patches that we know we'll need to
+      modify to be applied on top of a source tree that resembles the
+      upstream tree as closely as possible.  This is why we keep
+      accepted patches around for a while.</para>
+
+    <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote>
+      patches float at the end of the <filename role="special" moreinfo="none">series</filename> file.  The backport patches
+      must be applied on top of all other patches, and the <quote>do
+	not ship</quote> patches might as well stay out of harm's
+      way.</para>
+
+  </sect1>
+  <sect1>
+    <title>Maintaining the patch series</title>
+
+    <para id="x_18e">In my work, I use a number of guards to control which
+      patches are to be applied.</para>
+
+    <itemizedlist>
+      <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with
+	  <literal moreinfo="none">accepted</literal>.  I enable this guard most of
+	  the time.  When I'm applying the patches on top of a tree
+	  where the patches are already present, I can turn this patch
+	  off, and the patches that follow it will apply
+	  cleanly.</para>
+      </listitem>
+      <listitem><para id="x_190">Patches that are <quote>finished</quote>, but
+	  not yet submitted, have no guards.  If I'm applying the
+	  patch stack to a copy of the upstream tree, I don't need to
+	  enable any guards in order to get a reasonably safe source
+	  tree.</para>
+      </listitem>
+      <listitem><para id="x_191">Those patches that need reworking before being
+	  resubmitted are guarded with
+	  <literal moreinfo="none">rework</literal>.</para>
+      </listitem>
+      <listitem><para id="x_192">For those patches that are still under
+	  development, I use <literal moreinfo="none">devel</literal>.</para>
+      </listitem>
+      <listitem><para id="x_193">A backport patch may have several guards, one
+	  for each version of the kernel to which it applies.  For
+	  example, a patch that backports a piece of code to 2.6.9
+	  will have a <literal moreinfo="none">2.6.9</literal> guard.</para>
+      </listitem></itemizedlist>
+    <para id="x_194">This variety of guards gives me considerable flexibility in
+      determining what kind of source tree I want to end up with.  For
+      most situations, the selection of appropriate guards is
+      automated during the build process, but I can manually tune the
+      guards to use for less common circumstances.</para>
+
+    <sect2>
+      <title>The art of writing backport patches</title>
+
+      <para id="x_195">Using MQ, writing a backport patch is a simple process.
+	All such a patch has to do is modify a piece of code that uses
+	a kernel feature not present in the older version of the
+	kernel, so that the driver continues to work correctly under
+	that older version.</para>
+
+      <para id="x_196">A useful goal when writing a good backport patch is to
+	make your code look as if it was written for the older version
+	of the kernel you're targeting.  The less obtrusive the patch,
+	the easier it will be to understand and maintain.  If you're
+	writing a collection of backport patches to avoid the
+	<quote>rat's nest</quote> effect of lots of
+	<literal moreinfo="none">#ifdef</literal>s (hunks of source code that are only
+	used conditionally) in your code, don't introduce
+	version-dependent <literal moreinfo="none">#ifdef</literal>s into the patches.
+	Instead, write several patches, each of which makes
+	unconditional changes, and control their application using
+	guards.</para>
+
+      <para id="x_197">There are two reasons to divide backport patches into a
+	distinct group, away from the <quote>regular</quote> patches
+	whose effects they modify. The first is that intermingling the
+	two makes it more difficult to use a tool like the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension to automate the
+	process of submitting the patches to an upstream maintainer.
+	The second is that a backport patch could perturb the context
+	in which a subsequent regular patch is applied, making it
+	impossible to apply the regular patch cleanly
+	<emphasis>without</emphasis> the earlier backport patch
+	already being applied.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Useful tips for developing with MQ</title>
+
+    <sect2>
+      <title>Organising patches in directories</title>
+
+      <para id="x_198">If you're working on a substantial project with MQ, it's
+	not difficult to accumulate a large number of patches.  For
+	example, I have one patch repository that contains over 250
+	patches.</para>
+
+      <para id="x_199">If you can group these patches into separate logical
+	categories, you can if you like store them in different
+	directories; MQ has no problems with patch names that contain
+	path separators.</para>
+
+    </sect2>
+    <sect2 id="mq-collab:tips:interdiff">
+      <title>Viewing the history of a patch</title>
+
+      <para id="x_19a">If you're developing a set of patches over a long time,
+	it's a good idea to maintain them in a repository, as
+	discussed in <xref linkend="sec:mq:repo"/>.  If you do
+	so, you'll quickly
+	discover that using the <command role="hg-cmd" moreinfo="none">hg
+	  diff</command> command to look at the history of changes to
+	a patch is unworkable.  This is in part because you're looking
+	at the second derivative of the real code (a diff of a diff),
+	but also because MQ adds noise to the process by modifying
+	time stamps and directory names when it updates a
+	patch.</para>
+
+      <para id="x_19b">However, you can use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension, which is bundled
+	with Mercurial, to turn a diff of two versions of a patch into
+	something readable.  To do this, you will need a third-party
+	package called <literal role="package" moreinfo="none">patchutils</literal>
+	<citation>web:patchutils</citation>.  This provides a command
+	named <command moreinfo="none">interdiff</command>, which shows the
+	differences between two diffs as a diff.  Used on two versions
+	of the same diff, it generates a diff that represents the diff
+	from the first to the second version.</para>
+
+      <para id="x_19c">You can enable the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension in the usual way,
+	by adding a line to the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
+	<filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
+      <programlisting format="linespecific">[extensions]
+extdiff =</programlisting>
+      <para id="x_19d">The <command moreinfo="none">interdiff</command> command expects to be
+	passed the names of two files, but the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension passes the program
+	it runs a pair of directories, each of which can contain an
+	arbitrary number of files.  We thus need a small program that
+	will run <command moreinfo="none">interdiff</command> on each pair of files in
+	these two directories.  This program is available as <filename role="special" moreinfo="none">hg-interdiff</filename> in the <filename class="directory" moreinfo="none">examples</filename> directory of the
+	source code repository that accompanies this book. <!--
+	&example.hg-interdiff; --></para>
+
+      <para id="x_19e">With the <filename role="special" moreinfo="none">hg-interdiff</filename>
+	program in your shell's search path, you can run it as
+	follows, from inside an MQ patch directory:</para>
+      <programlisting format="linespecific">hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting>
+      <para id="x_19f">Since you'll probably want to use this long-winded command
+	a lot, you can get <literal role="hg-ext" moreinfo="none">hgext</literal> to
+	make it available as a normal Mercurial command, again by
+	editing your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
+      <programlisting format="linespecific">[extdiff]
+cmd.interdiff = hg-interdiff</programlisting>
+      <para id="x_1a0">This directs <literal role="hg-ext" moreinfo="none">hgext</literal> to
+	make an <literal moreinfo="none">interdiff</literal> command available, so you
+	can now shorten the previous invocation of <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> to something a
+	little more wieldy.</para>
+      <programlisting format="linespecific">hg interdiff -r A:B my-change.patch</programlisting>
+
+      <note>
+	<para id="x_1a1">  The <command moreinfo="none">interdiff</command> command works well
+	  only if the underlying files against which versions of a
+	  patch are generated remain the same.  If you create a patch,
+	  modify the underlying files, and then regenerate the patch,
+	  <command moreinfo="none">interdiff</command> may not produce useful
+	  output.</para>
+      </note>
+
+      <para id="x_1a2">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
+	useful for more than merely improving the presentation of MQ
+	patches.  To read more about it, go to <xref linkend="sec:hgext:extdiff"/>.</para>
+
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN ch14 -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:hgext">
+  <?dbhtml filename="adding-functionality-with-extensions.html"?>
+  <title>Adding functionality with extensions</title>
+
+  <para id="x_4fe">While the core of Mercurial is quite complete from a
+    functionality standpoint, it's deliberately shorn of fancy
+    features.  This approach of preserving simplicity keeps the
+    software easy to deal with for both maintainers and users.</para>
+
+  <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
+    command set: you can add features to it as
+    <emphasis>extensions</emphasis> (sometimes known as
+    <emphasis>plugins</emphasis>).  We've already discussed a few of
+    these extensions in earlier chapters.</para>
+  <itemizedlist>
+    <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
+	covers the <literal role="hg-ext" moreinfo="none">fetch</literal> extension;
+	this combines pulling new changes and merging them with local
+	changes into a single command, <command role="hg-ext-fetch" moreinfo="none">fetch</command>.</para>
+    </listitem>
+    <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
+	several extensions that are useful for hook-related
+	functionality: <literal role="hg-ext" moreinfo="none">acl</literal> adds
+	access control lists; <literal role="hg-ext" moreinfo="none">bugzilla</literal> adds integration with the
+	Bugzilla bug tracking system; and <literal role="hg-ext" moreinfo="none">notify</literal> sends notification emails on
+	new changes.</para>
+    </listitem>
+    <listitem><para id="x_502">The Mercurial Queues patch management extension is
+	so invaluable that it merits two chapters and an appendix all
+	to itself. <xref linkend="chap:mq"/> covers the
+	basics; <xref linkend="chap:mq-collab"/> discusses advanced topics;
+	and <xref linkend="chap:mqref"/> goes into detail on
+	each
+	command.</para>
+    </listitem></itemizedlist>
+
+  <para id="x_503">In this chapter, we'll cover some of the other extensions that
+    are available for Mercurial, and briefly touch on some of the
+    machinery you'll need to know about if you want to write an
+    extension of your own.</para>
+  <itemizedlist>
+    <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
+	we'll discuss the possibility of <emphasis>huge</emphasis>
+	performance improvements using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.</para>
+    </listitem></itemizedlist>
+
+  <sect1 id="sec:hgext:inotify">
+    <title>Improve performance with the <literal role="hg-ext" moreinfo="none">inotify</literal> extension</title>
+
+    <para id="x_505">Are you interested in having some of the most common
+      Mercurial operations run as much as a hundred times faster?
+      Read on!</para>
+
+    <para id="x_506">Mercurial has great performance under normal circumstances.
+      For example, when you run the <command role="hg-cmd" moreinfo="none">hg
+	status</command> command, Mercurial has to scan almost every
+      directory and file in your repository so that it can display
+      file status.  Many other Mercurial commands need to do the same
+      work behind the scenes; for example, the <command role="hg-cmd" moreinfo="none">hg diff</command> command uses the status
+      machinery to avoid doing an expensive comparison operation on
+      files that obviously haven't changed.</para>
+
+    <para id="x_507">Because obtaining file status is crucial to good
+      performance, the authors of Mercurial have optimised this code
+      to within an inch of its life.  However, there's no avoiding the
+      fact that when you run <command role="hg-cmd" moreinfo="none">hg
+	status</command>, Mercurial is going to have to perform at
+      least one expensive system call for each managed file to
+      determine whether it's changed since the last time Mercurial
+      checked.  For a sufficiently large repository, this can take a
+      long time.</para>
+
+    <para id="x_508">To put a number on the magnitude of this effect, I created a
+      repository containing 150,000 managed files.  I timed <command role="hg-cmd" moreinfo="none">hg status</command> as taking ten seconds to
+      run, even when <emphasis>none</emphasis> of those files had been
+      modified.</para>
+
+    <para id="x_509">Many modern operating systems contain a file notification
+      facility. If a program signs up to an appropriate service, the
+      operating system will notify it every time a file of interest is
+      created, modified, or deleted.  On Linux systems, the kernel
+      component that does this is called
+      <literal moreinfo="none">inotify</literal>.</para>
+
+    <para id="x_50a">Mercurial's <literal role="hg-ext" moreinfo="none">inotify</literal>
+      extension talks to the kernel's <literal moreinfo="none">inotify</literal>
+      component to optimise <command role="hg-cmd" moreinfo="none">hg status</command>
+      commands.  The extension has two components.  A daemon sits in
+      the background and receives notifications from the
+      <literal moreinfo="none">inotify</literal> subsystem.  It also listens for
+      connections from a regular Mercurial command.  The extension
+      modifies Mercurial's behavior so that instead of scanning the
+      filesystem, it queries the daemon.  Since the daemon has perfect
+      information about the state of the repository, it can respond
+      with a result instantaneously, avoiding the need to scan every
+      directory and file in the repository.</para>
+
+    <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
+      taking to run <command role="hg-cmd" moreinfo="none">hg status</command> on a
+      150,000 file repository.  With the <literal role="hg-ext" moreinfo="none">inotify</literal> extension enabled, the time
+      dropped to 0.1 seconds, a factor of <emphasis>one
+	hundred</emphasis> faster.</para>
+
+    <para id="x_50c">Before we continue, please pay attention to some
+      caveats.</para>
+    <itemizedlist>
+      <listitem><para id="x_50d">The <literal role="hg-ext" moreinfo="none">inotify</literal>
+	  extension is Linux-specific.  Because it interfaces directly
+	  to the Linux kernel's <literal moreinfo="none">inotify</literal> subsystem,
+	  it does not work on other operating systems.</para>
+      </listitem>
+      <listitem><para id="x_50e">It should work on any Linux distribution that
+	  was released after early 2005.  Older distributions are
+	  likely to have a kernel that lacks
+	  <literal moreinfo="none">inotify</literal>, or a version of
+	  <literal moreinfo="none">glibc</literal> that does not have the necessary
+	  interfacing support.</para>
+      </listitem>
+      <listitem><para id="x_50f">Not all filesystems are suitable for use with
+	  the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.
+	  Network filesystems such as NFS are a non-starter, for
+	  example, particularly if you're running Mercurial on several
+	  systems, all mounting the same network filesystem.  The
+	  kernel's <literal moreinfo="none">inotify</literal> system has no way of
+	  knowing about changes made on another system.  Most local
+	  filesystems (e.g. ext3, XFS, ReiserFS) should work
+	  fine.</para>
+      </listitem></itemizedlist>
+
+    <para id="x_510">The <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
+      not yet shipped with Mercurial as of May 2007, so it's a little
+      more involved to set up than other extensions.  But the
+      performance improvement is worth it!</para>
+
+    <para id="x_511">The extension currently comes in two parts: a set of patches
+      to the Mercurial source code, and a library of Python bindings
+      to the <literal moreinfo="none">inotify</literal> subsystem.</para>
+    <note>
+      <para id="x_512">  There are <emphasis>two</emphasis> Python
+	<literal moreinfo="none">inotify</literal> binding libraries.  One of them is
+	called <literal moreinfo="none">pyinotify</literal>, and is packaged by some
+	Linux distributions as <literal moreinfo="none">python-inotify</literal>.
+	This is <emphasis>not</emphasis> the one you'll need, as it is
+	too buggy and inefficient to be practical.</para>
+    </note>
+    <para id="x_513">To get going, it's best to already have a functioning copy
+      of Mercurial installed.</para>
+    <note>
+      <para id="x_514">  If you follow the instructions below, you'll be
+	<emphasis>replacing</emphasis> and overwriting any existing
+	installation of Mercurial that you might already have, using
+	the latest <quote>bleeding edge</quote> Mercurial code. Don't
+	say you weren't warned!</para>
+    </note>
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_515">Clone the Python <literal moreinfo="none">inotify</literal>
+	  binding repository.  Build and install it.</para>
+	<programlisting format="linespecific">hg clone http://hg.kublai.com/python/inotify
+cd inotify
+python setup.py build --force
+sudo python setup.py install --skip-build</programlisting>
+      </listitem>
+      <listitem><para id="x_516">Clone the <filename class="directory" moreinfo="none">crew</filename> Mercurial repository.
+	  Clone the <literal role="hg-ext" moreinfo="none">inotify</literal> patch
+	  repository so that Mercurial Queues will be able to apply
+	  patches to your cope of the <filename class="directory" moreinfo="none">crew</filename> repository.</para>
+	<programlisting format="linespecific">hg clone http://hg.intevation.org/mercurial/crew
+hg clone crew inotify
+hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
+      </listitem>
+      <listitem><para id="x_517">Make sure that you have the Mercurial Queues
+	  extension, <literal role="hg-ext" moreinfo="none">mq</literal>, enabled.  If
+	  you've never used MQ, read <xref linkend="sec:mq:start"/> to get started
+	  quickly.</para>
+      </listitem>
+      <listitem><para id="x_518">Go into the <filename class="directory" moreinfo="none">inotify</filename> repo, and apply all
+	  of the <literal role="hg-ext" moreinfo="none">inotify</literal> patches
+	  using the <option role="hg-ext-mq-cmd-qpush-opt">hg
+	    -a</option> option to the <command role="hg-ext-mq" moreinfo="none">qpush</command> command.</para>
+	<programlisting format="linespecific">cd inotify
+hg qpush -a</programlisting>
+      </listitem>
+      <listitem><para id="x_519">  If you get an error message from <command role="hg-ext-mq" moreinfo="none">qpush</command>, you should not continue.
+	  Instead, ask for help.</para>
+      </listitem>
+      <listitem><para id="x_51a">Build and install the patched version of
+	  Mercurial.</para>
+	<programlisting format="linespecific">python setup.py build --force
+sudo python setup.py install --skip-build</programlisting>
+      </listitem>
+    </orderedlist>
+    <para id="x_51b">Once you've build a suitably patched version of Mercurial,
+      all you need to do to enable the <literal role="hg-ext" moreinfo="none">inotify</literal> extension is add an entry to
+      your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
+    <programlisting format="linespecific">[extensions] inotify =</programlisting>
+    <para id="x_51c">When the <literal role="hg-ext" moreinfo="none">inotify</literal> extension
+      is enabled, Mercurial will automatically and transparently start
+      the status daemon the first time you run a command that needs
+      status in a repository.  It runs one status daemon per
+      repository.</para>
+
+    <para id="x_51d">The status daemon is started silently, and runs in the
+      background.  If you look at a list of running processes after
+      you've enabled the <literal role="hg-ext" moreinfo="none">inotify</literal>
+      extension and run a few commands in different repositories,
+      you'll thus see a few <literal moreinfo="none">hg</literal> processes sitting
+      around, waiting for updates from the kernel and queries from
+      Mercurial.</para>
+
+    <para id="x_51e">The first time you run a Mercurial command in a repository
+      when you have the <literal role="hg-ext" moreinfo="none">inotify</literal>
+      extension enabled, it will run with about the same performance
+      as a normal Mercurial command.  This is because the status
+      daemon needs to perform a normal status scan so that it has a
+      baseline against which to apply later updates from the kernel.
+      However, <emphasis>every</emphasis> subsequent command that does
+      any kind of status check should be noticeably faster on
+      repositories of even fairly modest size.  Better yet, the bigger
+      your repository is, the greater a performance advantage you'll
+      see.  The <literal role="hg-ext" moreinfo="none">inotify</literal> daemon makes
+      status operations almost instantaneous on repositories of all
+      sizes!</para>
+
+    <para id="x_51f">If you like, you can manually start a status daemon using
+      the <command role="hg-ext-inotify" moreinfo="none">inserve</command> command.
+      This gives you slightly finer control over how the daemon ought
+      to run.  This command will of course only be available when the
+      <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
+      enabled.</para>
+
+    <para id="x_520">When you're using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension, you should notice
+      <emphasis>no difference at all</emphasis> in Mercurial's
+      behavior, with the sole exception of status-related commands
+      running a whole lot faster than they used to.  You should
+      specifically expect that commands will not print different
+      output; neither should they give different results. If either of
+      these situations occurs, please report a bug.</para>
+
+  </sect1>
+  <sect1 id="sec:hgext:extdiff">
+    <title>Flexible diff support with the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension</title>
+
+    <para id="x_521">Mercurial's built-in <command role="hg-cmd" moreinfo="none">hg
+	diff</command> command outputs plaintext unified diffs.</para>
+
+    <!-- BEGIN extdiff.diff -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
+diff -r 801b35c37d8b myfile
+--- a/myfile	Sun Aug 16 14:05:02 2009 +0000
++++ b/myfile	Sun Aug 16 14:05:02 2009 +0000
+@@ -1,1 +1,2 @@
+ The first line.
++The second line.
+</screen>
+<!-- END extdiff.diff -->
+
+
+    <para id="x_522">If you would like to use an external tool to display
+      modifications, you'll want to use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension.  This will let you
+      use, for example, a graphical diff tool.</para>
+
+    <para id="x_523">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
+      bundled with Mercurial, so it's easy to set up.  In the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
+      <filename role="special" moreinfo="none">~/.hgrc</filename>, simply add a
+      one-line entry to enable the extension.</para>
+    <programlisting format="linespecific">[extensions]
+extdiff =</programlisting>
+    <para id="x_524">This introduces a command named <command role="hg-ext-extdiff" moreinfo="none">extdiff</command>, which by default uses
+      your system's <command moreinfo="none">diff</command> command to generate a
+      unified diff in the same form as the built-in <command role="hg-cmd" moreinfo="none">hg diff</command> command.</para>
+    
+    <!-- BEGIN extdiff.extdiff -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff</userinput>
+--- a.801b35c37d8b/myfile	2009-08-16 14:05:02.000000000 +0000
++++ /tmp/extdiffl1y_s9/a/myfile	2009-08-16 14:05:02.000000000 +0000
+@@ -1 +1,2 @@
+ The first line.
++The second line.
+</screen>
+<!-- END extdiff.extdiff -->
+
+
+    <para id="x_525">The result won't be exactly the same as with the built-in
+      <command role="hg-cmd" moreinfo="none">hg diff</command> variations, because the
+      output of <command moreinfo="none">diff</command> varies from one system to
+      another, even when passed the same options.</para>
+
+    <para id="x_526">As the <quote><literal moreinfo="none">making snapshot</literal></quote>
+      lines of output above imply, the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command works by
+      creating two snapshots of your source tree.  The first snapshot
+      is of the source revision; the second, of the target revision or
+      working directory.  The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command generates
+      these snapshots in a temporary directory, passes the name of
+      each directory to an external diff viewer, then deletes the
+      temporary directory.  For efficiency, it only snapshots the
+      directories and files that have changed between the two
+      revisions.</para>
+
+    <para id="x_527">Snapshot directory names have the same base name as your
+      repository. If your repository path is <filename class="directory" moreinfo="none">/quux/bar/foo</filename>, then <filename class="directory" moreinfo="none">foo</filename> will be the name of each
+      snapshot directory.  Each snapshot directory name has its
+      changeset ID appended, if appropriate.  If a snapshot is of
+      revision <literal moreinfo="none">a631aca1083f</literal>, the directory will be
+      named <filename class="directory" moreinfo="none">foo.a631aca1083f</filename>.
+      A snapshot of the working directory won't have a changeset ID
+      appended, so it would just be <filename class="directory" moreinfo="none">foo</filename> in this example.  To see what
+      this looks like in practice, look again at the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> example above.  Notice
+      that the diff has the snapshot directory names embedded in its
+      header.</para>
+
+    <para id="x_528">The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
+      accepts two important options. The <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
+      lets you choose a program to view differences with, instead of
+      <command moreinfo="none">diff</command>.  With the <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
+      you can change the options that <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> passes to the program
+      (by default, these options are
+      <quote><literal moreinfo="none">-Npru</literal></quote>, which only make sense
+      if you're running <command moreinfo="none">diff</command>).  In other respects,
+      the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
+      acts similarly to the built-in <command role="hg-cmd" moreinfo="none">hg
+	diff</command> command: you use the same option names, syntax,
+      and arguments to specify the revisions you want, the files you
+      want, and so on.</para>
+
+    <para id="x_529">As an example, here's how to run the normal system
+      <command moreinfo="none">diff</command> command, getting it to generate context
+      diffs (using the <option role="cmd-opt-diff">-c</option> option)
+      instead of unified diffs, and five lines of context instead of
+      the default three (passing <literal moreinfo="none">5</literal> as the argument
+      to the <option role="cmd-opt-diff">-C</option> option).</para>
+
+      <!-- BEGIN extdiff.extdiff-ctx -->
+<screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff -o -NprcC5</userinput>
+*** a.801b35c37d8b/myfile	Sun Aug 16 14:05:02 2009
+--- /tmp/extdiffl1y_s9/a/myfile	Sun Aug 16 14:05:02 2009
+***************
+*** 1 ****
+--- 1,2 ----
+  The first line.
++ The second line.
+</screen>
+<!-- END extdiff.extdiff-ctx -->
+
+
+    <para id="x_52a">Launching a visual diff tool is just as easy.  Here's how to
+      launch the <command moreinfo="none">kdiff3</command> viewer.</para>
+    <programlisting format="linespecific">hg extdiff -p kdiff3 -o</programlisting>
+
+    <para id="x_52b">If your diff viewing command can't deal with directories,
+      you can easily work around this with a little scripting.  For an
+      example of such scripting in action with the <literal role="hg-ext" moreinfo="none">mq</literal> extension and the
+      <command moreinfo="none">interdiff</command> command, see <xref linkend="mq-collab:tips:interdiff"/>.</para>
+
+    <sect2>
+      <title>Defining command aliases</title>
+
+      <para id="x_52c">It can be cumbersome to remember the options to both the
+	<command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command and
+	the diff viewer you want to use, so the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension lets you define
+	<emphasis>new</emphasis> commands that will invoke your diff
+	viewer with exactly the right options.</para>
+
+      <para id="x_52d">All you need to do is edit your <filename role="special" moreinfo="none">~/.hgrc</filename>, and add a section named
+	<literal role="rc-extdiff" moreinfo="none">extdiff</literal>.  Inside this
+	section, you can define multiple commands.  Here's how to add
+	a <literal moreinfo="none">kdiff3</literal> command.  Once you've defined
+	this, you can type <quote><literal moreinfo="none">hg kdiff3</literal></quote>
+	and the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension
+	will run <command moreinfo="none">kdiff3</command> for you.</para>
+      <programlisting format="linespecific">[extdiff]
+cmd.kdiff3 =</programlisting>
+      <para id="x_52e">If you leave the right hand side of the definition empty,
+	as above, the <literal role="hg-ext" moreinfo="none">extdiff</literal>
+	extension uses the name of the command you defined as the name
+	of the external program to run.  But these names don't have to
+	be the same.  Here, we define a command named
+	<quote><literal moreinfo="none">hg wibble</literal></quote>, which runs
+	<command moreinfo="none">kdiff3</command>.</para>
+      <programlisting format="linespecific">[extdiff]
+ cmd.wibble = kdiff3</programlisting>
+
+      <para id="x_52f">You can also specify the default options that you want to
+	invoke your diff viewing program with.  The prefix to use is
+	<quote><literal moreinfo="none">opts.</literal></quote>, followed by the name
+	of the command to which the options apply.  This example
+	defines a <quote><literal moreinfo="none">hg vimdiff</literal></quote> command
+	that runs the <command moreinfo="none">vim</command> editor's
+	<literal moreinfo="none">DirDiff</literal> extension.</para>
+      <programlisting format="linespecific">[extdiff]
+ cmd.vimdiff = vim
+opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
+
+    </sect2>
+  </sect1>
+  <sect1 id="sec:hgext:transplant">
+    <title>Cherrypicking changes with the <literal role="hg-ext" moreinfo="none">transplant</literal> extension</title>
+
+    <para id="x_530">Need to have a long chat with Brendan about this.</para>
+
+  </sect1>
+  <sect1 id="sec:hgext:patchbomb">
+    <title>Send changes via email with the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension</title>
+
+    <para id="x_531">Many projects have a culture of <quote>change
+	review</quote>, in which people send their modifications to a
+      mailing list for others to read and comment on before they
+      commit the final version to a shared repository.  Some projects
+      have people who act as gatekeepers; they apply changes from
+      other people to a repository to which those others don't have
+      access.</para>
+
+    <para id="x_532">Mercurial makes it easy to send changes over email for
+      review or application, via its <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension.  The extension is
+      so named because changes are formatted as patches, and it's usual
+      to send one changeset per email message.  Sending a long series
+      of changes by email is thus much like <quote>bombing</quote> the
+      recipient's inbox, hence <quote>patchbomb</quote>.</para>
+
+    <para id="x_533">As usual, the basic configuration of the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension takes just one or
+      two lines in your <filename role="special" moreinfo="none">
+	/.hgrc</filename>.</para>
+    <programlisting format="linespecific">[extensions]
+patchbomb =</programlisting>
+    <para id="x_534">Once you've enabled the extension, you will have a new
+      command available, named <command role="hg-ext-patchbomb" moreinfo="none">email</command>.</para>
+
+    <para id="x_535">The safest and best way to invoke the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command is to
+      <emphasis>always</emphasis> run it first with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
+      This will show you what the command <emphasis>would</emphasis>
+      send, without actually sending anything.  Once you've had a
+      quick glance over the changes and verified that you are sending
+      the right ones, you can rerun the same command, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
+      removed.</para>
+
+    <para id="x_536">The <command role="hg-ext-patchbomb" moreinfo="none">email</command> command
+      accepts the same kind of revision syntax as every other
+      Mercurial command.  For example, this command will send every
+      revision between 7 and <literal moreinfo="none">tip</literal>, inclusive.</para>
+    <programlisting format="linespecific">hg email -n 7:tip</programlisting>
+    <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
+      compare with.  If you provide a repository but no revisions, the
+      <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will
+      send all revisions in the local repository that are not present
+      in the remote repository.  If you additionally specify revisions
+      or a branch name (the latter using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
+      this will constrain the revisions sent.</para>
+
+    <para id="x_538">It's perfectly safe to run the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command without the
+      names of the people you want to send to: if you do this, it will
+      just prompt you for those values interactively.  (If you're
+      using a Linux or Unix-like system, you should have enhanced
+      <literal moreinfo="none">readline</literal>-style editing capabilities when
+      entering those headers, too, which is useful.)</para>
+
+    <para id="x_539">When you are sending just one revision, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will by
+      default use the first line of the changeset description as the
+      subject of the single email message it sends.</para>
+
+    <para id="x_53a">If you send multiple revisions, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will usually
+      send one message per changeset.  It will preface the series with
+      an introductory message, in which you should describe the
+      purpose of the series of changes you're sending.</para>
+
+    <sect2>
+      <title>Changing the behavior of patchbombs</title>
+
+      <para id="x_53b">Not every project has exactly the same conventions for
+	sending changes in email; the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension tries to
+	accommodate a number of variations through command line
+	options.</para>
+      <itemizedlist>
+	<listitem><para id="x_53c">You can write a subject for the introductory
+	    message on the command line using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
+	    option.  This takes one argument, the text of the subject
+	    to use.</para>
+	</listitem>
+	<listitem><para id="x_53d">To change the email address from which the
+	    messages originate, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
+	    option.  This takes one argument, the email address to
+	    use.</para>
+	</listitem>
+	<listitem><para id="x_53e">The default behavior is to send unified diffs
+	    (see <xref linkend="sec:mq:patch"/> for a
+	    description of the
+	    format), one per message.  You can send a binary bundle
+	    instead with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
+	    option.</para>
+	</listitem>
+	<listitem><para id="x_53f">Unified diffs are normally prefaced with a
+	    metadata header.  You can omit this, and send unadorned
+	    diffs, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg
+	      --plain</option> option.</para>
+	</listitem>
+	<listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
+	    in the same body part as the description of a patch.  This
+	    makes it easiest for the largest number of readers to
+	    quote and respond to parts of a diff, as some mail clients
+	    will only quote the first MIME body part in a message. If
+	    you'd prefer to send the description and the diff in
+	    separate body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
+	    option.</para>
+	</listitem>
+	<listitem><para id="x_541">Instead of sending mail messages, you can
+	    write them to an <literal moreinfo="none">mbox</literal>-format mail
+	    folder using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
+	    option.  That option takes one argument, the name of the
+	    file to write to.</para>
+	</listitem>
+	<listitem><para id="x_542">If you would like to add a
+	    <command moreinfo="none">diffstat</command>-format summary to each patch,
+	    and one to the introductory message, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
+	    option.  The <command moreinfo="none">diffstat</command> command displays
+	    a table containing the name of each file patched, the
+	    number of lines affected, and a histogram showing how much
+	    each file is modified.  This gives readers a qualitative
+	    glance at how complex a patch is.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "chapter")
+end:
+-->
+
+  <!-- BEGIN appA -->
+  
+
+<appendix id="svn">
+  <?dbhtml filename="migrating-to-mercurial.html"?>
+<title>Migrer vers Mercurial</title>
+
+  <para id="x_6e1">Une manière courante de s'essayer à un nouveau
+  gestionnaire de révisions est d'expérimenter en migrant un
+  projet existant, plutôt que le faire avec un nouveau projet.
+  </para>
+
+  <para id="x_6e2">Dans cette annexe, nous discuterons comment importer
+  l'historique d'un projet dans Mercurial, et à quoi faire attention
+  si vous êtes habitués à un autre outil de gestion de révisions.
+   </para>
+
+  <sect1>
+    <title>Importer l'historique depuis un autre système</title>
+
+    <para id="x_6e3">Mercurial est livré avec une extension nommée
+      <literal moreinfo="none">convert</literal>, qui permet d'importer un historique
+      depuis les gestionnaire de révisions les plus courants. Au moment de 
+      l'écriture de ce livre, il pouvait importer l'historique depuis:
+      </para>
+    <itemizedlist>
+      <listitem>
+	<para id="x_6e4">Subversion</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e5">CVS</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e6">git</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e7">Darcs</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e8">Bazaar</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e9">Monotone</para>
+      </listitem>
+      <listitem>
+	<para id="x_6ea">GNU Arch</para>
+      </listitem>
+      <listitem>
+	<para id="x_6eb">Mercurial</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_6ec">(Pour savoir pourquoi Mercurial lui même est supporté
+    comme source, voir <xref linkend="svn.filemap"/>.)</para>
+
+    <para id="x_6ed">Vous pouvez activer l'extension de la manière
+    habituelle, en éditant votre fichier <filename moreinfo="none">~/.hgrc</filename></para>
+
+    <programlisting format="linespecific">[extensions]
+convert =</programlisting>
+
+    <para id="x_6ee">Ceci rendra la commande <command moreinfo="none">hg convert</command>
+    disponible. La commande est facile à utiliser. Par exemple, la 
+    commande suivante va importer l'historique Subversion du <emphasis remap="it">framework</emphasis> de test <quote>Nose Unit</quote> dans Mercurial.
+      </para>
+
+    <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
+
+    <para id="x_6ef">L'extension <literal moreinfo="none">convert</literal> opère de 
+    manière incrémentale. En d'autres mots, après une première exécution de
+    la commande <command moreinfo="none">hg convert</command>, les exécutions ultérieures
+    importeront les révisions ultérieures à l'exécution précédente.
+    La conversion incrémentale ne réussira que si
+    vous exécutez <command moreinfo="none">hg convert</command> dans le même dépôt que vous
+    aviez utilisé à l'origine, ceci parce que l'extension <literal moreinfo="none">convert</literal> 
+    sauvegarde un certain nombre de méta-données privées dans le fichier
+    <filename moreinfo="none">.hg/shamap</filename> (non versioné) au sein du dépôt cible.
+    </para>
+
+    <para id="x_707">Lorsque vous voulez faire des modifications en utilisant
+    Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence 
+    que vous souhaitez convertir, et de laisser l'arborescence d'origine pour
+    de futures conversions incrémentales. C'est la manière la plus sûre pour vous laisser
+    récupérer et fusionner les modifications futures depuis l'outil de gestion
+    de révisions dans votre nouveau dépôt Mercurial.</para>
+
+    <sect2>
+      <title>Convertir plusieurs branches</title>
+
+      <para id="x_708">La commande <command moreinfo="none">hg convert</command> citée 
+      ci-dessus convertit seulement l'historique de la <literal moreinfo="none">branche
+      principale (trunk)</literal> du dépôt Subversion. Si nous utilisons
+      à la place l'URL <literal moreinfo="none">http://python-nose.googlecode.com/svn</literal>,
+      Mercurial va automatiquement détecter la  
+      <literal moreinfo="none">branche principale (trunk)</literal>, les <literal moreinfo="none">étiquettes 
+      (tags)</literal>, et les <literal moreinfo="none">branches</literal>  que les dépôts
+      Subversion utilisent généralement, et les importera chacun dans
+      une branche Mercurial distincte.</para>
+
+      <para id="x_709">Par défaut, chaque branche Subversion importée 
+     dans Mercurial se voit attribuer un nom de branche. Une fois la
+     conversion achevée, vous pouvez obtenir la liste des noms des branches 
+     actives dans le dépôt Mercurial en utilisant la commande
+     <command moreinfo="none">hg branches -a</command>. Si vous préférez importer les 
+     branches Subversion sans noms, ajoutez l'option <option>--config
+     convert.hg.usebranches=false</option> à la commande 
+     <command moreinfo="none">hg convert</command>.</para>
+
+      <para id="x_70a">Une fois votre arborescence convertie, 
+      si vous souhaitez travailler selon la pratique habituelle sous Mercurial
+      avec une arborescence qui ne contient qu'une seule branche, vous pouvez cloner
+      cette seule branche en utilisant 
+      <command moreinfo="none">hg clone -r nomdemabranche</command>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Associer les noms d'utilisateurs</title>
+
+      <para id="x_6f0">Certains outils de gestion de révisions
+      ne sauvegardent, avec les modifications, que les noms 
+      d'utilisateurs raccourcis. Ceux-ci peuvent être difficiles à 
+      interpréter. La norme avec Mercurial est de sauvegarder le 
+      nom du <emphasis remap="it">committeur</emphasis> et son adresse
+      mail, ce qui est beaucoup plus utile pour discuter avec lui
+      par la suite.</para>
+
+      <para id="x_6f1">Si vous convertissez une arborescence depuis
+      un gestionnaire de révisions qui utilise seulement les noms
+      raccourcis, vous pouvez associer ces noms à des équivalents 
+      plus détaillés en passant l'option <option>--authors</option>
+      à la commande <command moreinfo="none">hg convert</command>. Cette option
+      attend un fichier qui contient des entrées sous la forme suivante:
+      </para>
+
+      <programlisting format="linespecific">arist = Aristotle &lt;aristotle@phil.example.gr&gt;
+soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
+
+      <para id="x_6f2">Quand <literal moreinfo="none">convert</literal> trouve une
+      modification associée au nom <literal moreinfo="none">arist</literal> dans le
+      dépôt de source, il va utiliser le nom <literal moreinfo="none">Aristotle
+      &lt;aristotle@phil.example.gr&gt;</literal> dans les révisions
+      Mercurial. Si aucune correspondance n'est trouvé, il utilise
+      le nom tel quel.</para>
+    </sect2>
+
+    <sect2 id="svn.filemap">
+      <title>Nettoyer l'arboresence</title>
+
+      <para id="x_6f3">Tous les projets n'ont pas un historique parfait.
+      Il peut y avoir des répertoires qui n'auraient jamais dû être ajoutés,
+      un fichier qui est trop volumineux, ou même une partie de la
+      hiérarchie qui devrait être réorganisée.</para>
+
+      <para id="x_6f4">L'extension <literal moreinfo="none">convert</literal> permet
+      d'utiliser un <quote>fichier d'association</quote> qui peut 
+      réorganiser les fichiers et les répertoires dans un projet lors de
+      l'importation de son historique. Ceci est utile non seulement quand vous
+      importez l'historique d'un autre gestionnaire de révisions, mais
+      aussi pour nettoyer ou réorganiser l'arborescence d'un projet
+      Mercurial.</para>
+
+      <para id="x_6f5">Pour indiquer le fichier d'association, on utilise
+      l'option <option>--filemap</option> en lui fournissant un nom de
+      fichier. Le fichier d'association contient des lignes de la forme
+      suivante :</para>
+
+      <programlisting format="linespecific"># Ceci est un commentaire.
+# Les lignes vides sont ignorées.
+
+include path/to/file
+
+exclude path/to/file
+
+rename from/some/path to/some/other/place
+</programlisting>
+      
+      <para id="x_6f6">La directive <literal moreinfo="none">include</literal> inclut un
+      fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt
+      de destination. La directive <literal moreinfo="none">exclude</literal> omet les
+      fichiers ou répertoires du dépôt. Ceci inclut aussi les autres
+      fichiers et répertoires qui ne sont pas explicitement inclus.
+      La directive <literal moreinfo="none">exclude</literal> entraine l'omission
+      des fichiers ou répertoires, et autres fichiers qui ne sont pas
+      explicitement inclus.</para>
+
+      <para id="x_6f7">Pour déplacer un fichier ou un répertoire d'un
+      emplacement à un autre, utilisez la directive
+      <literal moreinfo="none">rename</literal>. Si vous avez besoin de déplacer un 
+      fichier ou un répertoire depuis un sous répertoire dans la racine
+      du dépôt, utilisez <literal moreinfo="none">.</literal> comme second argument de 
+      la directive <literal moreinfo="none">rename</literal>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Améliorer les performances de la conversion Subversion</title>
+
+      <para id="x_70b">Vous aurez souvent besoin de plusieurs essais
+      avant d'arriver à la parfaite combinaison de fichier d'association de fichiers,
+      de fichier d'association de noms d'utilisateurs et des autres paramètres. Or,
+      convertir un dépôt Mercurial via un protocole comme <literal moreinfo="none">ssh</literal>
+      ou <literal moreinfo="none">http</literal> peut être des milliers de fois plus long
+      que ce dont le système d'exploitation est en fait capable de faire,
+      à cause des latence réseau. Ceci peut rendre la conception de cette
+      combinaison parfaite très douloureuse.</para>
+
+      <para id="x_70c">La commande <ulink url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command moreinfo="none">svnsync</command></ulink> 
+	peut grandement améliorer la vitesse de conversion d'un dépôt
+        Subversion. Il s'agit d'un programme de miroir de dépôt Subversion
+        en lecture seule. L'idée est de créer un miroir local d'une
+        arborescence Subversion, puis de convertir ce miroir en dépôt
+        Mercurial.</para>
+      
+      <para id="x_70d">Supposez que nous voulions convertir le dépôt 
+      Subversion du populaire projet Memcached en une arborescence Mercurial.
+      Tout d'abord, nous créons un dépôt Subversion local.</para>
+
+      <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnadmin create memcached-mirror</userinput></screen>
+
+      <para id="x_70e">Puis, nous allons mettre en place un <quote>hook</quote> Subversion
+      dont <command moreinfo="none">svnsync</command> a besoin.</para>
+
+      <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '#!/bin/sh' &gt; memcached-mirror/hooks/pre-revprop-change</userinput>
+<prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
+
+      <para id="x_70f">Nous initialisons ensuite <command moreinfo="none">svnsync</command> dans ce
+      dépôt.</para>
+
+      <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync --init file://`pwd`/memcached-mirror \
+  http://code.sixapart.com/svn/memcached</userinput></screen>
+
+      <para id="x_710">La prochaine étape est de commencer le processus de
+      mirroring de <command moreinfo="none">svnsync</command>.</para>
+
+      <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
+
+      <para id="x_711">Enfin, nous importons l'historique de notre dépôt
+      local Subversion dans Mercurial.</para>
+
+      <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert memcached-mirror</userinput></screen>
+      
+      <para id="x_712">Nous pouvons utiliser ce processus de manière
+      incrémentale, si le dépôt Subversion est toujours en activité.
+      Il suffit d'exécuter de nouveau <command moreinfo="none">svnsync</command> pour
+      récupérer les récentes modifications dans notre miroir, puis <command moreinfo="none">hg 
+      convert</command>
+      les importe dans notre arborescence Mercurial.</para>
+
+      <para id="x_713">Il y a deux avantages à utiliser un import à deux
+      étages comme avec <command moreinfo="none">svnsync</command>. Le premier
+      est qu'il utilise du code de synchronisation réseau de Subversion 
+      plus efficace que la commande <command moreinfo="none">hg convert</command>,
+      et donc transfère moins de données par le réseau. Le deuxième
+      est que l'import depuis un dépôt Subversion local est si rapide que
+      vous pouvez peaufiner et réitérer les paramètres de conversion de 
+      ce dernier sans souffrir de la qualité de la connexion réseau.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Migrer depuis Subversion</title>
+
+    <para id="x_6f8">Subversion est le système de gestion de versions
+    open source le plus populaire aujourd'hui. Bien qu'il y ait des
+    différences entre Mercurial et Subversion, faire la transition de
+    l'un à l'autre n'est pas très difficile. Les deux disposent en effet 
+    de jeux de commandes similaires et d'interfaces similaires.</para>
+
+    <sect2>
+      <title>Différences philosophiques</title>
+
+      <para id="x_6f9">La différence fondamentale entre Subversion et
+      Mercurial est bien évidement que Subversion est centralisé, alors 
+      que Mercurial est distribué. Puisque que Mercurial enregistre tout
+      l'historique d'un projet sur votre disque dur local, il n'a besoin
+      d'effectuer des accès au réseau que lorsque vous voulez
+      explicitement communiquer avec un autre dépôt. Subversion, par contre,
+      ne conserve que peu d'informations localement, et le client
+      doit donc communiquer avec le serveur central pour la
+      plupart des opérations communes.</para>
+
+      <para id="x_6fa">Subversion s'en tire plus ou moins bien sans notion
+      de branche réellement bien définie : quelle portion de l'espace de nommage
+      du serveur est une branche est une simple question de convention, le
+      logiciel n'imposant rien à ce sujet. Mercurial considère
+      un dépôt comme un élément de la gestion des branches.</para>
+      
+      <sect3>
+	<title>Portée des commandes</title>
+
+	<para id="x_6fb">Puisque que Subversion ne sait pas réellement
+        quelle partie de son espace de nommage est en fait une branche, il
+        traite la plupart des commandes comme des requêtes à exécuter sur le
+        répertoire où vous vous situez, et ses sous répertoires. Par exemple,
+        si vous exécutez <command moreinfo="none">svn log</command>, vous verrez l'historique 
+        de la partie de l'arborescence où vous vous situez, et non de la
+        hiérarchie entière.</para>
+
+	<para id="x_6fc">Les commandes de Mercurial ont un comportement
+        différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence
+        du dépôt. Exécutez la commande <command moreinfo="none">hg log</command> et elle vous
+        donnera l'historique de l'ensemble de l'arborescence, quel que soit le
+        sous-répertoire où vous vous situez. Si
+        vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un
+        fichier, ajouter simplement le nom de celui-ci à la commande, par
+        exemple <command moreinfo="none">hg log src</command>.</para>
+
+	<para id="x_6fd">De ma propre expérience, cette différence dans leur
+        comportement par défaut est probablement ce qui risque de vous
+        surprendre le plus si vous passez régulièrement d'un outil à l'autre.</para>
+      </sect3>
+
+      <sect3>
+	<title>Opération multi utilisateur et sécurité</title>
+
+	<para id="x_6fe">Avec Subversion, il est normal (bien que légèrement
+        désapprouvé) que différentes personnes collaborent sur une seule
+        branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses
+        modifications à leur branche partagée, Bob doit alors mettre à jour
+        sa vue de la branche avant de pouvoir appliquer un commit.
+        Puisqu'il n'a, à ce moment, pas effectué de commit
+        des modifications qu'il a faites, il se peut qu'il ne corrompe 
+        ou ne perde
+        ses modifications pendant ou après la mise à jour.</para>
+
+	<para id="x_6ff">Mercurial encourage, à l'inverse, un modèle 
+        "commit-puis-merge". Avant de récupérer des modifications depuis le 
+        serveur, ou avant d'y envoyer les siennes, Bob enregistre ses 
+        modifications de manière locale en appliquant un commit. C'est à dire
+        que si Alice avait envoyé ses modifications sur le serveur avant
+        que Bob n'envoie les siennes, ce dernier ne pourra le faire
+        qu'après avoir récupéré et fusionné celles d'Alice avec les siennes. 
+        Si Bob fait alors une
+        erreur lors de la fusion, il pourra toujours restaurer sa version, pour
+        laquelle il avait appliqué le commit.</para>
+          
+	<para id="x_700">Il est important de souligner qu'il s'agit de la
+        manière habituelle de travailler avec ces outils. Subversion propose
+        une manière plus sûre de "travailler-dans-votre-propre-branche", mais elle
+        est assez complexe pour que, en pratique, elle ne soit que rarement utilisé.
+        Mercurial propose de son côté un mode un peu moins sûr, permettant de
+        récupérer des modifications par dessus des modifications non
+        committées, qui reste toutefois très peu répandu.</para> 
+      </sect3>
+
+      <sect3>
+	<title>Publication vs changement locaux</title>
+
+	<para id="x_701">Une commande Subversion <command moreinfo="none">svn
+        commit</command> publie immédiatement les modifications sur le
+        serveur, où elles peuvent être vu par n'importe qui doté d'un privilège
+        de lecture.</para>
+
+	<para id="x_702">Avec Mercurial, les modifications sont toujours d'abord
+        enregistrées localement, et doivent être par la suite transférés par
+        la commande <command moreinfo="none">hg push</command>.</para>
+
+	<para id="x_703">Chaque approche a ses avantages et ses inconvénients.
+        Le modèle Subversion implique que les modifications soient publiées, et
+        donc disponibles immédiatement. D'un autre coté, cela implique aussi
+        que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit 
+        avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé 
+        facilement par la plupart des projets Open Source.</para>
+
+	<para id="x_704">L'approche de Mercurial permet à quiconque de faire
+        un clone du dépôt et d'y ajouter ses modifications sans jamais avoir
+        besoin de la permission de quiconque, et l'on peut même publier ses
+        modifications et continuer à participer comme on le désire. Toutefois, la
+        distinction entre les commits et le transfert de ces derniers présente
+        le risque que quelqu'un applique ses modifications par un commit local
+        sur son portable et parte se promener pendant quelques jours en ayant
+        oublié de les transférer, ce qui peut, dans certains rares cas,
+        bloquer temporairement ses collaborateurs.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Références des commandes</title>
+
+      <table>
+	<title>Commandes Subversion et leurs équivalents Mercurial</title>
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Subversion</entry>
+	      <entry>Mercurial</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><command moreinfo="none">svn add</command></entry>
+	      <entry><command moreinfo="none">hg add</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn blame</command></entry>
+	      <entry><command moreinfo="none">hg annotate</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn cat</command></entry>
+	      <entry><command moreinfo="none">hg cat</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn checkout</command></entry>
+	      <entry><command moreinfo="none">hg clone</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn cleanup</command></entry>
+	      <entry>n/a</entry>
+	      <entry>Aucun nettoyage nécessaire.</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn commit</command></entry>
+	      <entry><command moreinfo="none">hg commit</command>; <command moreinfo="none">hg
+		  push</command></entry>
+	      <entry><command moreinfo="none">hg push</command> publie les modifications
+              après un commit.</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn copy</command></entry>
+	      <entry><command moreinfo="none">hg clone</command></entry>
+	      <entry>Pour créer une nouvelle branche</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn copy</command></entry>
+	      <entry><command moreinfo="none">hg copy</command></entry>
+	      <entry>Pour copier des fichiers ou des répertoires</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn delete</command> (<command moreinfo="none">svn
+		  remove</command>)</entry>
+	      <entry><command moreinfo="none">hg remove</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn diff</command></entry>
+	      <entry><command moreinfo="none">hg diff</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn export</command></entry>
+	      <entry><command moreinfo="none">hg archive</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn help</command></entry>
+	      <entry><command moreinfo="none">hg help</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn import</command></entry>
+	      <entry><command moreinfo="none">hg addremove</command>; <command moreinfo="none">hg
+		  commit</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn info</command></entry>
+	      <entry><command moreinfo="none">hg parents</command></entry>
+	      <entry>Affiche la version sur la base de laquelle on travaille</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn info</command></entry>
+	      <entry><command moreinfo="none">hg showconfig
+		  paths.default</command></entry>
+	      <entry>Affiche de quelle URL est extrait ce dépôt</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn list</command></entry>
+	      <entry><command moreinfo="none">hg manifest</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn log</command></entry>
+	      <entry><command moreinfo="none">hg log</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn merge</command></entry>
+	      <entry><command moreinfo="none">hg merge</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn mkdir</command></entry>
+	      <entry>n/a</entry>
+	      <entry>Mercurial ne versionne pas les répertoires</entry>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn move</command> (<command moreinfo="none">svn
+		  rename</command>)</entry>
+	      <entry><command moreinfo="none">hg rename</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn resolved</command></entry>
+	      <entry><command moreinfo="none">hg resolve -m</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn revert</command></entry>
+	      <entry><command moreinfo="none">hg revert</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn status</command></entry>
+	      <entry><command moreinfo="none">hg status</command></entry>
+	      <entry/>
+	    </row>
+	    <row>
+	      <entry><command moreinfo="none">svn update</command></entry>
+	      <entry><command moreinfo="none">hg pull -u</command></entry>
+	      <entry/>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Conseils utiles pour les débutants</title>
+
+    <para id="x_705">Avec la plupart des gestionnaire de versions, afficher
+    un diff associé à une révision peut être assez douloureux. Par exemple,
+    avec Subversion, pour voir ce qui a été modifiée dans la révision 104654,
+    vous devez saisir <command moreinfo="none">svn diff -r104653:104654</command>. Mercurial
+    élimine le besoin de saisir l'identifiant d'une révision deux fois dans
+    ce cas classique. Pour un simple diff, <command moreinfo="none">hg
+    export 104654</command> suffit. Pour obtenir une entrée du journal suivie d'un diff,
+    <command moreinfo="none">hg log -r104654 -p</command>.</para>
+
+    <para id="x_706">Quand vous exécutez la commande <command moreinfo="none">hg status</command>
+    sans aucun argument, elle affiche l'état de l'ensemble de l'arborescence,
+    avec des chemins relatifs partant de la racine du dépôt. Ceci rend
+    difficile de copier un nom de fichier depuis la sortie de la commande
+    <command moreinfo="none">hg status</command> dans une autre ligne de commande. Si vous
+    fournissez un fichier ou un répertoire à la commande <command moreinfo="none">hg
+    status</command>, elle va afficher les chemins relatif depuis votre
+    répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble
+    de l'arborescence à l'aide  de <command moreinfo="none">hg status</command>, avec des
+    chemins relatifs à votre répertoire courant, et non la racine du dépôt,
+    ajoutez la sortie de <command moreinfo="none">hg root</command> à la commande
+    <command moreinfo="none">hg status</command>. Vous pouvez le faire aisément sur un
+    système Unix ainsi :</para>
+
+    <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput></screen>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->
+
+  <!-- BEGIN appB -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:mqref">
+  <?dbhtml filename="mercurial-queues-reference.html"?>
+  <title>Mercurial Queues reference</title>
+
+  <sect1 id="sec:mqref:cmdref">
+    <title>MQ command reference</title>
+
+    <para id="x_5e8">For an overview of the commands provided by MQ, use the
+      command <command role="hg-cmd" moreinfo="none">hg help mq</command>.</para>
+
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qapplied</command>—print
+	applied patches</title>
+
+      <para id="x_5e9">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command
+	prints the current stack of applied patches.  Patches are
+	printed in oldest-to-newest order, so the last patch in the
+	list is the <quote>top</quote> patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qcommit</command>—commit
+	changes in the queue repository</title>
+
+      <para id="x_5ea">The <command role="hg-ext-mq" moreinfo="none">qcommit</command> command
+	commits any outstanding changes in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
+	repository.  This command only works if the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
+	directory is a repository, i.e. you created the directory
+	using <command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
+	ran <command role="hg-cmd" moreinfo="none">hg init</command> in the directory
+	after running <command role="hg-ext-mq" moreinfo="none">qinit</command>.</para>
+
+      <para id="x_5eb">This command is shorthand for <command role="hg-cmd" moreinfo="none">hg
+	  commit --cwd .hg/patches</command>.</para>
+    </sect2>
+    <sect2>
+	<title><command role="hg-ext-mq" moreinfo="none">qdelete</command>—delete a patch
+	from the <filename role="special" moreinfo="none">series</filename>
+	file</title>
+
+      <para id="x_5ec">The <command role="hg-ext-mq" moreinfo="none">qdelete</command> command
+	removes the entry for a patch from the <filename role="special" moreinfo="none">series</filename> file in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
+	directory.  It does not pop the patch if the patch is already
+	applied.  By default, it does not delete the patch file; use
+	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
+	to do that.</para>
+
+      <para id="x_5ed">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5ee"><option role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
+	    patch file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qdiff</command>—print a
+	diff of the topmost applied patch</title>
+
+      <para id="x_5ef">The <command role="hg-ext-mq" moreinfo="none">qdiff</command> command
+	prints a diff of the topmost applied patch. It is equivalent
+	to <command role="hg-cmd" moreinfo="none">hg diff -r-2:-1</command>.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—move
+	applied patches into repository history</title>
+
+      <para id="x_72d">The <command moreinfo="none">hg qfinish</command> command converts the
+	specified applied patches into permanent changes by moving
+	them out of MQ's control so that they will be treated as
+	normal repository history.</para>
+    </sect2>
+
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—merge
+	(<quote>fold</quote>) several patches into one</title>
+
+      <para id="x_5f0">The <command role="hg-ext-mq" moreinfo="none">qfold</command> command
+	merges multiple patches into the topmost applied patch, so
+	that the topmost applied patch makes the union of all of the
+	changes in the patches in question.</para>
+
+      <para id="x_5f1">The patches to fold must not be applied; <command role="hg-ext-mq" moreinfo="none">qfold</command> will exit with an error if
+	any is.  The order in which patches are folded is significant;
+	<command role="hg-cmd" moreinfo="none">hg qfold a b</command> means
+	<quote>apply the current topmost patch, followed by
+	  <literal moreinfo="none">a</literal>, followed by
+	  <literal moreinfo="none">b</literal></quote>.</para>
+
+      <para id="x_5f2">The comments from the folded patches are appended to the
+	comments of the destination patch, with each block of comments
+	separated by three asterisk
+	(<quote><literal moreinfo="none">*</literal></quote>) characters.  Use the
+	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
+	edit the commit message for the combined patch/changeset after
+	the folding has completed.</para>
+
+      <para id="x_5f3">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5f4"><option role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
+	    commit message and patch description for the newly folded
+	    patch.</para>
+	</listitem>
+	<listitem><para id="x_5f5"><option role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
+	    contents of the given file as the new commit message and
+	    patch description for the folded patch.</para>
+	</listitem>
+	<listitem><para id="x_5f6"><option role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
+	    given text as the new commit message and patch description
+	    for the folded patch.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qheader</command>—display the
+	header/description of a patch</title>
+
+      <para id="x_5f7">The <command role="hg-ext-mq" moreinfo="none">qheader</command> command
+	prints the header, or description, of a patch.  By default, it
+	prints the header of the topmost applied patch. Given an
+	argument, it prints the header of the named patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qimport</command>—import
+	a third-party patch into the queue</title>
+
+      <para id="x_5f8">The <command role="hg-ext-mq" moreinfo="none">qimport</command> command
+	adds an entry for an external patch to the <filename role="special" moreinfo="none">series</filename> file, and copies the patch
+	into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory.  It adds
+	the entry immediately after the topmost applied patch, but
+	does not push the patch.</para>
+
+      <para id="x_5f9">If the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
+	repository, <command role="hg-ext-mq" moreinfo="none">qimport</command>
+	automatically does an <command role="hg-cmd" moreinfo="none">hg add</command>
+	of the imported patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qinit</command>—prepare
+	a repository to work with MQ</title>
+
+      <para id="x_5fa">The <command role="hg-ext-mq" moreinfo="none">qinit</command> command
+	prepares a repository to work with MQ.  It creates a directory
+	called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>.</para>
+
+      <para id="x_5fb">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_5fc"><option role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
+	    <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> as a repository
+	    in its own right.  Also creates a <filename role="special" moreinfo="none">.hgignore</filename> file that will
+	    ignore the <filename role="special" moreinfo="none">status</filename>
+	    file.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_5fd">When the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
+	repository, the <command role="hg-ext-mq" moreinfo="none">qimport</command>
+	and <command role="hg-ext-mq" moreinfo="none">qnew</command> commands
+	automatically <command role="hg-cmd" moreinfo="none">hg add</command> new
+	patches.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qnew</command>—create a
+	new patch</title>
+
+      <para id="x_5fe">The <command role="hg-ext-mq" moreinfo="none">qnew</command> command
+	creates a new patch.  It takes one mandatory argument, the
+	name to use for the patch file.  The newly created patch is
+	created empty by default.  It is added to the <filename role="special" moreinfo="none">series</filename> file after the current
+	topmost applied patch, and is immediately pushed on top of
+	that patch.</para>
+
+      <para id="x_5ff">If <command role="hg-ext-mq" moreinfo="none">qnew</command> finds modified
+	files in the working directory, it will refuse to create a new
+	patch unless the <option role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
+	(see below).  This behavior allows you to <command role="hg-ext-mq" moreinfo="none">qrefresh</command> your topmost applied
+	patch before you apply a new patch on top of it.</para>
+
+      <para id="x_600">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_601"><option role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
+	    patch if the contents of the working directory are
+	    modified.  Any outstanding modifications are added to the
+	    newly created patch, so after this command completes, the
+	    working directory will no longer be modified.</para>
+	</listitem>
+	<listitem><para id="x_602"><option role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
+	    text as the commit message. This text will be stored at
+	    the beginning of the patch file, before the patch
+	    data.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qnext</command>—print
+	the name of the next patch</title>
+
+      <para id="x_603">The <command role="hg-ext-mq" moreinfo="none">qnext</command> command
+	prints the name name of the next patch in the <filename role="special" moreinfo="none">series</filename> file after the topmost
+	applied patch.  This patch will become the topmost applied
+	patch if you run <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qpop</command>—pop
+	patches off the stack</title>
+
+      <para id="x_604">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
+	removes applied patches from the top of the stack of applied
+	patches.  By default, it removes only one patch.</para>
+
+      <para id="x_605">This command removes the changesets that represent the
+	popped patches from the repository, and updates the working
+	directory to undo the effects of the patches.</para>
+
+      <para id="x_606">This command takes an optional argument, which it uses as
+	the name or index of the patch to pop to.  If given a name, it
+	will pop patches until the named patch is the topmost applied
+	patch.  If given a number, <command role="hg-ext-mq" moreinfo="none">qpop</command> treats the number as an
+	index into the entries in the series file, counting from zero
+	(empty lines and lines containing only comments do not count).
+	It pops patches until the patch identified by the given index
+	is the topmost applied patch.</para>
+
+      <para id="x_607">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command does
+	not read or write patches or the <filename role="special" moreinfo="none">series</filename> file.  It is thus safe to
+	<command role="hg-ext-mq" moreinfo="none">qpop</command> a patch that you have
+	removed from the <filename role="special" moreinfo="none">series</filename>
+	file, or a patch that you have renamed or deleted entirely.
+	In the latter two cases, use the name of the patch as it was
+	when you applied it.</para>
+
+      <para id="x_608">By default, the <command role="hg-ext-mq" moreinfo="none">qpop</command>
+	command will not pop any patches if the working directory has
+	been modified.  You can override this behavior using the
+	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
+	which reverts all modifications in the working
+	directory.</para>
+
+      <para id="x_609">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_60a"><option role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
+	    applied patches.  This returns the repository to its state
+	    before you applied any patches.</para>
+	</listitem>
+	<listitem><para id="x_60b"><option role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
+	    revert any modifications to the working directory when
+	    popping.</para>
+	</listitem>
+	<listitem><para id="x_60c"><option role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
+	    from the named queue.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_60d">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
+	removes one line from the end of the <filename role="special" moreinfo="none">status</filename> file for each patch that it
+	pops.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qprev</command>—print
+	the name of the previous patch</title>
+
+      <para id="x_60e">The <command role="hg-ext-mq" moreinfo="none">qprev</command> command
+	prints the name of the patch in the <filename role="special" moreinfo="none">series</filename> file that comes before the
+	topmost applied patch. This will become the topmost applied
+	patch if you run <command role="hg-ext-mq" moreinfo="none">qpop</command>.</para>
+
+    </sect2>
+    <sect2 id="sec:mqref:cmd:qpush">
+      <title><command role="hg-ext-mq" moreinfo="none">qpush</command>—push
+	patches onto the stack</title>
+
+      <para id="x_60f">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command adds
+	patches onto the applied stack.  By default, it adds only one
+	patch.</para>
+
+      <para id="x_610">This command creates a new changeset to represent each
+	applied patch, and updates the working directory to apply the
+	effects of the patches.</para>
+
+      <para id="x_611">The default data used when creating a changeset are as
+	follows:</para>
+      <itemizedlist>
+	<listitem><para id="x_612">The commit date and time zone are the current
+	    date and time zone.  Because these data are used to
+	    compute the identity of a changeset, this means that if
+	    you <command role="hg-ext-mq" moreinfo="none">qpop</command> a patch and
+	    <command role="hg-ext-mq" moreinfo="none">qpush</command> it again, the
+	    changeset that you push will have a different identity
+	    than the changeset you popped.</para>
+	</listitem>
+	<listitem><para id="x_613">The author is the same as the default used by
+	    the <command role="hg-cmd" moreinfo="none">hg commit</command>
+	    command.</para>
+	</listitem>
+	<listitem><para id="x_614">The commit message is any text from the patch
+	    file that comes before the first diff header.  If there is
+	    no such text, a default commit message is used that
+	    identifies the name of the patch.</para>
+	</listitem></itemizedlist>
+      <para id="x_615">If a patch contains a Mercurial patch header,
+	the information in the patch header overrides these
+	defaults.</para>
+
+      <para id="x_616">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_617"><option role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
+	    unapplied patches from the <filename role="special" moreinfo="none">series</filename> file until there are
+	    none left to push.</para>
+	</listitem>
+	<listitem><para id="x_618"><option role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
+	    of the patch to the end of the commit message.</para>
+	</listitem>
+	<listitem><para id="x_619"><option role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
+	    fails to apply cleanly, use the entry for the patch in
+	    another saved queue to compute the parameters for a
+	    three-way merge, and perform a three-way merge using the
+	    normal Mercurial merge machinery.  Use the resolution of
+	    the merge as the new patch content.</para>
+	</listitem>
+	<listitem><para id="x_61a"><option role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
+	    named queue if merging while pushing.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_61b">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command
+	reads, but does not modify, the <filename role="special" moreinfo="none">series</filename> file.  It appends one line
+	to the <command role="hg-cmd" moreinfo="none">hg status</command> file for
+	each patch that it pushes.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qrefresh</command>—update the
+	topmost applied patch</title>
+
+      <para id="x_61c">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
+	updates the topmost applied patch.  It modifies the patch,
+	removes the old changeset that represented the patch, and
+	creates a new changeset to represent the modified
+	patch.</para>
+
+      <para id="x_61d">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
+	looks for the following modifications:</para>
+      <itemizedlist>
+	<listitem><para id="x_61e">Changes to the commit message, i.e. the text
+	    before the first diff header in the patch file, are
+	    reflected in the new changeset that represents the
+	    patch.</para>
+	</listitem>
+	<listitem><para id="x_61f">Modifications to tracked files in the working
+	    directory are added to the patch.</para>
+	</listitem>
+	<listitem><para id="x_620">Changes to the files tracked using <command role="hg-cmd" moreinfo="none">hg add</command>, <command role="hg-cmd" moreinfo="none">hg copy</command>, <command role="hg-cmd" moreinfo="none">hg remove</command>, or <command role="hg-cmd" moreinfo="none">hg rename</command>.  Added files and copy
+	    and rename destinations are added to the patch, while
+	    removed files and rename sources are removed.</para>
+	</listitem></itemizedlist>
+
+      <para id="x_621">Even if <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
+	detects no changes, it still recreates the changeset that
+	represents the patch.  This causes the identity of the
+	changeset to differ from the previous changeset that
+	identified the patch.</para>
+
+      <para id="x_622">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_623"><option role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
+	    the commit and patch description, using the preferred text
+	    editor.</para>
+	</listitem>
+	<listitem><para id="x_624"><option role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
+	    the commit message and patch description, using the given
+	    text.</para>
+	</listitem>
+	<listitem><para id="x_625"><option role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
+	    the commit message and patch description, using text from
+	    the given file.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qrename</command>—rename
+	a patch</title>
+
+      <para id="x_626">The <command role="hg-ext-mq" moreinfo="none">qrename</command> command
+	renames a patch, and changes the entry for the patch in the
+	<filename role="special" moreinfo="none">series</filename> file.</para>
+
+      <para id="x_627">With a single argument, <command role="hg-ext-mq" moreinfo="none">qrename</command> renames the topmost
+	applied patch.  With two arguments, it renames its first
+	argument to its second.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qseries</command>—print
+	the entire patch series</title>
+
+      <para id="x_62a">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command
+	prints the entire patch series from the <filename role="special" moreinfo="none">series</filename> file.  It prints only patch
+	names, not empty lines or comments.  It prints in order from
+	first to be applied to last.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qtop</command>—print the
+	name of the current patch</title>
+
+      <para id="x_62b">The <command role="hg-ext-mq" moreinfo="none">qtop</command> prints the
+	name of the topmost currently applied patch.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-ext-mq" moreinfo="none">qunapplied</command>—print patches
+	not yet applied</title>
+
+      <para id="x_62c">The <command role="hg-ext-mq" moreinfo="none">qunapplied</command> command
+	prints the names of patches from the <filename role="special" moreinfo="none">series</filename> file that are not yet
+	applied.  It prints them in order from the next patch that
+	will be pushed to the last.</para>
+
+    </sect2>
+    <sect2>
+      <title><command role="hg-cmd" moreinfo="none">hg strip</command>—remove a
+	revision and descendants</title>
+
+      <para id="x_62d">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
+	removes a revision, and all of its descendants, from the
+	repository.  It undoes the effects of the removed revisions
+	from the repository, and updates the working directory to the
+	first parent of the removed revision.</para>
+
+      <para id="x_62e">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
+	saves a backup of the removed changesets in a bundle, so that
+	they can be reapplied if removed in error.</para>
+
+      <para id="x_62f">Options:</para>
+      <itemizedlist>
+	<listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
+	    unrelated changesets that are intermixed with the stripped
+	    changesets in the backup bundle.</para>
+	</listitem>
+	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
+	    branch has multiple heads, remove all heads.</para>
+	</listitem>
+	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
+	    not save a backup bundle.</para>
+	</listitem></itemizedlist>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>MQ file reference</title>
+
+    <sect2>
+      <title>The <filename role="special" moreinfo="none">series</filename>
+	file</title>
+
+      <para id="x_633">The <filename role="special" moreinfo="none">series</filename> file
+	contains a list of the names of all patches that MQ can apply.
+	It is represented as a list of names, with one name saved per
+	line.  Leading and trailing white space in each line are
+	ignored.</para>
+
+      <para id="x_634">Lines may contain comments.  A comment begins with the
+	<quote><literal moreinfo="none">#</literal></quote> character, and extends to
+	the end of the line.  Empty lines, and lines that contain only
+	comments, are ignored.</para>
+
+      <para id="x_635">You will often need to edit the <filename role="special" moreinfo="none">series</filename> file by hand, hence the
+	support for comments and empty lines noted above.  For
+	example, you can comment out a patch temporarily, and <command role="hg-ext-mq" moreinfo="none">qpush</command> will skip over that patch
+	when applying patches.  You can also change the order in which
+	patches are applied by reordering their entries in the
+	<filename role="special" moreinfo="none">series</filename> file.</para>
+
+      <para id="x_636">Placing the <filename role="special" moreinfo="none">series</filename>
+	file under revision control is also supported; it is a good
+	idea to place all of the patches that it refers to under
+	revision control, as well.  If you create a patch directory
+	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
+	option to <command role="hg-ext-mq" moreinfo="none">qinit</command>, this will
+	be done for you automatically.</para>
+
+    </sect2>
+    <sect2>
+      <title>The <filename role="special" moreinfo="none">status</filename>
+	file</title>
+
+      <para id="x_637">The <filename role="special" moreinfo="none">status</filename> file
+	contains the names and changeset hashes of all patches that MQ
+	currently has applied.  Unlike the <filename role="special" moreinfo="none">series</filename> file, this file is not
+	intended for editing.  You should not place this file under
+	revision control, or modify it in any way.  It is used by MQ
+	strictly for internal book-keeping.</para>
+
+    </sect2>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->
+
+  <!-- BEGIN appC -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="chap:srcinstall">
+  <?dbhtml filename="installing-mercurial-from-source.html"?>
+  <title>Installer Mercurial à partir des sources</title>
+
+  <sect1 id="sec:srcinstall:unixlike">
+    <title>Pour un système Unix ou similaire</title>
+
+    <para id="x_5e0">Si vous utilisez un système Unix ou similaire, pour lequel
+      une version récente de Python (2.3 ou plus) est disponible, l'installation
+      de Mercurial à partir des sources est simple.</para>
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_5e1">Téléchargez un paquet récent depuis <ulink url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
+      </listitem>
+      <listitem><para id="x_5e2">Extrayez le paquet : </para>
+	<programlisting format="linespecific">gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
+      </listitem>
+      <listitem><para id="x_5e3">Allez dans le répertoires où les sources ont
+    été extraites et exécutez le script d'installation. Ce dernier compilera
+    Mercurial et l'installera dans votre répertoire utilisateur.</para>
+	<programlisting format="linespecific">cd mercurial-MYVERSION
+python setup.py install --force --home=$HOME</programlisting>
+      </listitem>
+    </orderedlist>
+    <para id="x_5e4">Lorsque l'installation est terminée, Mercurial se
+      trouvera dans le répertoire <literal moreinfo="none">bin</literal> de votre répertoire
+      utilisateur.
+      N'oubliez pas de vérifier que ce répertoire se trouve dans la liste
+      des répertoires où votre shell recherche les exécutables.</para>
+
+    <para id="x_5e5">Vous devrez vraisemblablement définir la variable
+      d'environnement <envar>PYTHONPATH</envar> de manière à ce que
+      l'exécutable de Mercurial puisse trouver le reste des paquets logiciels.
+      Par exemple, sur mon ordinateur portable, je dois le définir ainsi:
+      <literal moreinfo="none">/home/bos/lib/python</literal>. Le chemin exact à utiliser
+      dépendra de la manière dont Python aura été construit pour votre 
+      système. Il ne devrait pas être difficile de le trouver. En cas de
+      doute, lisez le texte généré lors de l'installation ci-dessus, et
+      recherchez l'emplacement où le contenu du répertoire
+      <literal moreinfo="none">mercurial</literal> a été installé.</para>
+
+  </sect1>
+  <sect1>
+    <title>Pour Windows</title>
+
+    <para id="x_5e6">Construire et installer Mercurial sous Windows nécessite
+      des outils logiciels divers, une certaine connaissance technique et une
+      bonne dose de patience. Je vous <emphasis>déconseille fortement</emphasis> 
+      de tenter de le faire si vous êtes un <quote>simple utilisateur</quote>.
+      A moins que vous n'ayez l'intention de "hacker" Mercurial, je vous
+      suggère d'avoir recours à un paquet d'installation de la version binaire.</para>
+
+    <para id="x_5e7">Si vous avez vraiment l'intention de construire
+      Mercurial à partir des sources sous Windows, suivez les indications pour 
+      ce <quote>chemin laborieux</quote> sur le wiki de Mercurial : <ulink url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, 
+      et préparez vous à un travail épineux.</para>
+
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->
+
+  <!-- BEGIN appD -->
+  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="cha:opl">
+  <?dbhtml filename="open-publication-license.html"?>
+  <title>Open Publication License</title>
+
+  <para id="x_638">Version 1.0, 8 June 1999</para>
+
+  <sect1>
+    <title>Requirements on both unmodified and modified
+      versions</title>
+
+    <para id="x_639">The Open Publication works may be reproduced and distributed
+      in whole or in part, in any medium physical or electronic,
+      provided that the terms of this license are adhered to, and that
+      this license or an incorporation of it by reference (with any
+      options elected by the author(s) and/or publisher) is displayed
+      in the reproduction.</para>
+
+    <para id="x_63a">Proper form for an incorporation by reference is as
+      follows:</para>
+
+    <blockquote>
+      <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
+	<emphasis>author's name or designee</emphasis>. This material
+	may be distributed only subject to the terms and conditions
+	set forth in the Open Publication License,
+	v<emphasis>x.y</emphasis> or later (the latest version is
+	presently available at <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
+    </blockquote>
+
+    <para id="x_63c">The reference must be immediately followed with any options
+      elected by the author(s) and/or publisher of the document (see
+      <xref linkend="sec:opl:options"/>).</para>
+
+    <para id="x_63d">Commercial redistribution of Open Publication-licensed
+      material is permitted.</para>
+
+    <para id="x_63e">Any publication in standard (paper) book form shall require
+      the citation of the original publisher and author. The publisher
+      and author's names shall appear on all outer surfaces of the
+      book. On all outer surfaces of the book the original publisher's
+      name shall be as large as the title of the work and cited as
+      possessive with respect to the title.</para>
+
+  </sect1>
+  <sect1>
+    <title>Copyright</title>
+
+    <para id="x_63f">The copyright to each Open Publication is owned by its
+      author(s) or designee.</para>
+
+  </sect1>
+  <sect1>
+    <title>Scope of license</title>
+
+    <para id="x_640">The following license terms apply to all Open Publication
+      works, unless otherwise explicitly stated in the
+      document.</para>
+
+    <para id="x_641">Mere aggregation of Open Publication works or a portion of
+      an Open Publication work with other works or programs on the
+      same media shall not cause this license to apply to those other
+      works. The aggregate work shall contain a notice specifying the
+      inclusion of the Open Publication material and appropriate
+      copyright notice.</para>
+
+    <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
+      of this license is found to be unenforceable in any
+      jurisdiction, the remaining portions of the license remain in
+      force.</para>
+
+    <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
+      Publication works are licensed and provided <quote>as is</quote>
+      without warranty of any kind, express or implied, including, but
+      not limited to, the implied warranties of merchantability and
+      fitness for a particular purpose or a warranty of
+      non-infringement.</para>
+
+  </sect1>
+  <sect1>
+    <title>Requirements on modified works</title>
+
+    <para id="x_644">All modified versions of documents covered by this license,
+      including translations, anthologies, compilations and partial
+      documents, must meet the following requirements:</para>
+
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_645">The modified version must be labeled as
+	  such.</para>
+      </listitem>
+      <listitem><para id="x_646">The person making the modifications must be
+	  identified and the modifications dated.</para>
+      </listitem>
+      <listitem><para id="x_647">Acknowledgement of the original author and
+	  publisher if applicable must be retained according to normal
+	  academic citation practices.</para>
+      </listitem>
+      <listitem><para id="x_648">The location of the original unmodified document
+	  must be identified.</para>
+      </listitem>
+      <listitem><para id="x_649">The original author's (or authors') name(s) may
+	  not be used to assert or imply endorsement of the resulting
+	  document without the original author's (or authors')
+	  permission.</para>
+      </listitem></orderedlist>
+
+  </sect1>
+  <sect1>
+    <title>Good-practice recommendations</title>
+
+    <para id="x_64a">In addition to the requirements of this license, it is
+      requested from and strongly recommended of redistributors
+      that:</para>
+
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_64b">If you are distributing Open Publication works
+	  on hardcopy or CD-ROM, you provide email notification to the
+	  authors of your intent to redistribute at least thirty days
+	  before your manuscript or media freeze, to give the authors
+	  time to provide updated documents. This notification should
+	  describe modifications, if any, made to the document.</para>
+      </listitem>
+      <listitem><para id="x_64c">All substantive modifications (including
+	  deletions) be either clearly marked up in the document or
+	  else described in an attachment to the document.</para>
+      </listitem>
+      <listitem><para id="x_64d">Finally, while it is not mandatory under this
+	  license, it is considered good form to offer a free copy of
+	  any hardcopy and CD-ROM expression of an Open
+	  Publication-licensed work to its author(s).</para>
+      </listitem></orderedlist>
+
+  </sect1>
+  <sect1 id="sec:opl:options">
+    <title>License options</title>
+
+    <para id="x_64e">The author(s) and/or publisher of an Open
+      Publication-licensed document may elect certain options by
+      appending language to the reference to or copy of the license.
+      These options are considered part of the license instance and
+      must be included with the license (or its incorporation by
+      reference) in derived works.</para>
+
+    <orderedlist inheritnum="ignore" continuation="restarts">
+      <listitem><para id="x_64f">To prohibit distribution of substantively
+	  modified versions without the explicit permission of the
+	  author(s). <quote>Substantive modification</quote> is
+	  defined as a change to the semantic content of the document,
+	  and excludes mere changes in format or typographical
+	  corrections.</para>
+      </listitem>
+      <listitem><para id="x_650">  To accomplish this, add the phrase
+	  <quote>Distribution of substantively modified versions of
+	    this document is prohibited without the explicit
+	    permission of the copyright holder.</quote> to the license
+	  reference or copy.</para>
+      </listitem>
+      <listitem><para id="x_651">To prohibit any publication of this work or
+	  derivative works in whole or in part in standard (paper)
+	  book form for commercial purposes is prohibited unless prior
+	  permission is obtained from the copyright holder.</para>
+      </listitem>
+      <listitem><para id="x_652">To accomplish this, add the phrase
+	  <quote>Distribution of the work or derivative of the work in
+	    any standard (paper) book form is prohibited unless prior
+	    permission is obtained from the copyright holder.</quote>
+	  to the license reference or copy.</para>
+      </listitem></orderedlist>
+
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->
+
+</book>